From fc8667a2c295cbd2cfc812ccb2404cf4e43494c0 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sun, 8 Nov 2026 08:04:45 -0500 Subject: [PATCH 1/3] =?UTF-8?q?=E2=9C=A8=20crux:=20human=20gate=20service?= =?UTF-8?q?=20(S3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- changelog.d/added-crux-gates-s3.md | 1 + src/crux/api/gates.go | 161 ++++++++++++ src/crux/api/gates_test.go | 17 ++ src/crux/cli/cli.go | 7 + src/crux/cli/gate.go | 236 ++++++++++++++++++ src/crux/cli/gate_test.go | 136 ++++++++++ src/crux/cli/remote.go | 2 + src/crux/cli/serve.go | 10 + src/crux/cli/verbs_test.go | 4 +- src/crux/gates/gates.go | 230 +++++++++++++++++ src/crux/gates/gates_test.go | 344 ++++++++++++++++++++++++++ src/crux/gates/request.go | 145 +++++++++++ src/crux/gates/service.go | 227 +++++++++++++++++ src/crux/gates/store.go | 182 ++++++++++++++ src/crux/gates/wait.go | 151 +++++++++++ src/crux/serve/gates.go | 236 ++++++++++++++++++ src/crux/serve/gates_test.go | 224 +++++++++++++++++ src/crux/serve/serve.go | 6 + src/docs/crux-serve.md | 2 + src/docs/design/crux-work-services.md | 89 ++++++- 20 files changed, 2407 insertions(+), 3 deletions(-) create mode 100644 changelog.d/added-crux-gates-s3.md create mode 100644 src/crux/api/gates.go create mode 100644 src/crux/api/gates_test.go create mode 100644 src/crux/cli/gate.go create mode 100644 src/crux/cli/gate_test.go create mode 100644 src/crux/gates/gates.go create mode 100644 src/crux/gates/gates_test.go create mode 100644 src/crux/gates/request.go create mode 100644 src/crux/gates/service.go create mode 100644 src/crux/gates/store.go create mode 100644 src/crux/gates/wait.go create mode 100644 src/crux/serve/gates.go create mode 100644 src/crux/serve/gates_test.go diff --git a/changelog.d/added-crux-gates-s3.md b/changelog.d/added-crux-gates-s3.md new file mode 100644 index 0000000000..90ae4c18ed --- /dev/null +++ b/changelog.d/added-crux-gates-s3.md @@ -0,0 +1 @@ +- crux: human gates, the third work service of the Crux work-services RFC ([hivecommons/crux#114](https://github.com/hivecommons/crux/issues/114) S3). A driver opens a gate with `POST /v1/gates` (or `crux --server … gate open`) and a person answers it with `crux gate answer --choice approve` or `POST /v1/gates/{id}/answer`. Answers must be one of the offered choices, and any free text goes in a separate note. The record keeps both who opened the gate and who answered it. An opener answering its own gate needs the explicit, audited `--as-operator` override. Gates are stored under `/gates` (`pending/`, `resolved/` and a `gates.jsonl` journal), so they survive a `crux serve` restart. Re-opening the same gate returns the same id and the recorded answer. A gate that times out is marked `expired`, which is neither approval nor denial. `GET /v1/gates/{id}/wait` and `crux gate wait` block until the gate is answered or expires, and `gate.opened`, `gate.answered` and `gate.expired` events appear on `/v1/events`. diff --git a/src/crux/api/gates.go b/src/crux/api/gates.go new file mode 100644 index 0000000000..3e5f517a2f --- /dev/null +++ b/src/crux/api/gates.go @@ -0,0 +1,161 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "net/url" + "time" +) + +// Human gates (hivecommons/crux#114 S3): a driver asks a person to decide +// something before it continues; a person answers from the CLI or the API. +// +// POST /v1/gates open (idempotent: the same request from the +// same principal returns the same gate) +// GET /v1/gates[?status=] list (a project sees only gates it opened) +// GET /v1/gates/{id} poll +// POST /v1/gates/{id}/answer answer with one of the gate's choices +// GET /v1/gates/{id}/wait long-poll (?timeout=, bounded server-side) +// +// The family admits project principals (to open, read and wait on their own +// gates); only the operator answers. +const PathGates = "/" + Version + "/gates" + +// GatePath is the route of one gate. +func GatePath(id string) string { return PathGates + "/" + url.PathEscape(id) } + +// GateAnswerPath is the route that answers one gate. +func GateAnswerPath(id string) string { return GatePath(id) + "/answer" } + +// GateWaitPath is the long-poll route of one gate. +func GateWaitPath(id string) string { return GatePath(id) + "/wait" } + +// Gate statuses, the closed set every record reports. Expired is neither +// approval nor denial. +const ( + GateWaiting = "waiting" + GateAnswered = "answered" + GateExpired = "expired" +) + +// Gate error codes. +const ( + // CodeGateContextTooLarge is a context payload over 64 KiB once + // encoded (413). + CodeGateContextTooLarge = "gate_context_too_large" + // CodeGateInvalidChoice is an answer that is not one of the gate's + // choices (422); free text belongs in note. + CodeGateInvalidChoice = "gate_invalid_choice" + // CodeGateSelfAnswer is the opener answering its own gate without + // as_operator (403). + CodeGateSelfAnswer = "gate_self_answer" + // CodeGateClosed is an answer to a gate that is already answered + // differently or expired (409). + CodeGateClosed = "gate_closed" +) + +// Gate events on /v1/events; Data is the Gate without its context. +const ( + EventGateOpened = "gate.opened" + EventGateAnswered = "gate.answered" + EventGateExpired = "gate.expired" +) + +// GateRequest is the body of POST /v1/gates. +type GateRequest struct { + Subject string `json:"subject"` + // Context is a driver-defined JSON payload, at most 64 KiB encoded. + Context json.RawMessage `json:"context,omitempty"` + // Choices defaults to ["approve","deny"]. + Choices []string `json:"choices,omitempty"` + // Timeout is a Go duration; "" or "0" waits indefinitely. + Timeout string `json:"timeout,omitempty"` + // OpenedBy is the driver's own label; the authenticated principal is + // recorded beside it as opened_by_principal. + OpenedBy string `json:"opened_by,omitempty"` + // IdempotencyKey, when set, identifies the gate instead of its contents. + IdempotencyKey string `json:"idempotency_key,omitempty"` +} + +// Gate is one gate record: the response of every gate route. +type Gate struct { + ID string `json:"id"` + Status string `json:"status"` + Subject string `json:"subject"` + Context json.RawMessage `json:"context,omitempty"` + Choices []string `json:"choices"` + Timeout string `json:"timeout"` + OpenedBy string `json:"opened_by"` + OpenedByPrincipal string `json:"opened_by_principal"` + OpenedAt time.Time `json:"opened_at"` + ExpiresAt *time.Time `json:"expires_at,omitempty"` + Answer string `json:"answer,omitempty"` + AnsweredBy string `json:"answered_by,omitempty"` + AnsweredByPrincipal string `json:"answered_by_principal,omitempty"` + AnsweredAt *time.Time `json:"answered_at,omitempty"` + Note string `json:"note,omitempty"` + OperatorOverride bool `json:"operator_override,omitempty"` + ExpiredAt *time.Time `json:"expired_at,omitempty"` +} + +// GateList is the response of GET /v1/gates. +type GateList struct { + Gates []Gate `json:"gates"` +} + +// GateAnswerRequest is the body of POST /v1/gates/{id}/answer. +type GateAnswerRequest struct { + // Answer must be one of the gate's choices. + Answer string `json:"answer"` + // Note is free text recorded beside the answer. + Note string `json:"note,omitempty"` + // AsOperator is the explicit, audited override that lets the principal + // that opened the gate answer it. + AsOperator bool `json:"as_operator,omitempty"` +} + +// OpenGate is POST /v1/gates. +func (c *Client) OpenGate(ctx context.Context, in GateRequest) (Gate, error) { + var out Gate + err := c.do(ctx, http.MethodPost, PathGates, in, &out) + return out, err +} + +// ListGates is GET /v1/gates[?status=]. +func (c *Client) ListGates(ctx context.Context, status string) ([]Gate, error) { + path := PathGates + if status != "" { + path += "?status=" + url.QueryEscape(status) + } + var out GateList + err := c.do(ctx, http.MethodGet, path, nil, &out) + return out.Gates, err +} + +// GetGate is GET /v1/gates/{id}. +func (c *Client) GetGate(ctx context.Context, id string) (Gate, error) { + var out Gate + err := c.do(ctx, http.MethodGet, GatePath(id), nil, &out) + return out, err +} + +// AnswerGate is POST /v1/gates/{id}/answer. +func (c *Client) AnswerGate(ctx context.Context, id string, in GateAnswerRequest) (Gate, error) { + var out Gate + err := c.do(ctx, http.MethodPost, GateAnswerPath(id), in, &out) + return out, err +} + +// WaitGate is one GET /v1/gates/{id}/wait: it returns when the gate is +// answered or expired, or when the server's poll window (timeout, zero for +// the server default) closes with the gate still waiting. +func (c *Client) WaitGate(ctx context.Context, id string, timeout time.Duration) (Gate, error) { + path := GateWaitPath(id) + if timeout > 0 { + path += "?timeout=" + url.QueryEscape(timeout.String()) + } + var out Gate + err := c.do(ctx, http.MethodGet, path, nil, &out) + return out, err +} diff --git a/src/crux/api/gates_test.go b/src/crux/api/gates_test.go new file mode 100644 index 0000000000..a70c0ca832 --- /dev/null +++ b/src/crux/api/gates_test.go @@ -0,0 +1,17 @@ +package api + +import "testing" + +func TestGatePathsAndCodes(t *testing.T) { + if PathGates != "/v1/gates" || GatePath("gate_a") != "/v1/gates/gate_a" || + GateAnswerPath("gate_a") != "/v1/gates/gate_a/answer" || GateWaitPath("gate_a") != "/v1/gates/gate_a/wait" { + t.Fatalf("paths: %s %s %s %s", PathGates, GatePath("gate_a"), GateAnswerPath("gate_a"), GateWaitPath("gate_a")) + } + seen := map[string]bool{CodeRuntime: true, CodeBadRequest: true, CodeForbidden: true, CodeConflict: true, CodeTooLarge: true} + for _, code := range []string{CodeGateContextTooLarge, CodeGateInvalidChoice, CodeGateSelfAnswer, CodeGateClosed} { + if seen[code] { + t.Fatalf("gate code %q overloads an existing code", code) + } + seen[code] = true + } +} diff --git a/src/crux/cli/cli.go b/src/crux/cli/cli.go index 2ef01ed3d7..9026d92e74 100644 --- a/src/crux/cli/cli.go +++ b/src/crux/cli/cli.go @@ -214,6 +214,11 @@ func (e *Env) dispatch(ctx context.Context, opts globalOptions, name string, arg // in-process form, so the verb is only reachable with --server. fmt.Fprintln(e.Stderr, "crux: runs needs --server ADDR (or CRUX_SERVER); contained runs execute on a crux serve") return ExitUsage + case "gate": + // Gates are recorded, journaled and announced by a `crux serve`; + // there is no in-process form. + fmt.Fprintln(e.Stderr, "crux: gate needs --server ADDR (or CRUX_SERVER); gates are kept by a crux serve") + return ExitUsage case "help", "-h", "--help": fs := flag.NewFlagSet("crux", flag.ContinueOnError) e.usage(fs) @@ -351,6 +356,8 @@ Work services (no runtime; hivecommons/crux#114): checkout add|rm|list pinned checkouts under /checkouts (add -repo URL -commit SHA; -allow PREFIXES or $CRUX_CHECKOUT_ALLOWLIST gates which repos) + gate open|list|answer|wait human gates on a crux serve (--server only; + 'crux gate help' for flags) While 'crux run' is in the foreground it serves /crux.sock; ps, logs, kick and stop use that socket when present so they act on the live runtime. diff --git a/src/crux/cli/gate.go b/src/crux/cli/gate.go new file mode 100644 index 0000000000..0233fe8bed --- /dev/null +++ b/src/crux/cli/gate.go @@ -0,0 +1,236 @@ +package cli + +import ( + "context" + "encoding/json" + "errors" + "flag" + "fmt" + "strings" + "text/tabwriter" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/config" +) + +// `crux gate open|list|answer|wait` is the human-gate work service +// (hivecommons/crux#114 S3). It does not touch crux.Runtime and, like +// `runs`, exists only against a `crux serve`: the server is the one +// authority that records who opened and who answered, journals the +// decision and publishes gate.* events, so a second in-process writer on +// the same work dir would undercut all three. + +const gateUsage = `usage: crux --server ADDR gate open --subject S [--choice C]… [--timeout D] [--context JSON] [--opened-by L] [--idempotency-key K] [--json] + crux --server ADDR gate list [--status waiting|answered|expired] [--json] + crux --server ADDR gate answer --choice C [--note TEXT] [--as-operator] [--json] + crux --server ADDR gate wait [--timeout D] [--json] + +open prints the gate id; choices default to approve and deny, and timeout +0 (the default) waits indefinitely. answer records one of the offered +choices as the operator; --as-operator is the audited override that lets +the principal that opened a gate answer it. wait blocks until the gate is +answered (prints the answer, exit 0) or expires (exit 1, nothing printed): +expiry is neither approval nor denial.` + +// remoteGate is `crux --server … gate`. +func (e *Env) remoteGate(ctx context.Context, c *api.Client, args []string) int { + if len(args) == 0 { + fmt.Fprintln(e.Stderr, gateUsage) + return ExitUsage + } + switch args[0] { + case "open": + return e.remoteGateOpen(ctx, c, args[1:]) + case "list": + return e.remoteGateList(ctx, c, args[1:]) + case "answer": + return e.remoteGateAnswer(ctx, c, args[1:]) + case "wait": + return e.remoteGateWait(ctx, c, args[1:]) + case "help", "-h", "--help": + fmt.Fprintln(e.Stderr, gateUsage) + return ExitOK + default: + fmt.Fprintf(e.Stderr, "crux: gate: unknown subcommand %q\n%s\n", args[0], gateUsage) + return ExitUsage + } +} + +func (e *Env) remoteGateOpen(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("gate open") + var req api.GateRequest + var choices stringList + var payload string + fs.StringVar(&req.Subject, "subject", "", "what the person is asked to decide") + fs.Var(&choices, "choice", "an answer the person may give (repeatable; default approve, deny)") + fs.StringVar(&req.Timeout, "timeout", "0", "how long the gate waits, e.g. 24h; 0 waits indefinitely") + fs.StringVar(&payload, "context", "", "JSON payload shown beside the subject (at most 64 KiB)") + fs.StringVar(&req.OpenedBy, "opened-by", "", "the driver's own label (default: the caller)") + fs.StringVar(&req.IdempotencyKey, "idempotency-key", "", "identify the gate by this key instead of its contents") + asJSON := fs.Bool("json", false, "print the record as JSON") + if code, ok := parseSub(fs, args); !ok { + return code + } + if strings.TrimSpace(req.Subject) == "" || fs.NArg() != 0 { + fmt.Fprintln(e.Stderr, gateUsage) + return ExitUsage + } + if payload != "" { + if !json.Valid([]byte(payload)) { + fmt.Fprintln(e.Stderr, "crux: gate open: --context is not valid JSON") + return ExitUsage + } + req.Context = json.RawMessage(payload) + } + req.Choices = choices + g, err := c.OpenGate(ctx, req) + if err != nil { + return e.gateErr("open", err) + } + if *asJSON { + return e.writeJSON(g) + } + fmt.Fprintf(e.Stdout, "%s\t%s\n", g.ID, g.Status) + return ExitOK +} + +func (e *Env) remoteGateList(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("gate list") + status := fs.String("status", "", "only gates in this status: waiting, answered or expired") + asJSON := fs.Bool("json", false, "print a JSON array instead of a table") + if code, ok := parseSub(fs, args); !ok { + return code + } + if fs.NArg() != 0 { + fmt.Fprintln(e.Stderr, gateUsage) + return ExitUsage + } + list, err := c.ListGates(ctx, *status) + if err != nil { + return e.gateErr("list", err) + } + if *asJSON { + return e.writeJSON(list) + } + tw := tabwriter.NewWriter(e.Stdout, 0, 0, 2, ' ', 0) + fmt.Fprintln(tw, "ID\tSTATUS\tOPENED BY\tOPENED\tANSWER\tCHOICES\tSUBJECT") + for _, g := range list { + answer := "-" + if g.Answer != "" { + answer = g.Answer + " (" + g.AnsweredBy + ")" + } + fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n", g.ID, g.Status, g.OpenedByPrincipal, g.OpenedAt.UTC().Format(time.RFC3339), answer, strings.Join(g.Choices, "|"), g.Subject) + } + if err := tw.Flush(); err != nil { + fmt.Fprintln(e.Stderr, "crux:", err) + return ExitError + } + return ExitOK +} + +func (e *Env) remoteGateAnswer(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("gate answer") + var in api.GateAnswerRequest + fs.StringVar(&in.Answer, "choice", "", "one of the gate's choices") + fs.StringVar(&in.Note, "note", "", "free text recorded beside the choice") + fs.BoolVar(&in.AsOperator, "as-operator", false, "audited override: answer a gate this principal opened") + asJSON := fs.Bool("json", false, "print the record as JSON") + id, code, ok := parseWithID(fs, args) + if !ok { + return code + } + if id == "" || in.Answer == "" { + fmt.Fprintln(e.Stderr, gateUsage) + return ExitUsage + } + g, err := c.AnswerGate(ctx, id, in) + if err != nil { + return e.gateErr("answer", err) + } + if *asJSON { + return e.writeJSON(g) + } + fmt.Fprintf(e.Stdout, "%s\t%s\t%s\n", g.ID, g.Status, g.Answer) + return ExitOK +} + +// remoteGateWait polls the long-poll route until the gate leaves waiting +// or --timeout passes; each poll is bounded server-side. +func (e *Env) remoteGateWait(ctx context.Context, c *api.Client, args []string) int { + fs := e.subFlags("gate wait") + timeout := fs.Duration("timeout", 0, "give up after this long (default: wait indefinitely)") + asJSON := fs.Bool("json", false, "print the record as JSON") + id, code, ok := parseWithID(fs, args) + if !ok { + return code + } + if id == "" { + fmt.Fprintln(e.Stderr, gateUsage) + return ExitUsage + } + if *timeout > 0 { + var cancel context.CancelFunc + ctx, cancel = context.WithTimeout(ctx, *timeout) + defer cancel() + } + for { + g, err := c.WaitGate(ctx, id, 0) + if err != nil { + if ctx.Err() != nil { + fmt.Fprintf(e.Stderr, "crux: gate wait: %s is still waiting\n", id) + return ExitError + } + return e.gateErr("wait", err) + } + if g.Status == api.GateWaiting { + continue + } + if *asJSON { + if code := e.writeJSON(g); code != ExitOK { + return code + } + } else if g.Status == api.GateAnswered { + fmt.Fprintln(e.Stdout, g.Answer) + } + if g.Status != api.GateAnswered { + fmt.Fprintf(e.Stderr, "crux: gate wait: %s %s without an answer\n", g.ID, g.Status) + return ExitError + } + return ExitOK + } +} + +// parseWithID accepts the gate id before or after the flags. +func parseWithID(fs *flag.FlagSet, args []string) (id string, code int, ok bool) { + if len(args) > 0 && !strings.HasPrefix(args[0], "-") { + id, args = args[0], args[1:] + } + if code, ok := parseSub(fs, args); !ok { + return "", code, false + } + switch { + case id == "" && fs.NArg() == 1: + id = fs.Arg(0) + case fs.NArg() != 0: + return "", ExitUsage, true + } + return id, ExitOK, true +} + +// gateErr prints a failure; refusals the caller can fix are usage errors, +// everything else a runtime failure. +func (e *Env) gateErr(verb string, err error) int { + fmt.Fprintf(e.Stderr, "crux: gate %s: %v\n", verb, err) + var se *api.StatusError + if errors.As(err, &se) { + switch se.Body.Code { + case api.CodeBadRequest, api.CodeForbidden, api.CodeGateInvalidChoice, api.CodeGateSelfAnswer, api.CodeGateContextTooLarge: + return ExitUsage + } + } + if api.IsUnauthorized(err) { + fmt.Fprintf(e.Stderr, "crux: the server wants a bearer token; pass --token or set %s\n", config.ServeTokenEnvVar) + } + return ExitError +} diff --git a/src/crux/cli/gate_test.go b/src/crux/cli/gate_test.go new file mode 100644 index 0000000000..5f94811015 --- /dev/null +++ b/src/crux/cli/gate_test.go @@ -0,0 +1,136 @@ +package cli + +import ( + "encoding/json" + "net/http/httptest" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/gates" + "github.com/hivecommons/hive/crux/serve" +) + +// gateServer is a real crux serve gate family on a token-bearing httptest +// server, with a clock the test moves. +type gateServer struct { + url string + mu sync.Mutex + now time.Time +} + +func (g *gateServer) clock() time.Time { + g.mu.Lock() + defer g.mu.Unlock() + return g.now +} + +func (g *gateServer) advance(d time.Duration) { + g.mu.Lock() + defer g.mu.Unlock() + g.now = g.now.Add(d) +} + +func newGateServer(t *testing.T) *gateServer { + t.Helper() + g := &gateServer{now: time.Date(2026, 11, 8, 12, 0, 0, 0, time.UTC)} + svc, err := gates.New(gates.Config{Dir: filepath.Join(t.TempDir(), gates.DirName), Now: g.clock}) + if err != nil { + t.Fatal(err) + } + srv := serve.New(newFakeRuntime()) + srv.Token, srv.OperatorName, srv.Gates = "gate-token", "kelly", svc + ts := httptest.NewServer(srv.Handler()) + t.Cleanup(ts.Close) + g.url = ts.URL + return g +} + +func TestGateIsRemoteOnly(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + h := newHarness(t) + if code := h.run("gate", "list"); code != ExitUsage || !strings.Contains(h.stderr.String(), "needs --server") { + t.Fatalf("local gate: %d %s", code, h.stderr) + } + h = newHarness(t) + h.run("help") + if !strings.Contains(h.stderr.String(), "gate open|list|answer|wait") { + t.Fatalf("usage does not list gate:\n%s", h.stderr) + } +} + +func TestGateOpenAnswerWait(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + t.Setenv(config.ServeTokenEnvVar, "") + g := newGateServer(t) + remote := func(args ...string) (*harness, int) { + h := newHarness(t) + return h, h.run(append([]string{"--server", g.url, "--token", "gate-token", "gate"}, args...)...) + } + + h, code := remote("open", "--subject", "ship it?", "--choice", "ship", "--choice", "hold", "--context", `{"pr":17}`, "--opened-by", "release-bot") + fields := strings.Fields(h.stdout.String()) + if code != ExitOK || len(fields) != 2 || !strings.HasPrefix(fields[0], gates.IDPrefix) || fields[1] != api.GateWaiting { + t.Fatalf("open: %d stdout=%q stderr=%q", code, h.stdout, h.stderr) + } + id := fields[0] + + // The operator opened it, so answering needs the explicit override; an + // off-menu answer is refused either way. + if h, code := remote("answer", id, "--choice", "ship"); code != ExitUsage || !strings.Contains(h.stderr.String(), "override") { + t.Fatalf("self answer: %d %s", code, h.stderr) + } + if h, code := remote("answer", id, "--choice", "sure", "--as-operator"); code != ExitUsage || !strings.Contains(h.stderr.String(), "not one of") { + t.Fatalf("off-menu answer: %d %s", code, h.stderr) + } + if h, code := remote("answer", "--choice", "ship", "--note", "green", "--as-operator", id); code != ExitOK || !strings.Contains(h.stdout.String(), "answered\tship") { + t.Fatalf("answer: %d stdout=%q stderr=%q", code, h.stdout, h.stderr) + } + if h, code := remote("wait", id); code != ExitOK || h.stdout.String() != "ship\n" { + t.Fatalf("wait: %d stdout=%q stderr=%q", code, h.stdout, h.stderr) + } + h, code = remote("list", "--status", "answered", "--json") + var list []api.Gate + if err := json.Unmarshal(h.stdout.Bytes(), &list); code != ExitOK || err != nil || len(list) != 1 || list[0].AnsweredBy != "kelly" || + !list[0].OperatorOverride || list[0].Note != "green" || list[0].OpenedBy != "release-bot" || string(list[0].Context) != `{"pr":17}` { + t.Fatalf("list: %d %v %s", code, err, h.stdout) + } + + // Expiry is reported as its own outcome: nothing on stdout, exit 1. + h, _ = remote("open", "--subject", "quick", "--timeout", "1m") + expiring := strings.Fields(h.stdout.String())[0] + g.advance(2 * time.Minute) + if h, code := remote("wait", expiring); code != ExitError || h.stdout.String() != "" || !strings.Contains(h.stderr.String(), "expired without an answer") { + t.Fatalf("wait on expired: %d stdout=%q stderr=%q", code, h.stdout, h.stderr) + } +} + +func TestGateUsage(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + t.Setenv(config.ServeTokenEnvVar, "") + g := newGateServer(t) + for _, tc := range []struct { + args []string + code int + stderr string + }{ + {[]string{"gate"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"gate", "help"}, ExitOK, "usage: crux --server ADDR gate open"}, + {[]string{"gate", "bogus"}, ExitUsage, `unknown subcommand "bogus"`}, + {[]string{"gate", "open"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"gate", "open", "--subject", "s", "--context", "{"}, ExitUsage, "not valid JSON"}, + {[]string{"gate", "answer", "gate_a"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"gate", "answer", "gate_a", "gate_b", "--choice", "x"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"gate", "wait"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"gate", "list", "--status", "pending"}, ExitUsage, "pending"}, + } { + h := newHarness(t) + if code := h.run(append([]string{"--server", g.url, "--token", "gate-token"}, tc.args...)...); code != tc.code || !strings.Contains(h.stderr.String(), tc.stderr) { + t.Fatalf("%v: %d %s", tc.args, code, h.stderr) + } + } +} diff --git a/src/crux/cli/remote.go b/src/crux/cli/remote.go index accd3e92b1..0895ddf303 100644 --- a/src/crux/cli/remote.go +++ b/src/crux/cli/remote.go @@ -55,6 +55,8 @@ func (e *Env) remote(ctx context.Context, opts globalOptions, name string, args return e.remoteCheckout(ctx, c, args) case "runs": return e.remoteRuns(ctx, c, args) + case "gate": + return e.remoteGate(ctx, c, args) default: fmt.Fprintf(e.Stderr, "crux: %q is not available with --server; it runs where the runtime is\n", name) return ExitUsage diff --git a/src/crux/cli/serve.go b/src/crux/cli/serve.go index 0bbf8487b7..025ef18eb6 100644 --- a/src/crux/cli/serve.go +++ b/src/crux/cli/serve.go @@ -11,6 +11,7 @@ import ( "github.com/hivecommons/hive/crux/api/callback" "github.com/hivecommons/hive/crux/checkout" "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/gates" "github.com/hivecommons/hive/crux/lanes" "github.com/hivecommons/hive/crux/runs" "github.com/hivecommons/hive/crux/runstate" @@ -130,6 +131,15 @@ func (e *Env) cmdServe(ctx context.Context, opts globalOptions, args []string) i srv.Checkouts = checkouts runSvc.Checkouts = checkouts } + // S3: gates need no configuration; records under /gates + // outlive the process, so a gate opened before a restart is answerable + // after it. + gateSvc, err := gates.New(gates.Config{Dir: gates.DefaultDir(opts.workDir)}) + if err != nil { + fmt.Fprintln(e.Stderr, "crux: gates:", err) + return ExitError + } + srv.Gates = gateSvc if hive != nil { hive.install(ctx, rt, srv, e.Stdout) hive.watchPolicy(ctx, rt, e.Stdout, e.Stderr) diff --git a/src/crux/cli/verbs_test.go b/src/crux/cli/verbs_test.go index aad7ebbbc3..03f7bd6aef 100644 --- a/src/crux/cli/verbs_test.go +++ b/src/crux/cli/verbs_test.go @@ -15,8 +15,8 @@ import ( // nonRuntimeVerbs are dispatch cases that do not operate on a runtime: serve // exposes one, help prints usage, cline-turn executes one pane-side worker, -// checkout and runs drive work services on a server. -var nonRuntimeVerbs = map[string]bool{"serve": true, "help": true, "-h": true, "--help": true, "cline-turn": true, "checkout": true, "runs": true} +// checkout, runs and gate drive work services on a server. +var nonRuntimeVerbs = map[string]bool{"serve": true, "help": true, "-h": true, "--help": true, "cline-turn": true, "checkout": true, "runs": true, "gate": true} func TestVerbsHaveRuntimeMethods(t *testing.T) { rt := reflect.TypeOf((*crux.Runtime)(nil)).Elem() diff --git a/src/crux/gates/gates.go b/src/crux/gates/gates.go new file mode 100644 index 0000000000..8675dee64c --- /dev/null +++ b/src/crux/gates/gates.go @@ -0,0 +1,230 @@ +// Package gates is the human-gate work service (hivecommons/crux#114 S3): a +// driver says "I need a person to decide something before I continue", a +// person answers from the terminal or the API, and the answer is recorded +// and survives a restart of the serving process. +// +// The persistence model is toolapprove.Inbox's: one record per gate, an +// idempotency key derived from the request (the DeriveIdempotencyKey +// pattern) so re-opening the same gate yields the same id and the recorded +// answer, pending items in a durable directory, and resolved records kept +// forever beside an append-only journal: +// +// /pending/.json a gate still waiting for an answer +// /resolved/.json an answered or expired gate, never removed +// /gates.jsonl opened/answered/expired, one line per change +// +// Answers are constrained to the offered choices; free text rides beside +// the choice as a note. Expiry is its own status, neither approval nor +// denial: the driver decides what it means. Subject, note and the string +// leaves of the context payload pass through logscrub before they are +// stored, and the journal carries none of them. +package gates + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "path/filepath" + "strings" + "time" +) + +// Statuses. The set is closed. +const ( + StatusWaiting = "waiting" + StatusAnswered = "answered" + StatusExpired = "expired" +) + +const ( + // DirName is the per-concern directory under the work dir. + DirName = "gates" + // PendingDirName holds one record per waiting gate. + PendingDirName = "pending" + // ResolvedDirName holds one record per answered or expired gate. + ResolvedDirName = "resolved" + // JournalName is the append-only decision journal inside Dir. + JournalName = "gates.jsonl" + // IDPrefix starts every gate id. + IDPrefix = "gate_" + // MaxContextBytes bounds the context payload after JSON encoding. + MaxContextBytes = 64 << 10 + // MaxSubjectLen, MaxNoteLen, MaxChoices and MaxChoiceLen bound the + // rest of a gate so a record stays small. + MaxSubjectLen = 1024 + MaxNoteLen = 8 << 10 + MaxChoices = 16 + MaxChoiceLen = 64 + // MaxOpenedByLen bounds the driver's own label. + MaxOpenedByLen = 128 + + idRandomBytes = 8 + maxIDLen = 64 + dirMode = 0o700 + fileMode = 0o600 +) + +// Sentinel errors; Service methods wrap them so callers map them to typed +// API codes with errors.Is. +var ( + // ErrBadRequest is a malformed request (empty subject, bad timeout, + // duplicate choices, context that is not JSON). + ErrBadRequest = errors.New("gates: bad request") + // ErrContextTooLarge is a context payload over MaxContextBytes. + ErrContextTooLarge = errors.New("gates: context too large") + // ErrNotFound is an unknown gate id. + ErrNotFound = errors.New("gates: not found") + // ErrInvalidChoice is an answer that is not one of the gate's choices. + ErrInvalidChoice = errors.New("gates: answer is not one of the offered choices") + // ErrSelfAnswer is the opener answering its own gate without the + // explicit operator override. + ErrSelfAnswer = errors.New("gates: the opener may not answer its own gate") + // ErrForbidden is a caller that may not answer gates at all. + ErrForbidden = errors.New("gates: forbidden") + // ErrClosed is an answer to a gate that is already answered or expired. + ErrClosed = errors.New("gates: gate is closed") +) + +// DefaultChoices are offered when a request names none. +var DefaultChoices = []string{"approve", "deny"} + +// Caller is the authenticated identity behind a call. Principal is the +// unique form ("operator:kelly", "project:atlas") the opener check compares; +// Name is what answered_by records. +type Caller struct { + Name string + Principal string + Operator bool +} + +// Request is what a driver asks for. +type Request struct { + Subject string + // Context is a driver-defined JSON payload, opaque to crux. + Context json.RawMessage + Choices []string + // Timeout is how long the gate waits; zero waits indefinitely. + Timeout time.Duration + // OpenedBy is the driver's own label ("nous-campaign-42"); the + // authenticated principal is recorded separately. + OpenedBy string + // IdempotencyKey, when set, identifies the gate instead of the request + // contents; it is scoped to the opening principal. + IdempotencyKey string +} + +// Answer is a person's decision on a gate. +type Answer struct { + Choice string + Note string + // Override is the explicit, audited operator override that lets the + // opener answer its own gate. + Override bool +} + +// Record is one gate as stored. Context never leaves the record for the +// journal or the event stream. +type Record struct { + ID string `json:"id"` + Status string `json:"status"` + Subject string `json:"subject"` + Context json.RawMessage `json:"context,omitempty"` + Choices []string `json:"choices"` + Timeout string `json:"timeout"` + OpenedBy string `json:"opened_by"` + OpenedByPrincipal string `json:"opened_by_principal"` + OpenedAt time.Time `json:"opened_at"` + ExpiresAt *time.Time `json:"expires_at,omitempty"` + IdempotencyKey string `json:"idempotency_key"` + Answer string `json:"answer,omitempty"` + AnsweredBy string `json:"answered_by,omitempty"` + AnsweredByPrincipal string `json:"answered_by_principal,omitempty"` + AnsweredAt *time.Time `json:"answered_at,omitempty"` + Note string `json:"note,omitempty"` + OperatorOverride bool `json:"operator_override,omitempty"` + ExpiredAt *time.Time `json:"expired_at,omitempty"` +} + +// Waiting reports whether the gate still wants an answer. +func (r Record) Waiting() bool { return r.Status == StatusWaiting } + +// HasChoice reports whether choice is one the gate offers. +func (r Record) HasChoice(choice string) bool { + for _, c := range r.Choices { + if c == choice { + return true + } + } + return false +} + +// DefaultDir is the gates directory under the runtime's work dir. +func DefaultDir(workDir string) string { return filepath.Join(workDir, DirName) } + +// ParseTimeout reads the wire form of a timeout: "" and "0" wait +// indefinitely, anything else is a positive Go duration. +func ParseTimeout(s string) (time.Duration, error) { + s = strings.TrimSpace(s) + if s == "" || s == "0" { + return 0, nil + } + d, err := time.ParseDuration(s) + if err != nil { + return 0, fmt.Errorf("%w: timeout: %v", ErrBadRequest, err) + } + if d < 0 { + return 0, fmt.Errorf("%w: timeout %q is negative", ErrBadRequest, s) + } + return d, nil +} + +// FormatTimeout is ParseTimeout's inverse: "0" for indefinitely. +func FormatTimeout(d time.Duration) string { + if d <= 0 { + return "0" + } + return d.String() +} + +// DeriveIdempotencyKey identifies a gate the way toolapprove's inbox +// identifies an approval request: a caller-supplied key wins, otherwise the +// key covers what is being asked — subject, canonical context, choices, +// timeout and the driver label — and never timestamps, so a driver that +// re-opens the same gate after a restart gets the same record. Either form +// is scoped to the opening principal so two callers cannot read each +// other's gates by guessing a key. req must already be normalized. +func DeriveIdempotencyKey(principal string, req Request) string { + h := sha256.New() + write := func(parts ...string) { + for _, p := range parts { + h.Write([]byte(p)) + h.Write([]byte{0}) + } + } + write("gate.v1", principal) + if strings.TrimSpace(req.IdempotencyKey) != "" { + write("key", req.IdempotencyKey) + return hex.EncodeToString(h.Sum(nil)) + } + write("request", req.Subject, string(req.Context), FormatTimeout(req.Timeout), req.OpenedBy) + write(fmt.Sprintf("%d", len(req.Choices))) + write(req.Choices...) + return hex.EncodeToString(h.Sum(nil)) +} + +// ValidID reports whether id has the shape of a gate id, which keeps a +// caller-supplied id from escaping the gates directory. +func ValidID(id string) bool { + rest, ok := strings.CutPrefix(id, IDPrefix) + if !ok || rest == "" || len(id) > maxIDLen { + return false + } + for _, r := range rest { + if !(r >= 'a' && r <= 'z' || r >= '0' && r <= '9') { + return false + } + } + return true +} diff --git a/src/crux/gates/gates_test.go b/src/crux/gates/gates_test.go new file mode 100644 index 0000000000..545b10f616 --- /dev/null +++ b/src/crux/gates/gates_test.go @@ -0,0 +1,344 @@ +package gates + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" +) + +// fakeClock is the injectable clock: tests move time, never sleep. +type fakeClock struct { + mu sync.Mutex + t time.Time +} + +func (c *fakeClock) Now() time.Time { + c.mu.Lock() + defer c.mu.Unlock() + return c.t +} + +func (c *fakeClock) Advance(d time.Duration) { + c.mu.Lock() + defer c.mu.Unlock() + c.t = c.t.Add(d) +} + +// fakeTimers hands each After channel to the test, which fires it. +type fakeTimers struct{ ch chan chan time.Time } + +func (f *fakeTimers) After(time.Duration) <-chan time.Time { + c := make(chan time.Time, 1) + f.ch <- c + return c +} + +var ( + operator = Caller{Name: "kelly", Principal: "operator:kelly", Operator: true} + driver = Caller{Name: "atlas", Principal: "project:atlas"} +) + +type fixture struct { + t *testing.T + dir string + clock *fakeClock + timers *fakeTimers + svc *Service + n int + mu sync.Mutex + events []string +} + +func newFixture(t *testing.T) *fixture { + t.Helper() + f := &fixture{t: t, dir: filepath.Join(t.TempDir(), DirName), clock: &fakeClock{t: time.Date(2026, 11, 8, 12, 0, 0, 0, time.UTC)}, + timers: &fakeTimers{ch: make(chan chan time.Time, 8)}} + f.restart() + return f +} + +// restart is a new process on the same directory; ids stay unique across +// restarts because the counter lives on the fixture. +func (f *fixture) restart() { + f.t.Helper() + svc, err := New(Config{Dir: f.dir, Now: f.clock.Now, After: f.timers.After, NewID: func() string { + f.n++ + return fmt.Sprintf("%s%016x", IDPrefix, f.n) + }}) + if err != nil { + f.t.Fatal(err) + } + f.mu.Lock() + f.events = nil + f.mu.Unlock() + svc.SetObserver(func(op string, rec Record) { + f.mu.Lock() + defer f.mu.Unlock() + f.events = append(f.events, op+":"+rec.ID) + }) + f.svc = svc +} + +func (f *fixture) journal() []JournalEntry { + f.t.Helper() + data, err := os.ReadFile(filepath.Join(f.dir, JournalName)) + if err != nil { + f.t.Fatal(err) + } + var out []JournalEntry + for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") { + var e JournalEntry + if err := json.Unmarshal([]byte(line), &e); err != nil { + f.t.Fatalf("journal line %q: %v", line, err) + } + out = append(out, e) + } + return out +} + +func TestOpenIsIdempotentAndSurvivesRestart(t *testing.T) { + f := newFixture(t) + req := Request{Subject: "Approve experiment budget for cache-17", Context: json.RawMessage(`{"b":2,"a":"x"}`), OpenedBy: "nous-campaign-42"} + first, created, err := f.svc.Open(driver, req) + if err != nil || !created { + t.Fatalf("open: %v created=%v", err, created) + } + if first.Status != StatusWaiting || strings.Join(first.Choices, ",") != "approve,deny" || first.Timeout != "0" || first.ExpiresAt != nil || + first.OpenedBy != "nous-campaign-42" || first.OpenedByPrincipal != "project:atlas" || string(first.Context) != `{"a":"x","b":2}` { + t.Fatalf("opened = %+v", first) + } + if _, err := os.Stat(filepath.Join(f.dir, PendingDirName, first.ID+".json")); err != nil { + t.Fatalf("pending record: %v", err) + } + // The same request, context keys reordered, is the same gate. + req.Context = json.RawMessage(`{"a":"x", "b":2}`) + again, created, err := f.svc.Open(driver, req) + if err != nil || created || again.ID != first.ID { + t.Fatalf("reopen: %+v created=%v err=%v", again, created, err) + } + // Another principal asking the same thing gets its own gate. + if other, created, err := f.svc.Open(Caller{Name: "beacon", Principal: "project:beacon"}, req); err != nil || !created || other.ID == first.ID { + t.Fatalf("other principal: %+v created=%v err=%v", other, created, err) + } + + f.restart() + answered, err := f.svc.Answer(operator, first.ID, Answer{Choice: "approve", Note: "within budget"}) + if err != nil { + t.Fatalf("answer after restart: %v", err) + } + if answered.Status != StatusAnswered || answered.Answer != "approve" || answered.AnsweredBy != "kelly" || + answered.AnsweredByPrincipal != "operator:kelly" || answered.Note != "within budget" || answered.OperatorOverride || answered.AnsweredAt == nil { + t.Fatalf("answered = %+v", answered) + } + if _, err := os.Stat(filepath.Join(f.dir, PendingDirName, first.ID+".json")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("pending record left behind: %v", err) + } + + f.restart() + replay, created, err := f.svc.Open(driver, req) + if err != nil || created || replay.ID != first.ID || replay.Answer != "approve" || replay.Status != StatusAnswered { + t.Fatalf("reopen after answer and restart: %+v created=%v err=%v", replay, created, err) + } + ops := []string{} + for _, e := range f.journal() { + ops = append(ops, e.Op) + if e.Op == OpAnswered && (e.By != "operator:kelly" || e.Answer != "approve") { + t.Fatalf("answered entry = %+v", e) + } + } + if strings.Join(ops, ",") != "opened,opened,answered" { + t.Fatalf("journal ops = %v", ops) + } +} + +func TestCallerKeyIsScopedAndWins(t *testing.T) { + f := newFixture(t) + a, _, err := f.svc.Open(driver, Request{Subject: "first wording", IdempotencyKey: "step-7"}) + if err != nil { + t.Fatal(err) + } + b, created, err := f.svc.Open(driver, Request{Subject: "second wording", IdempotencyKey: "step-7"}) + if err != nil || created || b.ID != a.ID || b.Subject != "first wording" { + t.Fatalf("keyed reopen: %+v created=%v err=%v", b, created, err) + } +} + +func TestAnswerIsConstrained(t *testing.T) { + f := newFixture(t) + g, _, err := f.svc.Open(driver, Request{Subject: "ship it?", Choices: []string{"ship", "hold"}}) + if err != nil { + t.Fatal(err) + } + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "approve"}); !errors.Is(err, ErrInvalidChoice) { + t.Fatalf("off-menu answer: %v", err) + } + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "yes, ship it"}); !errors.Is(err, ErrInvalidChoice) { + t.Fatalf("free-text answer: %v", err) + } + if _, err := f.svc.Answer(driver, g.ID, Answer{Choice: "ship"}); !errors.Is(err, ErrForbidden) { + t.Fatalf("project answer: %v", err) + } + if _, err := f.svc.Answer(operator, "gate_nope", Answer{Choice: "ship"}); !errors.Is(err, ErrNotFound) { + t.Fatalf("unknown gate: %v", err) + } + if _, err := f.svc.Answer(operator, "../../etc/passwd", Answer{Choice: "ship"}); !errors.Is(err, ErrNotFound) { + t.Fatalf("path id: %v", err) + } + rec, err := f.svc.Answer(operator, g.ID, Answer{Choice: "hold", Note: "token ghp_secretvalue1234567890 leaked"}) + if err != nil || rec.Answer != "hold" || strings.Contains(rec.Note, "ghp_") { + t.Fatalf("answer: %+v %v", rec, err) + } + // An exact replay is not an error and writes nothing; a different + // answer to a closed gate is. + if again, err := f.svc.Answer(operator, g.ID, Answer{Choice: "hold", Note: "token ghp_secretvalue1234567890 leaked"}); err != nil || again.AnsweredAt == nil || !again.AnsweredAt.Equal(*rec.AnsweredAt) { + t.Fatalf("replay: %+v %v", again, err) + } + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "ship"}); !errors.Is(err, ErrClosed) { + t.Fatalf("second answer: %v", err) + } + if n := len(f.journal()); n != 2 { + t.Fatalf("journal has %d lines, want opened+answered", n) + } +} + +func TestOpenerNeedsExplicitOverride(t *testing.T) { + f := newFixture(t) + g, _, err := f.svc.Open(operator, Request{Subject: "self-serve"}) + if err != nil { + t.Fatal(err) + } + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "approve"}); !errors.Is(err, ErrSelfAnswer) { + t.Fatalf("self answer: %v", err) + } + rec, err := f.svc.Answer(operator, g.ID, Answer{Choice: "approve", Override: true}) + if err != nil || !rec.OperatorOverride { + t.Fatalf("override: %+v %v", rec, err) + } + j := f.journal() + if last := j[len(j)-1]; !last.Override || last.By != "operator:kelly" { + t.Fatalf("override not journaled: %+v", last) + } + // The override is recorded only when it was needed. + other, _, _ := f.svc.Open(driver, Request{Subject: "theirs"}) + if rec, err := f.svc.Answer(operator, other.ID, Answer{Choice: "deny", Override: true}); err != nil || rec.OperatorOverride { + t.Fatalf("unneeded override: %+v %v", rec, err) + } +} + +func TestExpiryIsNeitherApprovalNorDenial(t *testing.T) { + f := newFixture(t) + g, _, err := f.svc.Open(driver, Request{Subject: "quick decision", Timeout: time.Minute}) + if err != nil || g.ExpiresAt == nil || g.Timeout != "1m0s" { + t.Fatalf("open: %+v %v", g, err) + } + forever, _, _ := f.svc.Open(driver, Request{Subject: "no rush"}) + f.clock.Advance(2 * time.Minute) + f.restart() + rec, err := f.svc.Get(g.ID) + if err != nil || rec.Status != StatusExpired || rec.Answer != "" || rec.AnsweredBy != "" || rec.ExpiredAt == nil { + t.Fatalf("expired = %+v %v", rec, err) + } + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "approve"}); !errors.Is(err, ErrClosed) { + t.Fatalf("answer after expiry: %v", err) + } + f.clock.Advance(10000 * time.Hour) + if rec, _ := f.svc.Get(forever.ID); rec.Status != StatusWaiting { + t.Fatalf("timeout 0 expired: %+v", rec) + } + waiting, _ := f.svc.List(ListFilter{Status: StatusWaiting}) + if len(waiting) != 1 || waiting[0].ID != forever.ID { + t.Fatalf("waiting = %+v", waiting) + } + f.mu.Lock() + defer f.mu.Unlock() + if strings.Join(f.events, ",") != "expired:"+g.ID { + t.Fatalf("events = %v", f.events) + } +} + +func TestRequestValidation(t *testing.T) { + f := newFixture(t) + big := `{"blob":"` + strings.Repeat("x", MaxContextBytes) + `"}` + for _, tc := range []struct { + req Request + want error + }{ + {Request{}, ErrBadRequest}, + {Request{Subject: "s", Context: json.RawMessage(`{"a":`)}, ErrBadRequest}, + {Request{Subject: "s", Context: json.RawMessage(`{} {}`)}, ErrBadRequest}, + {Request{Subject: "s", Choices: []string{"a", "a"}}, ErrBadRequest}, + {Request{Subject: "s", Choices: []string{"a", " "}}, ErrBadRequest}, + {Request{Subject: "s", Timeout: -time.Second}, ErrBadRequest}, + {Request{Subject: "s", Context: json.RawMessage(big)}, ErrContextTooLarge}, + } { + if _, _, err := f.svc.Open(driver, tc.req); !errors.Is(err, tc.want) { + t.Errorf("Open(%+v) = %v, want %v", tc.req.Choices, err, tc.want) + } + } + rec, _, err := f.svc.Open(driver, Request{Subject: "s", Context: json.RawMessage(`{"cred":"ghp_secretvalue1234567890","html":""}`)}) + if err != nil || strings.Contains(string(rec.Context), "ghp_") || !strings.Contains(string(rec.Context), `""`) { + t.Fatalf("scrubbed context = %s %v", rec.Context, err) + } + for _, s := range []string{"", "0", " 0 "} { + if d, err := ParseTimeout(s); err != nil || d != 0 { + t.Fatalf("ParseTimeout(%q) = %v %v", s, d, err) + } + } + if _, err := ParseTimeout("soon"); !errors.Is(err, ErrBadRequest) { + t.Fatalf("ParseTimeout(soon) = %v", err) + } +} + +func TestWaitWakesOnAnswerExpiryAndWindow(t *testing.T) { + f := newFixture(t) + ctx := context.Background() + + g, _, _ := f.svc.Open(driver, Request{Subject: "answer me"}) + done := make(chan Record, 1) + go func() { + rec, _ := f.svc.Wait(ctx, g.ID, 0) + done <- rec + }() + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "deny"}); err != nil { + t.Fatal(err) + } + if rec := <-done; rec.Status != StatusAnswered || rec.Answer != "deny" { + t.Fatalf("wait after answer = %+v", rec) + } + + timed, _, _ := f.svc.Open(driver, Request{Subject: "expire me", Timeout: time.Minute}) + go func() { + rec, _ := f.svc.Wait(ctx, timed.ID, 0) + done <- rec + }() + expiry := <-f.timers.ch + f.clock.Advance(time.Minute) + expiry <- f.clock.Now() + if rec := <-done; rec.Status != StatusExpired { + t.Fatalf("wait through expiry = %+v", rec) + } + + open, _, _ := f.svc.Open(driver, Request{Subject: "nobody home"}) + go func() { + rec, _ := f.svc.Wait(ctx, open.ID, 30*time.Second) + done <- rec + }() + window := <-f.timers.ch + window <- f.clock.Now() + if rec := <-done; rec.Status != StatusWaiting || rec.ID != open.ID { + t.Fatalf("wait window = %+v", rec) + } + + cctx, cancel := context.WithCancel(ctx) + cancel() + if _, err := f.svc.Wait(cctx, open.ID, 0); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled wait: %v", err) + } +} diff --git a/src/crux/gates/request.go b/src/crux/gates/request.go new file mode 100644 index 0000000000..e142e2bf9d --- /dev/null +++ b/src/crux/gates/request.go @@ -0,0 +1,145 @@ +package gates + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io" + "strings" + + "github.com/hivecommons/hive/crux/logscrub" +) + +// maxIdempotencyKeyLen bounds a caller-supplied idempotency key. +const maxIdempotencyKeyLen = 256 + +// normalize validates req and returns the form that is stored and keyed: +// trimmed text, default choices filled in, the context re-encoded +// canonically (sorted object keys) and every free-text field scrubbed of +// credential-shaped strings. +func normalize(req Request) (Request, error) { + out := Request{Timeout: req.Timeout, IdempotencyKey: strings.TrimSpace(req.IdempotencyKey)} + subject := strings.TrimSpace(req.Subject) + switch { + case subject == "": + return Request{}, fmt.Errorf("%w: subject is required", ErrBadRequest) + case len(subject) > MaxSubjectLen: + return Request{}, fmt.Errorf("%w: subject is %d bytes, over %d", ErrBadRequest, len(subject), MaxSubjectLen) + } + out.Subject = logscrub.ScrubString(subject) + openedBy := strings.TrimSpace(req.OpenedBy) + if len(openedBy) > MaxOpenedByLen { + return Request{}, fmt.Errorf("%w: opened_by is %d bytes, over %d", ErrBadRequest, len(openedBy), MaxOpenedByLen) + } + out.OpenedBy = logscrub.ScrubString(openedBy) + if req.Timeout < 0 { + return Request{}, fmt.Errorf("%w: timeout is negative", ErrBadRequest) + } + if len(out.IdempotencyKey) > maxIdempotencyKeyLen { + return Request{}, fmt.Errorf("%w: idempotency key is over %d bytes", ErrBadRequest, maxIdempotencyKeyLen) + } + choices, err := normalizeChoices(req.Choices) + if err != nil { + return Request{}, err + } + out.Choices = choices + if out.Context, err = normalizeContext(req.Context); err != nil { + return Request{}, err + } + return out, nil +} + +func normalizeChoices(in []string) ([]string, error) { + if len(in) == 0 { + return append([]string(nil), DefaultChoices...), nil + } + if len(in) > MaxChoices { + return nil, fmt.Errorf("%w: %d choices, over %d", ErrBadRequest, len(in), MaxChoices) + } + seen := map[string]bool{} + out := make([]string, 0, len(in)) + for _, c := range in { + c = strings.TrimSpace(c) + switch { + case c == "": + return nil, fmt.Errorf("%w: empty choice", ErrBadRequest) + case len(c) > MaxChoiceLen: + return nil, fmt.Errorf("%w: choice %q is over %d bytes", ErrBadRequest, c[:MaxChoiceLen], MaxChoiceLen) + case seen[c]: + return nil, fmt.Errorf("%w: duplicate choice %q", ErrBadRequest, c) + } + seen[c] = true + out = append(out, c) + } + return out, nil +} + +// normalizeContext checks the payload is one JSON value no larger than +// MaxContextBytes once encoded, then returns it canonically encoded with +// its string values scrubbed. JSON null and an absent payload are nil. +func normalizeContext(raw json.RawMessage) (json.RawMessage, error) { + if len(bytes.TrimSpace(raw)) == 0 { + return nil, nil + } + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.UseNumber() + var v any + if err := dec.Decode(&v); err != nil { + return nil, fmt.Errorf("%w: context is not JSON: %v", ErrBadRequest, err) + } + if _, err := dec.Token(); !errors.Is(err, io.EOF) { + return nil, fmt.Errorf("%w: context must be a single JSON value", ErrBadRequest) + } + if v == nil { + return nil, nil + } + encoded, err := encodeCanonical(v) + if err != nil { + return nil, fmt.Errorf("%w: context: %v", ErrBadRequest, err) + } + if len(encoded) > MaxContextBytes { + return nil, fmt.Errorf("%w: %d bytes encoded, over %d", ErrContextTooLarge, len(encoded), MaxContextBytes) + } + return encodeCanonical(scrubValue(v)) +} + +// encodeCanonical marshals v with sorted object keys and without HTML +// escaping, so the stored payload is the driver's text. +func encodeCanonical(v any) (json.RawMessage, error) { + var buf bytes.Buffer + enc := json.NewEncoder(&buf) + enc.SetEscapeHTML(false) + if err := enc.Encode(v); err != nil { + return nil, err + } + return json.RawMessage(bytes.TrimRight(buf.Bytes(), "\n")), nil +} + +// scrubValue redacts credential-shaped strings in every string leaf. +func scrubValue(v any) any { + switch t := v.(type) { + case string: + return logscrub.ScrubString(t) + case map[string]any: + for k, e := range t { + t[k] = scrubValue(e) + } + return t + case []any: + for i, e := range t { + t[i] = scrubValue(e) + } + return t + } + return v +} + +// normalizeNote trims and bounds a note and scrubs it. +func normalizeNote(note string) (string, error) { + note = strings.TrimSpace(note) + if len(note) > MaxNoteLen { + return "", fmt.Errorf("%w: note is %d bytes, over %d", ErrBadRequest, len(note), MaxNoteLen) + } + return logscrub.ScrubString(note), nil +} diff --git a/src/crux/gates/service.go b/src/crux/gates/service.go new file mode 100644 index 0000000000..ea2d506f51 --- /dev/null +++ b/src/crux/gates/service.go @@ -0,0 +1,227 @@ +package gates + +import ( + "fmt" + "sort" + "strings" + "sync" + "time" +) + +// Config is how a Service is built. Only Dir is required. +type Config struct { + // Dir is where pending, resolved and the journal live (DefaultDir). + Dir string + // Now is the clock; nil uses time.Now. + Now func() time.Time + // After fires once d has passed; nil uses time.After. Wait uses it for + // both the caller's poll window and a gate's expiry. + After func(d time.Duration) <-chan time.Time + // NewID mints a gate id; nil draws IDPrefix plus 16 random hex digits. + NewID func() string +} + +// Observer is told about every change to a gate after it is durable: +// op is OpOpened, OpAnswered or OpExpired. +type Observer func(op string, rec Record) + +// Service is the gate store for one directory. It is safe for concurrent +// use within one process; a gates directory is served by one process. +type Service struct { + st store + now func() time.Time + after func(time.Duration) <-chan time.Time + newID func() string + + mu sync.Mutex + keys map[string]string // idempotency key -> id + watchers map[string]chan struct{} // id -> closed when the gate resolves + observer Observer +} + +// change is a durable transition the observer has not yet been told about. +type change struct { + op string + rec Record +} + +// New opens the gates directory, creating it, and rebuilds the idempotency +// index from every record on disk, pending and resolved — which is what +// makes a gate opened before a restart answerable, and re-opening it +// idempotent, after one. +func New(cfg Config) (*Service, error) { + if strings.TrimSpace(cfg.Dir) == "" { + return nil, fmt.Errorf("%w: gates directory is required", ErrBadRequest) + } + s := &Service{st: store{dir: cfg.Dir}, now: cfg.Now, after: cfg.After, newID: cfg.NewID, + keys: map[string]string{}, watchers: map[string]chan struct{}{}} + if s.now == nil { + s.now = time.Now + } + if s.after == nil { + s.after = time.After + } + if s.newID == nil { + s.newID = newID + } + if err := s.st.init(); err != nil { + return nil, err + } + recs, err := s.st.list() + if err != nil { + return nil, err + } + for _, rec := range recs { + if !rec.Waiting() { + if err := s.st.dropStalePending(rec.ID); err != nil { + return nil, err + } + } + if rec.IdempotencyKey != "" { + s.keys[rec.IdempotencyKey] = rec.ID + } + } + return s, nil +} + +// SetObserver installs fn as the change observer (crux serve publishes +// gate.* events from it). nil removes it. +func (s *Service) SetObserver(fn Observer) { + s.mu.Lock() + defer s.mu.Unlock() + s.observer = fn +} + +// Visible reports whether caller may read rec: the operator reads every +// gate, anyone else only the gates it opened. +func Visible(rec Record, caller Caller) bool { + return caller.Operator || rec.OpenedByPrincipal == caller.Principal +} + +// Open records a new waiting gate for caller and returns it with +// created=true. When the same principal already opened the same gate (the +// derived idempotency key matches) nothing is written and that gate's +// current record — waiting, answered or expired — is returned with +// created=false. +func (s *Service) Open(caller Caller, req Request) (Record, bool, error) { + n, err := normalize(req) + if err != nil { + return Record{}, false, err + } + key := DeriveIdempotencyKey(caller.Principal, n) + s.mu.Lock() + if id, ok := s.keys[key]; ok { + rec, changes, err := s.loadLocked(id) + s.mu.Unlock() + s.emit(changes) + return rec, false, err + } + now := s.now().UTC() + rec := Record{ + ID: s.newID(), Status: StatusWaiting, Subject: n.Subject, Context: n.Context, Choices: n.Choices, + Timeout: FormatTimeout(n.Timeout), OpenedBy: n.OpenedBy, OpenedByPrincipal: caller.Principal, + OpenedAt: now, IdempotencyKey: key, + } + if rec.OpenedBy == "" { + rec.OpenedBy = caller.Name + } + entry := JournalEntry{At: now, Op: OpOpened, ID: rec.ID, Status: rec.Status, By: caller.Principal} + if n.Timeout > 0 { + exp := now.Add(n.Timeout) + rec.ExpiresAt = &exp + entry.ExpiresAt = exp.Format(time.RFC3339Nano) + } + if err := s.st.put(rec); err != nil { + s.mu.Unlock() + return Record{}, false, err + } + err = s.st.appendJournal(entry) + s.keys[key] = rec.ID + s.mu.Unlock() + if err != nil { + return rec, true, err + } + s.emit([]change{{OpOpened, rec}}) + return rec, true, nil +} + +// Get returns the saved gate, expiring it first when its timeout passed. +func (s *Service) Get(id string) (Record, error) { + s.mu.Lock() + rec, changes, err := s.loadLocked(id) + s.mu.Unlock() + s.emit(changes) + return rec, err +} + +// ListFilter narrows List. Zero values match everything. +type ListFilter struct { + // Status is one of the Status* values. + Status string + // Caller limits the result to the gates Visible to it. + Caller *Caller +} + +// List returns the gates matching f, oldest first, expiring any whose +// timeout passed. +func (s *Service) List(f ListFilter) ([]Record, error) { + s.mu.Lock() + recs, err := s.st.list() + if err != nil { + s.mu.Unlock() + return nil, err + } + var changes []change + out := make([]Record, 0, len(recs)) + for _, rec := range recs { + rec, c, err := s.expireLocked(rec) + changes = append(changes, c...) + if err != nil { + s.mu.Unlock() + s.emit(changes) + return nil, err + } + if (f.Status == "" || rec.Status == f.Status) && (f.Caller == nil || Visible(rec, *f.Caller)) { + out = append(out, rec) + } + } + s.mu.Unlock() + s.emit(changes) + sort.Slice(out, func(i, j int) bool { + if out[i].OpenedAt.Equal(out[j].OpenedAt) { + return out[i].ID < out[j].ID + } + return out[i].OpenedAt.Before(out[j].OpenedAt) + }) + return out, nil +} + +// Answer records caller's decision on gate id. Only an operator answers; +// the choice must be one the gate offers; the principal that opened the +// gate may answer it only with a.Override, which the record and journal +// carry as operator_override. Repeating the exact answer that was recorded +// (same choice, note and principal) returns the record unchanged, so a +// retried request is not an error; any other answer to a closed gate is +// ErrClosed. +func (s *Service) Answer(caller Caller, id string, a Answer) (Record, error) { + if !caller.Operator { + return Record{}, fmt.Errorf("%w: gates are answered by the operator, not %s", ErrForbidden, caller.Principal) + } + note, err := normalizeNote(a.Note) + if err != nil { + return Record{}, err + } + choice := strings.TrimSpace(a.Choice) + s.mu.Lock() + rec, changes, err := s.loadLocked(id) + if err == nil { + var wrote bool + rec, wrote, err = s.answerLocked(caller, rec, choice, note, a.Override) + if wrote { + changes = append(changes, change{OpAnswered, rec}) + } + } + s.mu.Unlock() + s.emit(changes) + return rec, err +} diff --git a/src/crux/gates/store.go b/src/crux/gates/store.go new file mode 100644 index 0000000000..f55527c2f5 --- /dev/null +++ b/src/crux/gates/store.go @@ -0,0 +1,182 @@ +package gates + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "time" +) + +// Journal operations. +const ( + OpOpened = "opened" + OpAnswered = "answered" + OpExpired = "expired" +) + +// JournalEntry is one line of gates.jsonl: who did what to which gate. It +// never carries the subject, context or note, so the journal can be +// shipped or tailed without leaking what the gate was about. +type JournalEntry struct { + At time.Time `json:"at"` + Op string `json:"op"` + ID string `json:"id"` + Status string `json:"status"` + By string `json:"by,omitempty"` + Answer string `json:"answer,omitempty"` + Override bool `json:"operator_override,omitempty"` + ExpiresAt string `json:"expires_at,omitempty"` +} + +// store is the record layout under one gates directory. +type store struct{ dir string } + +func (st *store) pendingDir() string { return filepath.Join(st.dir, PendingDirName) } +func (st *store) resolvedDir() string { return filepath.Join(st.dir, ResolvedDirName) } + +func (st *store) pendingPath(id string) string { + return filepath.Join(st.pendingDir(), id+".json") +} + +func (st *store) resolvedPath(id string) string { + return filepath.Join(st.resolvedDir(), id+".json") +} + +func (st *store) init() error { + for _, d := range []string{st.dir, st.pendingDir(), st.resolvedDir()} { + if err := os.MkdirAll(d, dirMode); err != nil { + return fmt.Errorf("gates: %w", err) + } + } + return nil +} + +// put writes rec where its status says it belongs: pending while waiting, +// resolved otherwise. Resolving writes the resolved record first and only +// then removes the pending one, so a crash in between leaves both and +// load prefers the resolved copy; it never loses an answer. +func (st *store) put(rec Record) error { + data, err := json.Marshal(rec) + if err != nil { + return fmt.Errorf("gates: %w", err) + } + path := st.pendingPath(rec.ID) + if !rec.Waiting() { + path = st.resolvedPath(rec.ID) + } + if err := writeAtomic(path, data); err != nil { + return err + } + if !rec.Waiting() { + if err := os.Remove(st.pendingPath(rec.ID)); err != nil && !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("gates: %w", err) + } + } + return nil +} + +// get reads id, resolved first. +func (st *store) get(id string) (Record, error) { + if !ValidID(id) { + return Record{}, fmt.Errorf("%w: %q is not a gate id", ErrNotFound, id) + } + for _, path := range []string{st.resolvedPath(id), st.pendingPath(id)} { + rec, err := readRecord(path) + if errors.Is(err, os.ErrNotExist) { + continue + } + return rec, err + } + return Record{}, fmt.Errorf("%w: gate %s", ErrNotFound, id) +} + +// list returns every record on disk, a resolved copy shadowing a stale +// pending one. Order is unspecified; Service sorts. +func (st *store) list() ([]Record, error) { + byID := map[string]Record{} + for _, dir := range []string{st.pendingDir(), st.resolvedDir()} { + entries, err := os.ReadDir(dir) + if errors.Is(err, os.ErrNotExist) { + continue + } + if err != nil { + return nil, fmt.Errorf("gates: %w", err) + } + for _, e := range entries { + id, ok := strings.CutSuffix(e.Name(), ".json") + if !ok || e.IsDir() || !ValidID(id) { + continue + } + rec, err := readRecord(filepath.Join(dir, e.Name())) + if err != nil { + return nil, err + } + byID[id] = rec + } + } + out := make([]Record, 0, len(byID)) + for _, rec := range byID { + out = append(out, rec) + } + return out, nil +} + +// dropStalePending removes a pending copy left by a crash between the two +// writes of a resolution. +func (st *store) dropStalePending(id string) error { + if _, err := os.Stat(st.resolvedPath(id)); err != nil { + return nil + } + if err := os.Remove(st.pendingPath(id)); err != nil && !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("gates: %w", err) + } + return nil +} + +func (st *store) appendJournal(entry JournalEntry) error { + data, err := json.Marshal(entry) + if err != nil { + return fmt.Errorf("gates: %w", err) + } + f, err := os.OpenFile(filepath.Join(st.dir, JournalName), os.O_APPEND|os.O_CREATE|os.O_WRONLY, fileMode) + if err != nil { + return fmt.Errorf("gates: %w", err) + } + _, werr := f.Write(append(data, '\n')) + if cerr := f.Close(); werr == nil { + werr = cerr + } + if werr != nil { + return fmt.Errorf("gates: %w", werr) + } + return nil +} + +func readRecord(path string) (Record, error) { + data, err := os.ReadFile(path) + if err != nil { + if errors.Is(err, os.ErrNotExist) { + return Record{}, err + } + return Record{}, fmt.Errorf("gates: %w", err) + } + var rec Record + if err := json.Unmarshal(data, &rec); err != nil { + return Record{}, fmt.Errorf("gates: %s: corrupt record: %w", filepath.Base(path), err) + } + return rec, nil +} + +func writeAtomic(path string, data []byte) error { + tmp := path + ".tmp" + if err := os.WriteFile(tmp, data, fileMode); err != nil { + return fmt.Errorf("gates: %w", err) + } + if err := os.Rename(tmp, path); err != nil { + return fmt.Errorf("gates: %w", err) + } + return nil +} diff --git a/src/crux/gates/wait.go b/src/crux/gates/wait.go new file mode 100644 index 0000000000..05e3a9894a --- /dev/null +++ b/src/crux/gates/wait.go @@ -0,0 +1,151 @@ +package gates + +import ( + "context" + "crypto/rand" + "encoding/hex" + "fmt" + "strings" + "time" +) + +// Wait blocks until gate id is answered or expired, ctx ends, or poll has +// passed (poll <= 0 waits without a window), and returns the gate as it then +// stands: a record still StatusWaiting means the window closed first. A +// gate with a timeout is expired by Wait itself when the timeout passes, +// so a waiter never needs another caller to look for it to flip. +func (s *Service) Wait(ctx context.Context, id string, poll time.Duration) (Record, error) { + var window <-chan time.Time + if poll > 0 { + window = s.after(poll) + } + for { + s.mu.Lock() + rec, changes, err := s.loadLocked(id) + var resolved chan struct{} + if err == nil && rec.Waiting() { + resolved = s.watcherLocked(id) + } + s.mu.Unlock() + s.emit(changes) + if err != nil || !rec.Waiting() { + return rec, err + } + var expiry <-chan time.Time + if rec.ExpiresAt != nil { + expiry = s.after(rec.ExpiresAt.Sub(s.now())) + } + select { + case <-resolved: + case <-expiry: + case <-window: + return rec, nil + case <-ctx.Done(): + return rec, ctx.Err() + } + } +} + +// answerLocked applies one answer to rec; wrote reports whether a new +// answer was recorded (false for an exact replay). +func (s *Service) answerLocked(caller Caller, rec Record, choice, note string, override bool) (Record, bool, error) { + if !rec.Waiting() { + if rec.Status == StatusAnswered && rec.Answer == choice && rec.Note == note && rec.AnsweredByPrincipal == caller.Principal { + return rec, false, nil + } + return rec, false, fmt.Errorf("%w: %s is %s", ErrClosed, rec.ID, rec.Status) + } + if !rec.HasChoice(choice) { + return rec, false, fmt.Errorf("%w: %q is not one of %s", ErrInvalidChoice, choice, strings.Join(rec.Choices, ", ")) + } + self := rec.OpenedByPrincipal == caller.Principal + if self && !override { + return rec, false, fmt.Errorf("%w: %s opened %s; answering it needs the explicit operator override", ErrSelfAnswer, caller.Principal, rec.ID) + } + now := s.now().UTC() + rec.Status = StatusAnswered + rec.Answer = choice + rec.AnsweredBy = caller.Name + rec.AnsweredByPrincipal = caller.Principal + rec.AnsweredAt = &now + rec.Note = note + rec.OperatorOverride = self + err := s.resolveLocked(rec, JournalEntry{At: now, Op: OpAnswered, ID: rec.ID, Status: rec.Status, By: caller.Principal, Answer: choice, Override: self}) + if err != nil { + return Record{}, false, err + } + return rec, true, nil +} + +// loadLocked reads id and expires it when due. +func (s *Service) loadLocked(id string) (Record, []change, error) { + rec, err := s.st.get(id) + if err != nil { + return Record{}, nil, err + } + return s.expireLocked(rec) +} + +// expireLocked moves a waiting gate whose timeout has passed to +// StatusExpired: no answer, no answerer, only the time it expired. +func (s *Service) expireLocked(rec Record) (Record, []change, error) { + if !rec.Waiting() || rec.ExpiresAt == nil { + return rec, nil, nil + } + now := s.now().UTC() + if now.Before(*rec.ExpiresAt) { + return rec, nil, nil + } + rec.Status = StatusExpired + rec.ExpiredAt = &now + if err := s.resolveLocked(rec, JournalEntry{At: now, Op: OpExpired, ID: rec.ID, Status: rec.Status}); err != nil { + return Record{}, nil, err + } + return rec, []change{{OpExpired, rec}}, nil +} + +// resolveLocked makes a resolution durable, journals it and wakes waiters. +func (s *Service) resolveLocked(rec Record, entry JournalEntry) error { + if err := s.st.put(rec); err != nil { + return err + } + if ch, ok := s.watchers[rec.ID]; ok { + close(ch) + delete(s.watchers, rec.ID) + } + return s.st.appendJournal(entry) +} + +// watcherLocked returns the channel closed when id resolves. +func (s *Service) watcherLocked(id string) chan struct{} { + ch, ok := s.watchers[id] + if !ok { + ch = make(chan struct{}) + s.watchers[id] = ch + } + return ch +} + +// emit tells the observer about durable changes, outside the lock. +func (s *Service) emit(changes []change) { + if len(changes) == 0 { + return + } + s.mu.Lock() + fn := s.observer + s.mu.Unlock() + if fn == nil { + return + } + for _, c := range changes { + fn(c.op, c.rec) + } +} + +func newID() string { + var b [idRandomBytes]byte + if _, err := rand.Read(b[:]); err != nil { + panic(fmt.Sprintf("gates: crypto/rand: %v", err)) + } + return IDPrefix + hex.EncodeToString(b[:]) +} diff --git a/src/crux/serve/gates.go b/src/crux/serve/gates.go new file mode 100644 index 0000000000..57e7e0b860 --- /dev/null +++ b/src/crux/serve/gates.go @@ -0,0 +1,236 @@ +package serve + +import ( + "errors" + "fmt" + "net/http" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/gates" +) + +// Human gates (hivecommons/crux#114 S3) are a work-services family: a +// project principal may open gates and read or wait on the ones it opened; +// only the operator answers, and the principal that opened a gate answers +// it only with the explicit, audited as_operator override. + +const ( + // DefaultGateWait is the long-poll window of GET /v1/gates/{id}/wait + // when the request names none. + DefaultGateWait = 30 * time.Second + // MaxGateWait bounds the window a request may ask for; a longer wait is + // a loop of polls (crux gate wait does that). + MaxGateWait = 5 * time.Minute + // auditGateOverride is the audit action of an opener answering its own + // gate under as_operator. + auditGateOverride = "gate.operator_override" +) + +// registerGates mounts the gate routes, marks them a work service and +// relays gate changes onto /v1/events. +func (s *Server) registerGates(mux *http.ServeMux) { + mux.HandleFunc("POST "+api.PathGates, s.handleGateOpen) + mux.HandleFunc("GET "+api.PathGates, s.handleGateList) + mux.HandleFunc("GET "+api.PathGates+"/{id}", s.handleGateGet) + mux.HandleFunc("POST "+api.PathGates+"/{id}/answer", s.handleGateAnswer) + mux.HandleFunc("GET "+api.PathGates+"/{id}/wait", s.handleGateWait) + s.workService(api.PathGates) + if s.Gates != nil { + s.Gates.SetObserver(s.publishGate) + } +} + +// gatesCaller is the request's principal as the gate service sees it. A +// context that did not pass authenticate is the operator, as for runs. +func (s *Server) gatesCaller(r *http.Request) gates.Caller { + p, ok := CallerFrom(r.Context()) + if !ok { + p = s.operator() + } + return gates.Caller{Name: p.Name, Principal: p.String(), Operator: p.IsOperator()} +} + +// gateService answers 501 when the server has no gate service. +func (s *Server) gateService(w http.ResponseWriter) (*gates.Service, bool) { + if s.Gates == nil { + s.writeError(w, http.StatusNotImplemented, api.CodeNotSupported, "this server has no gate service") + return nil, false + } + return s.Gates, true +} + +func (s *Server) handleGateOpen(w http.ResponseWriter, r *http.Request) { + svc, ok := s.gateService(w) + if !ok { + return + } + var in api.GateRequest + if !s.readJSON(w, r, &in) { + return + } + timeout, err := gates.ParseTimeout(in.Timeout) + if err != nil { + s.writeGateError(w, err) + return + } + rec, created, err := svc.Open(s.gatesCaller(r), gates.Request{ + Subject: in.Subject, Context: in.Context, Choices: in.Choices, Timeout: timeout, + OpenedBy: in.OpenedBy, IdempotencyKey: in.IdempotencyKey, + }) + if err != nil { + s.writeGateError(w, err) + return + } + status := http.StatusOK + if created { + status = http.StatusCreated + } + s.writeJSON(w, status, gateToAPI(rec)) +} + +func (s *Server) handleGateList(w http.ResponseWriter, r *http.Request) { + svc, ok := s.gateService(w) + if !ok { + return + } + status := r.URL.Query().Get("status") + switch status { + case "", gates.StatusWaiting, gates.StatusAnswered, gates.StatusExpired: + default: + s.writeError(w, http.StatusBadRequest, api.CodeBadRequest, fmt.Sprintf("status %q is not waiting, answered or expired", status)) + return + } + caller := s.gatesCaller(r) + recs, err := svc.List(gates.ListFilter{Status: status, Caller: &caller}) + if err != nil { + s.writeGateError(w, err) + return + } + out := api.GateList{Gates: make([]api.Gate, 0, len(recs))} + for _, rec := range recs { + out.Gates = append(out.Gates, gateToAPI(rec)) + } + s.writeJSON(w, http.StatusOK, out) +} + +func (s *Server) handleGateGet(w http.ResponseWriter, r *http.Request) { + svc, ok := s.gateService(w) + if !ok { + return + } + if rec, ok := s.visibleGate(w, r, svc); ok { + s.writeJSON(w, http.StatusOK, gateToAPI(rec)) + } +} + +func (s *Server) handleGateAnswer(w http.ResponseWriter, r *http.Request) { + svc, ok := s.gateService(w) + if !ok { + return + } + var in api.GateAnswerRequest + if !s.readJSON(w, r, &in) { + return + } + rec, err := svc.Answer(s.gatesCaller(r), r.PathValue("id"), gates.Answer{Choice: in.Answer, Note: in.Note, Override: in.AsOperator}) + if err != nil { + s.writeGateError(w, err) + return + } + s.writeJSON(w, http.StatusOK, gateToAPI(rec)) +} + +func (s *Server) handleGateWait(w http.ResponseWriter, r *http.Request) { + svc, ok := s.gateService(w) + if !ok { + return + } + window := DefaultGateWait + if v := r.URL.Query().Get("timeout"); v != "" { + d, err := time.ParseDuration(v) + if err != nil || d <= 0 { + s.writeError(w, http.StatusBadRequest, api.CodeBadRequest, fmt.Sprintf("timeout %q is not a positive duration", v)) + return + } + window = min(d, MaxGateWait) + } + if _, ok := s.visibleGate(w, r, svc); !ok { + return + } + rec, err := svc.Wait(r.Context(), r.PathValue("id"), window) + if err != nil { + if r.Context().Err() != nil { + return // the caller went away; nothing to answer + } + s.writeGateError(w, err) + return + } + s.writeJSON(w, http.StatusOK, gateToAPI(rec)) +} + +// visibleGate loads {id} and enforces that the caller opened it or is the +// operator; on failure the response has been written. +func (s *Server) visibleGate(w http.ResponseWriter, r *http.Request, svc *gates.Service) (gates.Record, bool) { + rec, err := svc.Get(r.PathValue("id")) + if err != nil { + s.writeGateError(w, err) + return gates.Record{}, false + } + if caller := s.gatesCaller(r); !gates.Visible(rec, caller) { + s.writeError(w, http.StatusForbidden, api.CodeForbidden, fmt.Sprintf("gate %s was opened by %s, not by %s", rec.ID, rec.OpenedByPrincipal, caller.Principal)) + return gates.Record{}, false + } + return rec, true +} + +// writeGateError maps the package's sentinels to typed codes. +func (s *Server) writeGateError(w http.ResponseWriter, err error) { + status, code := http.StatusInternalServerError, api.CodeRuntime + switch { + case errors.Is(err, gates.ErrBadRequest): + status, code = http.StatusBadRequest, api.CodeBadRequest + case errors.Is(err, gates.ErrContextTooLarge): + status, code = http.StatusRequestEntityTooLarge, api.CodeGateContextTooLarge + case errors.Is(err, gates.ErrNotFound): + status, code = http.StatusNotFound, api.CodeNotFound + case errors.Is(err, gates.ErrInvalidChoice): + status, code = http.StatusUnprocessableEntity, api.CodeGateInvalidChoice + case errors.Is(err, gates.ErrSelfAnswer): + status, code = http.StatusForbidden, api.CodeGateSelfAnswer + case errors.Is(err, gates.ErrForbidden): + status, code = http.StatusForbidden, api.CodeForbidden + case errors.Is(err, gates.ErrClosed): + status, code = http.StatusConflict, api.CodeGateClosed + } + s.writeError(w, status, code, err.Error()) +} + +// publishGate relays one durable gate change onto /v1/events, without the +// context payload, and audits an operator override. +func (s *Server) publishGate(op string, rec gates.Record) { + typ := api.EventGateOpened + switch op { + case gates.OpAnswered: + typ = api.EventGateAnswered + case gates.OpExpired: + typ = api.EventGateExpired + } + ev := gateToAPI(rec) + ev.Context = nil + s.publishData(typ, "", ev) + if op == gates.OpAnswered && rec.OperatorOverride { + auditTee{s}.Record(rec.AnsweredByPrincipal, auditGateOverride, "", map[string]any{ + "gate": rec.ID, "answer": rec.Answer, "opened_by_principal": rec.OpenedByPrincipal, + }) + } +} + +func gateToAPI(rec gates.Record) api.Gate { + return api.Gate{ + ID: rec.ID, Status: rec.Status, Subject: rec.Subject, Context: rec.Context, Choices: rec.Choices, Timeout: rec.Timeout, + OpenedBy: rec.OpenedBy, OpenedByPrincipal: rec.OpenedByPrincipal, OpenedAt: rec.OpenedAt, ExpiresAt: rec.ExpiresAt, + Answer: rec.Answer, AnsweredBy: rec.AnsweredBy, AnsweredByPrincipal: rec.AnsweredByPrincipal, AnsweredAt: rec.AnsweredAt, + Note: rec.Note, OperatorOverride: rec.OperatorOverride, ExpiredAt: rec.ExpiredAt, + } +} diff --git a/src/crux/serve/gates_test.go b/src/crux/serve/gates_test.go new file mode 100644 index 0000000000..6e373276fa --- /dev/null +++ b/src/crux/serve/gates_test.go @@ -0,0 +1,224 @@ +package serve + +import ( + "bytes" + "encoding/json" + "net/http" + "net/http/httptest" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/gates" + "github.com/hivecommons/hive/crux/lanes" +) + +type gateClock struct { + mu sync.Mutex + t time.Time +} + +func (c *gateClock) now() time.Time { + c.mu.Lock() + defer c.mu.Unlock() + return c.t +} + +func (c *gateClock) advance(d time.Duration) { + c.mu.Lock() + defer c.mu.Unlock() + c.t = c.t.Add(d) +} + +type gateFixture struct { + t *testing.T + dir string + clock *gateClock + auth *lanes.Authenticator + tokens map[string]string + s *Server + h http.Handler +} + +// newGateFixture is a token-bearing server named "kelly" with a gate +// service and two lane projects (atlas, beacon) besides the operator. +func newGateFixture(t *testing.T) *gateFixture { + t.Helper() + tokens := map[string]string{"atlas": strings.Repeat("a", 32), "beacon": strings.Repeat("b", 32), "operator": "agent-admin"} + cfg := lanes.Config{Principals: []lanes.Principal{{Project: "atlas", TokenEnv: "ATLAS"}, {Project: "beacon", TokenEnv: "BEACON"}}} + auth, err := lanes.Bind(cfg, func(env string) string { return tokens[strings.ToLower(env)] }, tokens["operator"]) + if err != nil { + t.Fatal(err) + } + f := &gateFixture{t: t, dir: filepath.Join(t.TempDir(), gates.DirName), auth: auth, tokens: tokens, + clock: &gateClock{t: time.Date(2026, 11, 8, 12, 0, 0, 0, time.UTC)}} + f.restart() + return f +} + +// restart is a new crux serve process on the same work dir. +func (f *gateFixture) restart() { + f.t.Helper() + svc, err := gates.New(gates.Config{Dir: f.dir, Now: f.clock.now}) + if err != nil { + f.t.Fatal(err) + } + f.s = New(newFakeRuntime()) + f.s.Token, f.s.LaneAuth, f.s.OperatorName, f.s.Gates = f.tokens["operator"], f.auth, "kelly", svc + f.h = f.s.Handler() +} + +// call sends method path as who and decodes a 2xx body into out. +func (f *gateFixture) call(who, method, path string, body, out any) (int, api.Error) { + f.t.Helper() + var buf bytes.Buffer + if body != nil { + if err := json.NewEncoder(&buf).Encode(body); err != nil { + f.t.Fatal(err) + } + } + req := httptest.NewRequest(method, path, &buf) + req.Header.Set("Authorization", "Bearer "+f.tokens[who]) + rec := httptest.NewRecorder() + f.h.ServeHTTP(rec, req) + var e api.Error + if rec.Code >= 300 { + _ = json.Unmarshal(rec.Body.Bytes(), &e) + } else if out != nil { + if err := json.Unmarshal(rec.Body.Bytes(), out); err != nil { + f.t.Fatalf("decode %s %s: %v: %s", method, path, err, rec.Body) + } + } + return rec.Code, e +} + +func TestGateRoutesOpenAnswerAcrossRestart(t *testing.T) { + f := newGateFixture(t) + req := api.GateRequest{Subject: "Approve experiment budget for cache-17", Context: json.RawMessage(`{"budget_usd":40}`), OpenedBy: "nous-campaign-42"} + var g api.Gate + if code, e := f.call("atlas", http.MethodPost, api.PathGates, req, &g); code != http.StatusCreated { + t.Fatalf("open: %d %+v", code, e) + } + if g.Status != api.GateWaiting || g.OpenedByPrincipal != "project:atlas" || g.OpenedBy != "nous-campaign-42" || strings.Join(g.Choices, ",") != "approve,deny" || g.Timeout != "0" { + t.Fatalf("opened = %+v", g) + } + var again api.Gate + if code, _ := f.call("atlas", http.MethodPost, api.PathGates, req, &again); code != http.StatusOK || again.ID != g.ID { + t.Fatalf("reopen: %d %+v", code, again) + } + + // Visibility: beacon neither reads nor lists atlas's gate; the operator does. + if code, e := f.call("beacon", http.MethodGet, api.GatePath(g.ID), nil, nil); code != http.StatusForbidden || e.Code != api.CodeForbidden { + t.Fatalf("beacon get: %d %+v", code, e) + } + var list api.GateList + if code, _ := f.call("beacon", http.MethodGet, api.PathGates, nil, &list); code != http.StatusOK || len(list.Gates) != 0 { + t.Fatalf("beacon list: %d %+v", code, list) + } + if code, _ := f.call("operator", http.MethodGet, api.PathGates+"?status=waiting", nil, &list); code != http.StatusOK || len(list.Gates) != 1 { + t.Fatalf("operator list: %d %+v", code, list) + } + if code, e := f.call("operator", http.MethodGet, api.PathGates+"?status=pending", nil, nil); code != http.StatusBadRequest || e.Code != api.CodeBadRequest { + t.Fatalf("bad status filter: %d %+v", code, e) + } + + // Only the operator answers, and only with an offered choice. + if code, e := f.call("atlas", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "approve"}, nil); code != http.StatusForbidden || e.Code != api.CodeForbidden { + t.Fatalf("project answer: %d %+v", code, e) + } + if code, e := f.call("operator", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "looks fine to me"}, nil); code != http.StatusUnprocessableEntity || e.Code != api.CodeGateInvalidChoice { + t.Fatalf("free-text answer: %d %+v", code, e) + } + + f.restart() + var answered api.Gate + if code, e := f.call("operator", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "approve", Note: "within budget"}, &answered); code != http.StatusOK { + t.Fatalf("answer after restart: %d %+v", code, e) + } + if answered.Status != api.GateAnswered || answered.Answer != "approve" || answered.AnsweredBy != "kelly" || answered.AnsweredByPrincipal != "operator:kelly" || answered.Note != "within budget" { + t.Fatalf("answered = %+v", answered) + } + var reopened api.Gate + if code, _ := f.call("atlas", http.MethodPost, api.PathGates, req, &reopened); code != http.StatusOK || reopened.ID != g.ID || reopened.Answer != "approve" { + t.Fatalf("reopen after answer: %d %+v", code, reopened) + } + var waited api.Gate + if code, _ := f.call("atlas", http.MethodGet, api.GateWaitPath(g.ID)+"?timeout=1s", nil, &waited); code != http.StatusOK || waited.Status != api.GateAnswered { + t.Fatalf("wait: %d %+v", code, waited) + } + if code, e := f.call("operator", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "deny"}, nil); code != http.StatusConflict || e.Code != api.CodeGateClosed { + t.Fatalf("second answer: %d %+v", code, e) + } + if code, e := f.call("operator", http.MethodGet, api.GatePath("gate_missing"), nil, nil); code != http.StatusNotFound || e.Code != api.CodeNotFound { + t.Fatalf("unknown gate: %d %+v", code, e) + } +} + +func TestGateSelfAnswerNeedsAuditedOverride(t *testing.T) { + f := newGateFixture(t) + events := f.s.subscribe() + defer f.s.unsubscribe(events) + var g api.Gate + if code, e := f.call("operator", http.MethodPost, api.PathGates, api.GateRequest{Subject: "self-serve", Context: json.RawMessage(`{"secret_plan":"x"}`)}, &g); code != http.StatusCreated { + t.Fatalf("open: %d %+v", code, e) + } + if code, e := f.call("operator", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "approve"}, nil); code != http.StatusForbidden || e.Code != api.CodeGateSelfAnswer { + t.Fatalf("self answer: %d %+v", code, e) + } + var answered api.Gate + if code, e := f.call("operator", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "approve", AsOperator: true}, &answered); code != http.StatusOK || !answered.OperatorOverride { + t.Fatalf("override: %d %+v %+v", code, e, answered) + } + var types []string + for len(events) > 0 { + ev := <-events + types = append(types, ev.Type) + if strings.HasPrefix(ev.Type, "gate.") && strings.Contains(string(ev.Data), "secret_plan") { + t.Fatalf("event %s carries the context: %s", ev.Type, ev.Data) + } + if ev.Type == api.EventAudit && !strings.Contains(string(ev.Data), "gate.operator_override") { + t.Fatalf("audit = %s", ev.Data) + } + } + if strings.Join(types, ",") != api.EventGateOpened+","+api.EventGateAnswered+","+api.EventAudit { + t.Fatalf("events = %v", types) + } +} + +func TestGateContextLimitAndExpiry(t *testing.T) { + f := newGateFixture(t) + big := json.RawMessage(`{"blob":"` + strings.Repeat("x", gates.MaxContextBytes) + `"}`) + if code, e := f.call("atlas", http.MethodPost, api.PathGates, api.GateRequest{Subject: "huge", Context: big}, nil); code != http.StatusRequestEntityTooLarge || e.Code != api.CodeGateContextTooLarge { + t.Fatalf("large context: %d %+v", code, e) + } + if code, e := f.call("atlas", http.MethodPost, api.PathGates, api.GateRequest{Subject: "when?", Timeout: "soon"}, nil); code != http.StatusBadRequest || e.Code != api.CodeBadRequest { + t.Fatalf("bad timeout: %d %+v", code, e) + } + var g api.Gate + if code, e := f.call("atlas", http.MethodPost, api.PathGates, api.GateRequest{Subject: "quick", Timeout: "1m"}, &g); code != http.StatusCreated || g.ExpiresAt == nil { + t.Fatalf("open: %d %+v %+v", code, e, g) + } + f.clock.advance(2 * time.Minute) + var expired api.Gate + if code, _ := f.call("atlas", http.MethodGet, api.GateWaitPath(g.ID), nil, &expired); code != http.StatusOK || expired.Status != api.GateExpired || expired.Answer != "" { + t.Fatalf("expired: %d %+v", code, expired) + } + if code, e := f.call("operator", http.MethodPost, api.GateAnswerPath(g.ID), api.GateAnswerRequest{Answer: "deny"}, nil); code != http.StatusConflict || e.Code != api.CodeGateClosed { + t.Fatalf("answer after expiry: %d %+v", code, e) + } + if code, e := f.call("atlas", http.MethodGet, api.GateWaitPath(g.ID)+"?timeout=-1s", nil, nil); code != http.StatusBadRequest || e.Code != api.CodeBadRequest { + t.Fatalf("bad wait timeout: %d %+v", code, e) + } +} + +func TestGateRoutesWithoutService(t *testing.T) { + f := newGateFixture(t) + f.s.Gates = nil + f.h = f.s.Handler() + if code, e := f.call("operator", http.MethodGet, api.PathGates, nil, nil); code != http.StatusNotImplemented || e.Code != api.CodeNotSupported { + t.Fatalf("no service: %d %+v", code, e) + } +} diff --git a/src/crux/serve/serve.go b/src/crux/serve/serve.go index dd3da2065c..7b6fe5e204 100644 --- a/src/crux/serve/serve.go +++ b/src/crux/serve/serve.go @@ -37,6 +37,7 @@ import ( "github.com/hivecommons/hive/crux/api" "github.com/hivecommons/hive/crux/checkout" "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/gates" "github.com/hivecommons/hive/crux/lanes" "github.com/hivecommons/hive/crux/runs" ) @@ -114,6 +115,10 @@ type Server struct { // S7); nil answers those routes with not_supported. Runs *runs.Service + // Gates, when set, serves the human-gate family (RFC crux#114 S3, + // api.PathGates) and relays gate.* events; nil answers those routes 501. + Gates *gates.Service + now func() time.Time started time.Time @@ -172,6 +177,7 @@ func (s *Server) Handler() http.Handler { s.registerFamilies(mux) s.registerCheckouts(mux) s.registerRuns(mux) + s.registerGates(mux) return s.laneHandler(s.authenticate(instrument(mux))) } diff --git a/src/docs/crux-serve.md b/src/docs/crux-serve.md index 31e79e8b47..339ef6036c 100644 --- a/src/docs/crux-serve.md +++ b/src/docs/crux-serve.md @@ -97,6 +97,7 @@ and [lane error codes and failure behavior](crux-lanes.md#bounds-and-failure-beh | `GET /v1/events` | | watcher + `Kicker.SetKickObserver` + the `crux.Host` observers | `text/event-stream` of `Event` records | | `POST /v1/checkouts`, `GET /v1/checkouts[?owner=]`, `GET`/`DELETE /v1/checkouts/{id}` | `{"repo","commit","owner"?,"branches"?,"max_bytes"?,"ttl"?}` | `checkout.Service` | Work service (S1): a worktree pinned at a full SHA, owned by the caller principal; `501` without `--checkout-allow`; [routes, codes and semantics](design/crux-work-services.md) | | `POST /v1/runs`, `GET /v1/runs/{id}`, `POST /v1/runs/{id}/cancel` | contained-run request (see `ContainedRunRequest` in `crux/api/runs.go`) | `runs.Service` | Work service (S2/S7): run an untrusted command in a sandbox and read the saved record whatever the process state; cancel after completion returns the result; `501` on `POST` without `--runs-config`; restart and listing routes are [deferred](design/crux-work-services.md#deferred-runs-routes) | +| `POST /v1/gates`, `GET /v1/gates[?status=]`, `GET /v1/gates/{id}`, `POST /v1/gates/{id}/answer`, `GET /v1/gates/{id}/wait[?timeout=]` | `{"subject","context"?,"choices"?,"timeout"?,"opened_by"?,"idempotency_key"?}`; answer `{"answer","note"?,"as_operator"?}` | `gates.Service` | Work service (S3): human gates under `/gates`, always on; re-opening the same gate returns the same id and recorded answer; only the operator answers, the opener only with the audited `as_operator` override; [routes, codes and semantics](design/crux-work-services.md#s3-human-gate) | | `GET /v1/lanes` and lane/group subroutes | Publish/recovery/receipt JSON; [request shapes](crux-lanes.md#public-http-and-go-api) | `lanes.Broker` | Opt-in only; lane-project credential and capability ACLs; JSON or `204`; [full routes and responses](crux-lanes.md#public-http-and-go-api) | ### Runtime families (#14138 stage 3) @@ -174,6 +175,7 @@ every 15 s. `Event` is `{"time","type","agent","state","detail","data"}`. | `agent.started`, `agent.stopped`, `agent.kicked` | the API performed the action | | `agent.state` | the server's watcher (polls `AllStatuses` every second) saw an agent change state for any reason: crash, restart, pause; `state` is the new state, `detail` the last restart reason when there is one | | `agent.kick` | the runtime's kick observer fired (`Kicker.SetKickObserver`); `detail` is the observer's event name | +| `gate.opened`, `gate.answered`, `gate.expired` | a human gate (S3) was opened, answered or expired; `data` is the `api.Gate` record without its `context`. An `as_operator` answer also emits `runtime.audit` with action `gate.operator_override` | | `agent.kick_outcome`, `agent.pause_transition`, `agent.relaunch`, `agent.pause_persist`, `agent.prompt`, `agent.sandbox_audit`, `runtime.audit`, `runtime.condition` | the `crux.Host` observers, relayed when the runtime is a Host; `data` carries the typed payload (`api.KickOutcome`, `api.PauseTransition`, …). A sidecar hive demuxes these into the observers its boot sequence installs (`cmd/hive`'s `sidecarHost`) | A subscriber that stops reading is dropped after 64 buffered events so one diff --git a/src/docs/design/crux-work-services.md b/src/docs/design/crux-work-services.md index 968b84446c..cbc90ba6c8 100644 --- a/src/docs/design/crux-work-services.md +++ b/src/docs/design/crux-work-services.md @@ -1,7 +1,7 @@ # Crux work services: S1 pinned checkout (hivecommons/crux#114) Status: **S0 caller principals and S1 pinned checkout shipped in hive -`src/crux` (v5).** S2 contained run and S7 minimum shipped in #17014; everything else in the RFC is unscheduled. This records +`src/crux` (v5).** S2 contained run and S7 minimum shipped in #17014; S3 human gate is [below](#s3-human-gate); everything else in the RFC is unscheduled. This records S1 *as implemented*, including where it is weaker than the RFC text. The RFC asks for "a working copy of this repo at this commit, owned by @@ -152,6 +152,89 @@ does: a run is owned by the principal that created it, and only the owner or the operator may read or cancel it. While a run is live its checkout cannot be deleted (409 `conflict`); once the run settles, it can. +## S3. Human gate + +A driver asks a person to decide something before it continues; the +answer is recorded and survives a restart of `crux serve`. Package +`src/crux/gates` (`gates.Service`), API types in `src/crux/api/gates.go`, +routes in `src/crux/serve/gates.go`, CLI in `src/crux/cli/gate.go`. The +service needs no configuration: `crux serve` always opens it on +`/gates`. + +| Route | Body | Response | +|---|---|---| +| `POST /v1/gates` | `{"subject", "context"?, "choices"?, "timeout"?, "opened_by"?, "idempotency_key"?}` | `201 Gate` new; `200 Gate` the same gate re-opened | +| `GET /v1/gates[?status=waiting\|answered\|expired]` | | `200 {"gates":[Gate…]}` oldest first | +| `GET /v1/gates/{id}` | | `200 Gate` | +| `POST /v1/gates/{id}/answer` | `{"answer", "note"?, "as_operator"?}` | `200 Gate` | +| `GET /v1/gates/{id}/wait[?timeout=30s]` | | `200 Gate` once answered or expired, or still `waiting` when the window (default 30 s, capped at 5 min) closes | + +`Gate` is `{"id","status","subject","context"?,"choices","timeout", +"opened_by","opened_by_principal","opened_at","expires_at"?,"answer"?, +"answered_by"?,"answered_by_principal"?,"answered_at"?,"note"?, +"operator_override"?,"expired_at"?}`. + +``` +crux --server ADDR gate open --subject S [--choice C]… [--timeout D] [--context JSON] [--opened-by L] [--idempotency-key K] [--json] +crux --server ADDR gate list [--status S] [--json] +crux --server ADDR gate answer --choice C [--note TEXT] [--as-operator] [--json] +crux --server ADDR gate wait [--timeout D] [--json] +``` + +`gate wait` prints the answer and exits 0, or exits 1 with nothing on +stdout when the gate expired. Like `runs`, the verb exists only with +`--server`: the server is the single writer that records identities, +journals decisions and publishes events. + +| Condition | Status | `code` | +|---|---|---| +| empty subject, bad `timeout`, duplicate or empty choices, `context` not one JSON value, unknown `status` filter | 400 | `bad_request` | +| a project answering, or reading a gate another principal opened | 403 | `forbidden` | +| the opener answering its own gate without `as_operator` | 403 | `gate_self_answer` | +| unknown id | 404 | `not_found` | +| a different answer to an answered gate, any answer to an expired one | 409 | `gate_closed` | +| `context` over 64 KiB once encoded | 413 | `gate_context_too_large` | +| `answer` not one of `choices` (free text belongs in `note`) | 422 | `gate_invalid_choice` | +| the server has no gate service | 501 | `not_supported` | + +**Semantics.** + +- *Idempotent open.* The key is derived the way `toolapprove`'s inbox + derives one: from the subject, the canonically re-encoded context + (object keys sorted), the choices, the timeout and `opened_by` — never + timestamps — or from `idempotency_key` when given. Either form is + scoped to the opening principal. Re-opening returns the existing record + in whatever state it is in, including the recorded answer. +- *Who answers.* Only the operator principal. Projects open, read, list + and wait on their own gates. When the answering principal is the one + that opened the gate, `as_operator` is required; the record and journal + carry `operator_override: true` and the server emits a `runtime.audit` + event (`gate.operator_override`). Retrying the exact recorded answer is + a no-op `200`, not a conflict. +- *Expiry.* `timeout` is a Go duration; `"0"` or absent waits + indefinitely. A gate past its deadline becomes `expired` with no + answer the first time anything reads it, and a waiter's own timer flips + it at the deadline. Expiry is neither approval nor denial. +- *Secrets.* Subject, note, `opened_by` and every string inside + `context` pass through `logscrub.ScrubString` before they are stored. + Events and the journal never carry `context` or `note`. + +**Storage.** + +``` +gates/pending/.json waiting gates, 0600, tmp+rename +gates/resolved/.json answered or expired gates, kept forever +gates/gates.jsonl append-only {at, op, id, status, by?, answer?, operator_override?, expires_at?} +``` + +Resolving writes the resolved record before removing the pending one; +after a crash between the two, the resolved copy wins on the next start. + +**Deliberately not in S3.** No background sweeper (expiry is observed on +read and by waiters, so a gate nobody looks at stays `waiting` on disk +past its deadline until the next read); no in-process `crux gate` form; +no per-gate answerer allowlist beyond "the operator". + ## Deliberately not in S1 - TTL sweeper (recorded, not enforced). @@ -177,3 +260,7 @@ for runs are deferred and not scheduled. | `src/crux/serve/checkouts.go` | routes, ownership checks, error mapping; registered from `Server.Handler` after the runtime families and marked a work service for S0 | | `src/crux/serve/principal.go` | S0: `Principal`, `CallerFrom`, work-service gating | | `src/crux/cli/checkout.go` | `crux checkout add|rm|list`, local and remote | +| `src/crux/gates/` | S3: `Service`, `Record`, `Caller`, `DeriveIdempotencyKey`, typed sentinels (`ErrBadRequest`, `ErrContextTooLarge`, `ErrNotFound`, `ErrInvalidChoice`, `ErrSelfAnswer`, `ErrForbidden`, `ErrClosed`); pending/resolved store and journal | +| `src/crux/api/gates.go` | `PathGates`, `CodeGate*`, `EventGate*`, request/response types, `Client.{Open,List,Get,Answer,Wait}Gate` | +| `src/crux/serve/gates.go` | gate routes, visibility, error mapping, `gate.*` events and override audit | +| `src/crux/cli/gate.go` | `crux gate open|list|answer|wait`, remote only | From 7e1bb92530f6e15a3b09b745257a0989473dd6c4 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sun, 8 Nov 2026 08:18:54 -0500 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=8C=B1=20test:=20compare=20the=20gate?= =?UTF-8?q?=20list=20context=20compacted?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The list output is indented, so the raw context carries whitespace and a byte-for-byte compare against the compact literal fails. Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- src/crux/cli/gate_test.go | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/crux/cli/gate_test.go b/src/crux/cli/gate_test.go index 5f94811015..927b573584 100644 --- a/src/crux/cli/gate_test.go +++ b/src/crux/cli/gate_test.go @@ -1,6 +1,7 @@ package cli import ( + "bytes" "encoding/json" "net/http/httptest" "path/filepath" @@ -96,9 +97,15 @@ func TestGateOpenAnswerWait(t *testing.T) { h, code = remote("list", "--status", "answered", "--json") var list []api.Gate if err := json.Unmarshal(h.stdout.Bytes(), &list); code != ExitOK || err != nil || len(list) != 1 || list[0].AnsweredBy != "kelly" || - !list[0].OperatorOverride || list[0].Note != "green" || list[0].OpenedBy != "release-bot" || string(list[0].Context) != `{"pr":17}` { + !list[0].OperatorOverride || list[0].Note != "green" || list[0].OpenedBy != "release-bot" { t.Fatalf("list: %d %v %s", code, err, h.stdout) } + // The list output is indented, so the raw context carries that + // whitespace; compare it compacted. + var compact bytes.Buffer + if err := json.Compact(&compact, list[0].Context); err != nil || compact.String() != `{"pr":17}` { + t.Fatalf("list context: %v %q", err, list[0].Context) + } // Expiry is reported as its own outcome: nothing on stdout, exit 1. h, _ = remote("open", "--subject", "quick", "--timeout", "1m") From 283baeb509f056b2b14124273c339b68692b30b6 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Sun, 8 Nov 2026 07:44:30 -0700 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=8C=B1=20test:=20cover=20gate=20bound?= =?UTF-8?q?s,=20storage=20failures=20and=20the=20work-services=20client?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The coverage gate put crux/gates at 83%, crux/api at 87% and crux/cli at 91% against floors of 90, 90 and 92. Exercise the request bounds, id shape, default clock and id minting, the crash ordering between the resolved and pending copies, corrupt and stray records, and journal and directory failures in gates; drive the typed gates, checkouts and runs client methods against a recording fake in api; and cover the --json outputs, the list table, --timeout on wait and the typed failure codes in the CLI. No sleeps: the one timed wait is a 50ms context deadline. Signed-off-by: Andrew Anderson --- src/crux/api/gates_test.go | 222 ++++++++++++++++++++++++++++++++++- src/crux/cli/gate_test.go | 69 +++++++++++ src/crux/gates/gates_test.go | 182 ++++++++++++++++++++++++++++ 3 files changed, 472 insertions(+), 1 deletion(-) diff --git a/src/crux/api/gates_test.go b/src/crux/api/gates_test.go index a70c0ca832..30a9023100 100644 --- a/src/crux/api/gates_test.go +++ b/src/crux/api/gates_test.go @@ -1,6 +1,17 @@ package api -import "testing" +import ( + "context" + "encoding/json" + "errors" + "io" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" +) func TestGatePathsAndCodes(t *testing.T) { if PathGates != "/v1/gates" || GatePath("gate_a") != "/v1/gates/gate_a" || @@ -15,3 +26,212 @@ func TestGatePathsAndCodes(t *testing.T) { seen[code] = true } } + +// workServicesServer is the work-services half of the wire contract +// (checkouts, runs, gates): it records every request and answers canned +// records so the typed client methods are tested against the contract, +// not crux/serve. +type workServicesServer struct { + mu sync.Mutex + requests []string + bodies []string +} + +func (s *workServicesServer) handler() http.Handler { + mux := http.NewServeMux() + record := func(h http.HandlerFunc) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + data, _ := io.ReadAll(r.Body) + s.mu.Lock() + s.requests = append(s.requests, r.Method+" "+r.URL.RequestURI()) + s.bodies = append(s.bodies, string(data)) + s.mu.Unlock() + h(w, r) + } + } + writeJSON := func(w http.ResponseWriter, status int, v any) { + w.Header().Set("Content-Type", ContentTypeJSON) + w.WriteHeader(status) + _ = json.NewEncoder(w).Encode(v) + } + opened := time.Date(2026, 11, 8, 12, 0, 0, 0, time.UTC) + gate := func(id, status string) Gate { + return Gate{ID: id, Status: status, Subject: "ship?", Choices: []string{"ship", "hold"}, Timeout: "0", OpenedBy: "atlas", OpenedByPrincipal: "project:atlas", OpenedAt: opened} + } + + mux.HandleFunc("POST "+PathGates, record(func(w http.ResponseWriter, _ *http.Request) { + writeJSON(w, http.StatusCreated, gate("gate_1", GateWaiting)) + })) + mux.HandleFunc("GET "+PathGates, record(func(w http.ResponseWriter, _ *http.Request) { + writeJSON(w, http.StatusOK, GateList{Gates: []Gate{gate("gate_1", GateWaiting), gate("gate_2", GateExpired)}}) + })) + mux.HandleFunc("GET "+PathGates+"/{id}", record(func(w http.ResponseWriter, r *http.Request) { + if r.PathValue("id") == "gate_missing" { + writeJSON(w, http.StatusNotFound, Error{Error: "gate gate_missing", Code: CodeNotFound}) + return + } + writeJSON(w, http.StatusOK, gate(r.PathValue("id"), GateWaiting)) + })) + mux.HandleFunc("POST "+PathGates+"/{id}/answer", record(func(w http.ResponseWriter, r *http.Request) { + var in GateAnswerRequest + _ = json.NewDecoder(strings.NewReader(s.lastBody())).Decode(&in) + if in.Answer == "sure" { + writeJSON(w, http.StatusUnprocessableEntity, Error{Error: `"sure" is not one of ship, hold`, Code: CodeGateInvalidChoice}) + return + } + g := gate(r.PathValue("id"), GateAnswered) + g.Answer, g.AnsweredBy, g.Note, g.OperatorOverride = in.Answer, "kelly", in.Note, in.AsOperator + writeJSON(w, http.StatusOK, g) + })) + mux.HandleFunc("GET "+PathGates+"/{id}/wait", record(func(w http.ResponseWriter, r *http.Request) { + g := gate(r.PathValue("id"), GateAnswered) + g.Answer = "ship" + writeJSON(w, http.StatusOK, g) + })) + + mux.HandleFunc("POST "+PathCheckouts, record(func(w http.ResponseWriter, _ *http.Request) { + writeJSON(w, http.StatusCreated, Checkout{ID: "co_1", Repo: "https://github.com/org/name.git", Commit: strings.Repeat("a", 40), CreatedAt: opened}) + })) + mux.HandleFunc("GET "+PathCheckouts, record(func(w http.ResponseWriter, _ *http.Request) { + writeJSON(w, http.StatusOK, CheckoutList{Checkouts: []Checkout{{ID: "co_1"}}}) + })) + mux.HandleFunc("GET "+PathCheckouts+"/{id}", record(func(w http.ResponseWriter, r *http.Request) { + writeJSON(w, http.StatusOK, Checkout{ID: r.PathValue("id")}) + })) + mux.HandleFunc("DELETE "+PathCheckouts+"/{id}", record(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNoContent) + })) + + mux.HandleFunc("POST "+PathRuns, record(func(w http.ResponseWriter, _ *http.Request) { + writeJSON(w, http.StatusCreated, ContainedRun{ID: "run_1", Status: "running", CreatedAt: opened}) + })) + mux.HandleFunc("GET "+PathRuns+"/{id}", record(func(w http.ResponseWriter, r *http.Request) { + writeJSON(w, http.StatusOK, ContainedRun{ID: r.PathValue("id"), Status: "succeeded"}) + })) + mux.HandleFunc("POST "+PathRuns+"/{id}/cancel", record(func(w http.ResponseWriter, r *http.Request) { + writeJSON(w, http.StatusOK, ContainedRun{ID: r.PathValue("id"), Status: "cancelled"}) + })) + return mux +} + +func (s *workServicesServer) lastBody() string { + s.mu.Lock() + defer s.mu.Unlock() + return s.bodies[len(s.bodies)-1] +} + +func (s *workServicesServer) seen() (requests, bodies []string) { + s.mu.Lock() + defer s.mu.Unlock() + return append([]string(nil), s.requests...), append([]string(nil), s.bodies...) +} + +func TestWorkServicesClientRoutesAndDecodes(t *testing.T) { + s := &workServicesServer{} + srv := httptest.NewServer(s.handler()) + t.Cleanup(srv.Close) + c, err := NewClient(srv.URL, "tok") + if err != nil { + t.Fatal(err) + } + ctx := context.Background() + + g, err := c.OpenGate(ctx, GateRequest{Subject: "ship?", Context: json.RawMessage(`{"pr":17}`), Choices: []string{"ship", "hold"}, Timeout: "1h", OpenedBy: "atlas", IdempotencyKey: "k1"}) + if err != nil || g.ID != "gate_1" || g.Status != GateWaiting || g.OpenedByPrincipal != "project:atlas" || !g.OpenedAt.Equal(time.Date(2026, 11, 8, 12, 0, 0, 0, time.UTC)) { + t.Fatalf("open %+v %v", g, err) + } + all, err := c.ListGates(ctx, "") + if err != nil || len(all) != 2 || all[1].Status != GateExpired { + t.Fatalf("list %+v %v", all, err) + } + if _, err := c.ListGates(ctx, GateWaiting); err != nil { + t.Fatalf("list waiting %v", err) + } + if g, err = c.GetGate(ctx, "gate_1"); err != nil || g.ID != "gate_1" { + t.Fatalf("get %+v %v", g, err) + } + var se *StatusError + if _, err := c.GetGate(ctx, "gate_missing"); !errors.As(err, &se) || se.Status != http.StatusNotFound || se.Body.Code != CodeNotFound { + t.Fatalf("missing gate: %v", err) + } + if _, err := c.AnswerGate(ctx, "gate_1", GateAnswerRequest{Answer: "sure"}); !errors.As(err, &se) || se.Status != http.StatusUnprocessableEntity || se.Body.Code != CodeGateInvalidChoice { + t.Fatalf("off-menu answer: %v", err) + } + g, err = c.AnswerGate(ctx, "gate 1", GateAnswerRequest{Answer: "ship", Note: "green", AsOperator: true}) + if err != nil || g.Status != GateAnswered || g.Answer != "ship" || g.AnsweredBy != "kelly" || g.Note != "green" || !g.OperatorOverride { + t.Fatalf("answer %+v %v", g, err) + } + if g, err = c.WaitGate(ctx, "gate_1", 0); err != nil || g.Answer != "ship" { + t.Fatalf("wait %+v %v", g, err) + } + if g, err = c.WaitGate(ctx, "gate_1", 90*time.Second); err != nil || g.Status != GateAnswered { + t.Fatalf("wait with window %+v %v", g, err) + } + + co, err := c.CreateCheckout(ctx, CheckoutRequest{Repo: "https://github.com/org/name.git", Commit: strings.Repeat("a", 40), Owner: "nous-1"}) + if err != nil || co.ID != "co_1" { + t.Fatalf("create checkout %+v %v", co, err) + } + if cos, err := c.ListCheckouts(ctx, "nous 1"); err != nil || len(cos) != 1 { + t.Fatalf("list checkouts %+v %v", cos, err) + } + if cos, err := c.ListCheckouts(ctx, ""); err != nil || len(cos) != 1 { + t.Fatalf("list all checkouts %+v %v", cos, err) + } + if co, err = c.GetCheckout(ctx, "co 1"); err != nil || co.ID != "co 1" { + t.Fatalf("get checkout %+v %v", co, err) + } + if err := c.DeleteCheckout(ctx, "co_1"); err != nil { + t.Fatalf("delete checkout %v", err) + } + + run, err := c.CreateRun(ctx, ContainedRunRequest{Command: []string{"make", "test"}}) + if err != nil || run.ID != "run_1" || run.Status != "running" { + t.Fatalf("create run %+v %v", run, err) + } + if run, err = c.GetRun(ctx, "run_1"); err != nil || run.Status != "succeeded" { + t.Fatalf("get run %+v %v", run, err) + } + if run, err = c.CancelRun(ctx, "run_1"); err != nil || run.Status != "cancelled" { + t.Fatalf("cancel run %+v %v", run, err) + } + + requests, bodies := s.seen() + wantRequests := []string{ + "POST /v1/gates", + "GET /v1/gates", + "GET /v1/gates?status=waiting", + "GET /v1/gates/gate_1", + "GET /v1/gates/gate_missing", + "POST /v1/gates/gate_1/answer", + "POST /v1/gates/gate%201/answer", + "GET /v1/gates/gate_1/wait", + "GET /v1/gates/gate_1/wait?timeout=1m30s", + "POST /v1/checkouts", + "GET /v1/checkouts?owner=nous+1", + "GET /v1/checkouts", + "GET /v1/checkouts/co%201", + "DELETE /v1/checkouts/co_1", + "POST /v1/runs", + "GET /v1/runs/run_1", + "POST /v1/runs/run_1/cancel", + } + if strings.Join(requests, "\n") != strings.Join(wantRequests, "\n") { + t.Fatalf("requests:\n%s\nwant:\n%s", strings.Join(requests, "\n"), strings.Join(wantRequests, "\n")) + } + for i, want := range map[int]string{ + 0: `"subject":"ship?","context":{"pr":17},"choices":["ship","hold"],"timeout":"1h","opened_by":"atlas","idempotency_key":"k1"`, + 6: `{"answer":"ship","note":"green","as_operator":true}`, + 9: `"owner":"nous-1"`, + 14: `"command":["make","test"]`, + } { + if !strings.Contains(bodies[i], want) { + t.Errorf("request %d %s: body %q lacks %q", i, requests[i], bodies[i], want) + } + } + for _, i := range []int{1, 3, 7, 11, 13, 15} { + if bodies[i] != "" { + t.Errorf("request %d %s: unexpected body %q", i, requests[i], bodies[i]) + } + } +} diff --git a/src/crux/cli/gate_test.go b/src/crux/cli/gate_test.go index 927b573584..6735963b1f 100644 --- a/src/crux/cli/gate_test.go +++ b/src/crux/cli/gate_test.go @@ -141,3 +141,72 @@ func TestGateUsage(t *testing.T) { } } } + +func TestGateOutputsAndFailures(t *testing.T) { + t.Setenv(config.ServerEnvVar, "") + t.Setenv(config.ServeTokenEnvVar, "") + g := newGateServer(t) + remote := func(args ...string) (*harness, int) { + h := newHarness(t) + return h, h.run(append([]string{"--server", g.url, "--token", "gate-token", "gate"}, args...)...) + } + + h, code := remote("open", "--subject", "json please", "--json") + var opened api.Gate + if err := json.Unmarshal(h.stdout.Bytes(), &opened); code != ExitOK || err != nil || opened.Status != api.GateWaiting || strings.Join(opened.Choices, ",") != "approve,deny" { + t.Fatalf("open --json: %d %v %s", code, err, h.stdout) + } + h, code = remote("answer", opened.ID, "--choice", "deny", "--as-operator", "--json") + var answered api.Gate + if err := json.Unmarshal(h.stdout.Bytes(), &answered); code != ExitOK || err != nil || answered.Answer != "deny" || !answered.OperatorOverride { + t.Fatalf("answer --json: %d %v %s", code, err, h.stdout) + } + h, code = remote("wait", opened.ID, "--json") + var waited api.Gate + if err := json.Unmarshal(h.stdout.Bytes(), &waited); code != ExitOK || err != nil || waited.Answer != "deny" { + t.Fatalf("wait --json: %d %v %s", code, err, h.stdout) + } + g.advance(time.Second) + h, _ = remote("open", "--subject", "still open") + open := strings.Fields(h.stdout.String())[0] + + // The table lists both, answered first (it was opened first), with + // the answerer beside the answer and a dash for none. + h, code = remote("list") + lines := strings.Split(strings.TrimSpace(h.stdout.String()), "\n") + if code != ExitOK || len(lines) != 3 || !strings.HasPrefix(lines[0], "ID") || !strings.Contains(lines[1], "deny (kelly)") || + !strings.Contains(lines[1], "approve|deny") || !strings.Contains(lines[2], open) || !strings.Contains(lines[2], " - ") { + t.Fatalf("list: %d\n%s", code, h.stdout) + } + + // --timeout bounds the whole wait; a gate still waiting when it + // passes is reported as such, not as an error from the server. + if h, code := remote("wait", open, "--timeout", "50ms"); code != ExitError || !strings.Contains(h.stderr.String(), "still waiting") { + t.Fatalf("wait --timeout: %d %s", code, h.stderr) + } + + for _, tc := range []struct { + args []string + code int + stderr string + }{ + {[]string{"open", "--subject", "s", "extra"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"open", "--subject", "s", "--timeout", "soon"}, ExitUsage, "timeout"}, + {[]string{"open", "--subject", "s", "--choice", "a", "--choice", "a"}, ExitUsage, "duplicate choice"}, + {[]string{"list", "extra"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"answer", "--choice", "approve", "gate_a", "gate_b"}, ExitUsage, "usage: crux --server ADDR gate open"}, + {[]string{"answer", "gate_nope", "--choice", "approve"}, ExitError, "not found"}, + {[]string{"wait", "gate_nope"}, ExitError, "not found"}, + {[]string{"wait", "--timeout", "nope", "gate_a"}, ExitUsage, "invalid value"}, + } { + h := newHarness(t) + if code := h.run(append([]string{"--server", g.url, "--token", "gate-token", "gate"}, tc.args...)...); code != tc.code || !strings.Contains(h.stderr.String(), tc.stderr) { + t.Fatalf("%v: %d %s", tc.args, code, h.stderr) + } + } + + h = newHarness(t) + if code := h.run("--server", g.url, "--token", "wrong", "gate", "list"); code != ExitError || !strings.Contains(h.stderr.String(), "bearer token") { + t.Fatalf("wrong token: %d %s", code, h.stderr) + } +} diff --git a/src/crux/gates/gates_test.go b/src/crux/gates/gates_test.go index 545b10f616..1025116bfb 100644 --- a/src/crux/gates/gates_test.go +++ b/src/crux/gates/gates_test.go @@ -342,3 +342,185 @@ func TestWaitWakesOnAnswerExpiryAndWindow(t *testing.T) { t.Fatalf("cancelled wait: %v", err) } } + +func TestRequestBounds(t *testing.T) { + f := newFixture(t) + long := func(n int) string { return strings.Repeat("x", n) } + many := make([]string, MaxChoices+1) + for i := range many { + many[i] = fmt.Sprintf("c%d", i) + } + for _, tc := range []struct { + name string + req Request + want error + }{ + {"subject too long", Request{Subject: long(MaxSubjectLen + 1)}, ErrBadRequest}, + {"opened_by too long", Request{Subject: "s", OpenedBy: long(MaxOpenedByLen + 1)}, ErrBadRequest}, + {"key too long", Request{Subject: "s", IdempotencyKey: long(maxIdempotencyKeyLen + 1)}, ErrBadRequest}, + {"too many choices", Request{Subject: "s", Choices: many}, ErrBadRequest}, + {"choice too long", Request{Subject: "s", Choices: []string{long(MaxChoiceLen + 1)}}, ErrBadRequest}, + } { + if _, _, err := f.svc.Open(driver, tc.req); !errors.Is(err, tc.want) { + t.Errorf("%s: Open = %v, want %v", tc.name, err, tc.want) + } + } + // JSON null, whitespace and an absent payload all store no context; + // nested arrays are scrubbed like objects; the driver label defaults + // to the caller's name. + for _, raw := range []string{"", " ", "null"} { + rec, _, err := f.svc.Open(driver, Request{Subject: "ctx " + raw, Context: json.RawMessage(raw)}) + if err != nil || rec.Context != nil || rec.OpenedBy != "atlas" { + t.Fatalf("context %q: %+v %v", raw, rec, err) + } + } + rec, _, err := f.svc.Open(driver, Request{Subject: "nested", Context: json.RawMessage(`[{"k":["ghp_secretvalue1234567890"]}, 1.50]`)}) + if err != nil || strings.Contains(string(rec.Context), "ghp_") || !strings.Contains(string(rec.Context), "1.50") { + t.Fatalf("nested context = %s %v", rec.Context, err) + } + if _, err := f.svc.Answer(operator, rec.ID, Answer{Choice: "approve", Note: long(MaxNoteLen + 1)}); !errors.Is(err, ErrBadRequest) { + t.Fatalf("long note: %v", err) + } + if _, err := ParseTimeout("-1s"); !errors.Is(err, ErrBadRequest) { + t.Fatalf("negative timeout: %v", err) + } + if FormatTimeout(-time.Second) != "0" || FormatTimeout(90*time.Second) != "1m30s" { + t.Fatalf("FormatTimeout") + } +} + +func TestValidID(t *testing.T) { + for id, want := range map[string]bool{ + "gate_0123abcdef": true, + "gate_": false, + "run_abc": false, + "gate_ABC": false, + "gate_a/b": false, + "gate_" + strings.Repeat("a", maxIDLen): false, + } { + if got := ValidID(id); got != want { + t.Errorf("ValidID(%q) = %v, want %v", id, got, want) + } + } +} + +func TestDefaultsMintUniqueIDs(t *testing.T) { + svc, err := New(Config{Dir: filepath.Join(t.TempDir(), DirName)}) + if err != nil { + t.Fatal(err) + } + a, _, err := svc.Open(driver, Request{Subject: "a"}) + if err != nil || !ValidID(a.ID) || a.OpenedAt.IsZero() { + t.Fatalf("open with defaults: %+v %v", a, err) + } + b, _, _ := svc.Open(driver, Request{Subject: "b"}) + if a.ID == b.ID { + t.Fatalf("ids collide: %s", a.ID) + } + if !Visible(a, operator) || !Visible(a, driver) || Visible(a, Caller{Principal: "project:beacon"}) { + t.Fatalf("Visible") + } + if _, err := New(Config{}); !errors.Is(err, ErrBadRequest) { + t.Fatalf("New without dir: %v", err) + } + file := filepath.Join(t.TempDir(), "file") + if err := os.WriteFile(file, nil, 0o600); err != nil { + t.Fatal(err) + } + if _, err := New(Config{Dir: filepath.Join(file, DirName)}); err == nil { + t.Fatal("New under a file succeeded") + } +} + +func TestResolvedCopyWinsAfterCrash(t *testing.T) { + f := newFixture(t) + g, _, _ := f.svc.Open(driver, Request{Subject: "crash"}) + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "approve"}); err != nil { + t.Fatal(err) + } + // A crash between writing resolved/.json and removing + // pending/.json leaves both; the stale pending copy is the old + // waiting record. + pending := filepath.Join(f.dir, PendingDirName, g.ID+".json") + if err := os.WriteFile(pending, []byte(`{"id":"`+g.ID+`","status":"waiting","choices":["approve","deny"]}`), 0o600); err != nil { + t.Fatal(err) + } + // Stray files in the record directories are ignored. + for _, name := range []string{"notes.txt", "gate_x.json.tmp", "run_1.json"} { + if err := os.WriteFile(filepath.Join(f.dir, PendingDirName, name), []byte("{}"), 0o600); err != nil { + t.Fatal(err) + } + } + if err := os.Mkdir(filepath.Join(f.dir, ResolvedDirName, "gate_dir.json"), 0o700); err != nil { + t.Fatal(err) + } + f.restart() + if _, err := os.Stat(pending); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("stale pending copy survived restart: %v", err) + } + rec, err := f.svc.Get(g.ID) + if err != nil || rec.Status != StatusAnswered { + t.Fatalf("after crash = %+v %v", rec, err) + } + list, err := f.svc.List(ListFilter{}) + if err != nil || len(list) != 1 { + t.Fatalf("list = %+v %v", list, err) + } + if _, err := f.svc.Wait(context.Background(), "gate_missing", 0); !errors.Is(err, ErrNotFound) { + t.Fatalf("wait on unknown: %v", err) + } +} + +func TestCorruptRecordIsReported(t *testing.T) { + f := newFixture(t) + g, _, _ := f.svc.Open(driver, Request{Subject: "fine"}) + if err := os.WriteFile(filepath.Join(f.dir, PendingDirName, "gate_bad.json"), []byte("{nope"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := f.svc.Get("gate_bad"); err == nil || !strings.Contains(err.Error(), "corrupt") { + t.Fatalf("corrupt get: %v", err) + } + if _, err := f.svc.List(ListFilter{}); err == nil || !strings.Contains(err.Error(), "corrupt") { + t.Fatalf("corrupt list: %v", err) + } + if rec, err := f.svc.Get(g.ID); err != nil || rec.ID != g.ID { + t.Fatalf("healthy get beside corrupt: %+v %v", rec, err) + } + if _, err := New(Config{Dir: f.dir}); err == nil { + t.Fatal("New over a corrupt record succeeded") + } +} + +func TestStorageFailuresSurface(t *testing.T) { + f := newFixture(t) + g, _, _ := f.svc.Open(driver, Request{Subject: "before"}) + // The journal becomes a directory: the record is written but the + // append fails, and the caller hears about it. + journal := filepath.Join(f.dir, JournalName) + if err := os.Remove(journal); err != nil { + t.Fatal(err) + } + if err := os.Mkdir(journal, 0o700); err != nil { + t.Fatal(err) + } + if _, created, err := f.svc.Open(driver, Request{Subject: "journal down"}); err == nil || !created { + t.Fatalf("open with journal down: created=%v err=%v", created, err) + } + if _, err := f.svc.Answer(operator, g.ID, Answer{Choice: "deny"}); err == nil { + t.Fatal("answer with journal down succeeded") + } + // The pending directory becomes a file: nothing can be written at all. + pending := filepath.Join(f.dir, PendingDirName) + if err := os.RemoveAll(pending); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(pending, nil, 0o600); err != nil { + t.Fatal(err) + } + if _, _, err := f.svc.Open(driver, Request{Subject: "no pending dir"}); err == nil { + t.Fatal("open without a pending dir succeeded") + } + if _, err := f.svc.List(ListFilter{}); err == nil { + t.Fatal("list without a pending dir succeeded") + } +}