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..30a9023100 --- /dev/null +++ b/src/crux/api/gates_test.go @@ -0,0 +1,237 @@ +package api + +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" || + 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 + } +} + +// 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/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..6735963b1f --- /dev/null +++ b/src/crux/cli/gate_test.go @@ -0,0 +1,212 @@ +package cli + +import ( + "bytes" + "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" { + 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") + 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) + } + } +} + +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/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..1025116bfb --- /dev/null +++ b/src/crux/gates/gates_test.go @@ -0,0 +1,526 @@ +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) + } +} + +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") + } +} 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 |