diff --git a/CLAUDE.md b/CLAUDE.md index a7c9954fb..af9459b5c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -201,10 +201,10 @@ task dev # every service + Vite at http://localhost:5173, from deployments/d task e2e:up # seeded local stack; task e2e:check -- all runs the browser checks ``` -`task proto:generate` and `task db:generate` write the committed generated -output for `proto/` and `internal/infrastructure/postgres/`; `task check` runs -their check variants and rejects stale output. The e2e stack is not part of the -gate. +`task proto:generate`, `task db:generate` and `task openapi:generate` write +the committed generated output for `proto/`, `internal/infrastructure/postgres/` +and `api/openapi.yaml`; `task check` runs their check variants and rejects stale +output. The e2e stack is not part of the gate. Requires Go 1.27, Task, golangci-lint, Node, pnpm and Docker. Adopt `task fmt` and `go fix` output as-is. diff --git a/Taskfile.yml b/Taskfile.yml index 8005ce5a6..b54bef4fc 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -64,6 +64,18 @@ tasks: - task: db:generate - git diff --exit-code -- internal/infrastructure/postgres/postgresdb + openapi:generate: + desc: Write the API's OpenAPI document to api/openapi.yaml + cmds: + - mkdir -p api + - go run ./cmd/archie openapi > api/openapi.yaml + + openapi:check: + desc: Regenerate the OpenAPI document and reject uncommitted differences + cmds: + - task: openapi:generate + - git diff --exit-code -- api/openapi.yaml + proto:check: desc: Regenerate contracts and reject uncommitted generated differences cmds: @@ -311,6 +323,7 @@ tasks: - task: fmt - task: proto:check - task: db:check + - task: openapi:check - task: check:readonly check:readonly: diff --git a/api/openapi.yaml b/api/openapi.yaml new file mode 100644 index 000000000..e2f2aa26c --- /dev/null +++ b/api/openapi.yaml @@ -0,0 +1,3111 @@ +components: + schemas: + AnswerInputBody: + additionalProperties: false + properties: + approved: + type: boolean + required: + - approved + type: object + ApprovalsView: + additionalProperties: false + properties: + action: + type: string + answered_at: + format: date-time + type: string + answered_by: + type: string + answered_via: + type: string + deadline: + format: date-time + type: string + decision_id: + type: string + id: + type: string + kind: + type: string + level: + type: string + requested_at: + format: date-time + type: string + run_id: + type: string + state: + type: string + step: + format: int64 + type: integer + step_deadline: + format: date-time + type: string + summary: + type: string + target: + type: string + required: + - id + - kind + - run_id + - action + - target + - level + - summary + - state + - deadline + - step + - decision_id + - requested_at + type: object + AuditjsonPayload: + additionalProperties: false + properties: + json: {} + length: + format: int64 + type: integer + sha256: + type: string + text: + type: string + truncated: + type: boolean + type: object + ConnectorsAcceptRequest: + additionalProperties: false + properties: + credentials: + additionalProperties: + type: string + type: object + egress: + description: Every host the extension may reach + items: + type: string + type: + - array + - "null" + env: + description: Host environment variables the extension may see + items: + type: string + type: + - array + - "null" + path: + description: The extension binary on the host + type: string + settings: + additionalProperties: + type: string + type: object + sha256: + description: The binary's digest; it runs only while the digest matches + type: string + required: + - path + - sha256 + type: object + ConnectorsCall: + additionalProperties: false + properties: + connector: + type: string + error: + type: string + method: + type: string + request: + $ref: "#/components/schemas/AuditjsonPayload" + response: + $ref: "#/components/schemas/AuditjsonPayload" + required: + - connector + - method + - request + type: object + ConnectorsCredentialRequest: + additionalProperties: false + properties: + fields: + additionalProperties: + $ref: "#/components/schemas/ConnectorsField" + type: object + kind: + type: string + required: + - kind + - fields + type: object + ConnectorsCredentialSaved: + additionalProperties: false + properties: + kind: + type: string + name: + type: string + restarted: + items: + type: string + type: + - array + - "null" + required: + - name + - kind + - restarted + type: object + ConnectorsCredentialView: + additionalProperties: false + properties: + fields: + additionalProperties: + type: string + type: object + kind: + type: string + name: + type: string + required: + - name + - kind + - fields + type: object + ConnectorsEffect: + additionalProperties: false + properties: + ReadOnly: + type: boolean + Reversibility: + format: int64 + type: integer + Summary: + type: string + required: + - ReadOnly + - Reversibility + - Summary + type: object + ConnectorsExtensionView: + additionalProperties: false + properties: + args: + items: + type: string + type: + - array + - "null" + contract: + type: string + credentials: + additionalProperties: + type: string + type: object + digest: + type: string + egress: + items: + type: string + type: + - array + - "null" + env: + items: + type: string + type: + - array + - "null" + error: + type: string + name: + type: string + path: + type: string + settings: + additionalProperties: + type: string + type: object + settings_schema: + items: + $ref: "#/components/schemas/ConnectorsSetting" + type: + - array + - "null" + state: + type: string + tools: {} + url: + type: string + version: + type: string + required: + - name + - contract + - state + - digest + - egress + - env + - settings + - settings_schema + - credentials + type: object + ConnectorsField: + additionalProperties: false + properties: + engine: + type: string + key: + type: string + value: + type: string + writeOnly: true + type: object + ConnectorsMcpRequest: + additionalProperties: false + properties: + args: + items: + type: string + type: + - array + - "null" + credentials: + additionalProperties: + type: string + type: object + egress: + items: + type: string + type: + - array + - "null" + env: + items: + type: string + type: + - array + - "null" + path: + type: string + settings: + additionalProperties: + type: string + type: object + sha256: + type: string + tools: + items: + $ref: "#/components/schemas/ConnectorsToolDecl" + type: + - array + - "null" + url: + type: string + type: object + ConnectorsPackageState: + additionalProperties: false + properties: + name: + type: string + state: + enum: + - running + - removed + type: string + required: + - name + - state + type: object + ConnectorsSetting: + additionalProperties: false + properties: + description: + type: string + key: + type: string + label: + type: string + options: + items: + type: string + type: + - array + - "null" + required: + type: boolean + secret: + type: boolean + type: + type: string + required: + - key + - label + type: object + ConnectorsTarget: + additionalProperties: false + properties: + Disposable: + type: boolean + Environment: + type: string + ID: + type: string + Kind: + type: string + required: + - Kind + - ID + - Environment + - Disposable + type: object + ConnectorsToolDecl: + additionalProperties: false + properties: + kind: + type: string + name: + type: string + read_only: + type: boolean + reversibility: + type: string + summary: + type: string + required: + - name + - kind + type: object + DeliveriesAttempt: + additionalProperties: false + properties: + at: + format: date-time + type: string + attempt: + format: int64 + type: integer + channel: + type: string + duration_ms: + format: int64 + type: integer + error: + type: string + ok: + type: boolean + response: + type: string + required: + - channel + - attempt + - at + - ok + - duration_ms + type: object + DeliveriesMessage: + additionalProperties: false + properties: + attempts: + items: + $ref: "#/components/schemas/DeliveriesAttempt" + type: + - array + - "null" + body: + type: string + created_at: + format: date-time + type: string + expires_at: + format: date-time + type: + - string + - "null" + id: + type: string + kind: + type: string + request_id: + type: string + run_id: + type: string + seq: + format: int64 + type: integer + title: + type: string + required: + - seq + - id + - kind + - title + - body + - created_at + type: object + DraftsTrigger: + additionalProperties: false + properties: + event_type: + type: string + filter: {} + source: + type: string + required: + - source + - event_type + - filter + type: object + DraftsView: + additionalProperties: false + properties: + dry_event_id: + type: string + dry_run: + $ref: "#/components/schemas/RunsDryReport" + group_id: + type: string + id: + type: string + name: + type: string + policy: + type: string + policy_kind: + type: string + published_at: + format: date-time + type: + - string + - "null" + summary: + type: string + trigger: + $ref: "#/components/schemas/DraftsTrigger" + workflow: + type: string + required: + - id + - group_id + - name + - trigger + - workflow + - policy_kind + - policy + - summary + type: object + DryRunInputBody: + additionalProperties: false + properties: + event_id: + description: The stored event to replay; the newest by default + type: string + type: object + EditInputBody: + additionalProperties: false + properties: + name: + type: string + policy: + description: Cedar policy text added when the draft is published + type: string + policy_kind: + enum: + - hard_rules + - change_request + type: string + workflow: + description: The workflow document + type: string + required: + - name + - workflow + - policy_kind + type: object + ErrorDetail: + additionalProperties: false + properties: + location: + description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' + type: string + message: + description: Error message text + type: string + value: + description: The value at the given location + type: object + ErrorModel: + additionalProperties: false + properties: + detail: + description: A human-readable explanation specific to this occurrence of the problem. + examples: + - Property foo is required but is missing. + type: string + errors: + description: Optional list of individual error details + items: + $ref: "#/components/schemas/ErrorDetail" + type: + - array + - "null" + instance: + description: A URI reference that identifies the specific occurrence of the problem. + examples: + - https://example.com/error-log/abc123 + format: uri + type: string + status: + description: HTTP status code + examples: + - 400 + format: int64 + type: integer + title: + description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error. + examples: + - Bad Request + type: string + type: + default: about:blank + description: A URI reference to human-readable documentation for the error. + examples: + - https://example.com/errors/example + format: uri + type: string + type: object + EventsEventDetail: + additionalProperties: false + properties: + body: {} + runs: + items: + $ref: "#/components/schemas/EventsTriggerRun" + type: + - array + - "null" + required: + - body + - runs + type: object + EventsEventView: + additionalProperties: false + properties: + dispatched_at: + format: date-time + type: string + fields: {} + id: + type: string + linked_to: + type: string + matched: + type: boolean + occurred_at: + format: date-time + type: string + received_at: + format: date-time + type: string + source: + type: string + type: + type: string + required: + - id + - source + - type + - fields + - received_at + - matched + type: object + EventsGroupView: + additionalProperties: false + properties: + count: + format: int64 + type: integer + first_seen: + format: date-time + type: string + id: + type: string + last_seen: + format: date-time + type: string + proposed: + $ref: "#/components/schemas/EventsProposedTrigger" + required: + - id + - count + - first_seen + - last_seen + - proposed + type: object + EventsKeyFieldsSaved: + additionalProperties: false + properties: + key_fields: + items: + type: string + type: + - array + - "null" + required: + - key_fields + type: object + EventsProposedTrigger: + additionalProperties: false + properties: + event_type: + type: string + filter: {} + source: + type: string + workflow: + type: string + required: + - source + - event_type + - filter + - workflow + type: object + EventsSourceCreated: + additionalProperties: false + properties: + source: + type: string + token: + description: Shown once; only its hash is stored + type: string + url: + description: Where the sender posts its events + type: string + required: + - source + - token + - url + type: object + EventsSourceView: + additionalProperties: false + properties: + connector: + type: string + key_fields: + items: + type: string + type: + - array + - "null" + name: + type: string + token_set: + type: boolean + required: + - name + - connector + - key_fields + - token_set + type: object + EventsTriggerRun: + additionalProperties: false + properties: + run_id: + type: string + trigger: + type: string + required: + - trigger + - run_id + type: object + EventsTriggerSaved: + additionalProperties: false + properties: + trigger: + type: string + required: + - trigger + type: object + EventsTriggerView: + additionalProperties: false + properties: + enabled: + type: boolean + event_type: + type: string + every: + type: string + filter: + additionalProperties: + type: string + type: object + name: + type: string + source: + type: string + workflow: + type: string + required: + - name + - source + - event_type + - filter + - workflow + - enabled + type: object + GovernanceBlackout: + additionalProperties: false + properties: + from: + format: date-time + type: string + reason: + type: string + to: + format: date-time + type: string + required: + - from + - to + - reason + type: object + GovernanceModel: + additionalProperties: false + properties: + api_key_credential: + type: string + base_url: + type: string + class: + type: string + model: + type: string + required: + - class + - base_url + - model + type: object + GovernanceModelAnswer: + additionalProperties: false + properties: + answer: + type: string + model: + type: string + required: + - model + - answer + type: object + GovernancePersonRequest: + additionalProperties: false + properties: + authority: + type: boolean + id: + description: Empty for a new person + type: string + identities: + items: + type: string + type: + - array + - "null" + name: + type: string + required: + - name + - authority + - identities + type: object + GovernanceSettingsRequest: + additionalProperties: false + properties: + actions_per_day: + format: int64 + type: integer + actions_per_run: + format: int64 + type: integer + approval_deadline: + type: string + attempts_per_run: + format: int64 + type: integer + default_owner: + type: string + escalation: + items: + $ref: "#/components/schemas/GovernanceStepRequest" + type: + - array + - "null" + frozen: + type: boolean + raise_after: + format: int64 + type: integer + recurrence_threshold: + format: int64 + type: integer + timing: + $ref: "#/components/schemas/GovernanceTiming" + required: + - approval_deadline + - raise_after + - frozen + - recurrence_threshold + - attempts_per_run + - default_owner + - escalation + - timing + - actions_per_run + - actions_per_day + type: object + GovernanceStepRequest: + additionalProperties: false + properties: + deadline: + type: string + person: + type: string + required: + - person + - deadline + type: object + GovernanceTiming: + additionalProperties: false + properties: + blackouts: + items: + $ref: "#/components/schemas/GovernanceBlackout" + type: + - array + - "null" + days: + items: + type: string + type: + - array + - "null" + end: + type: string + start: + type: string + zone: + type: string + required: + - zone + - start + - end + - days + - blackouts + type: object + JudgementAction: + additionalProperties: false + properties: + connector: + type: string + digest: + type: string + effect: + $ref: "#/components/schemas/ConnectorsEffect" + input: {} + name: + type: string + target: + $ref: "#/components/schemas/ConnectorsTarget" + required: + - connector + - name + - input + - digest + - target + - effect + type: object + JudgementClassDetail: + additionalProperties: false + properties: + action: + type: string + connector: + type: string + count: + format: int64 + type: integer + decisions: + format: int64 + type: integer + default: + type: string + environment: + type: string + history: + items: + $ref: "#/components/schemas/JudgementHistoryEntry" + type: + - array + - "null" + id: + type: string + last_decided_at: + format: date-time + type: + - string + - "null" + level: + type: string + raises: + items: + $ref: "#/components/schemas/JudgementRaiseView" + type: + - array + - "null" + reset_at: + format: date-time + type: + - string + - "null" + resets: + items: + $ref: "#/components/schemas/JudgementResetView" + type: + - array + - "null" + target_kind: + type: string + tightened_at: + format: date-time + type: + - string + - "null" + tightened_because: + type: string + required: + - history + - resets + - raises + - id + - connector + - action + - target_kind + - environment + - level + - default + - decisions + - count + type: object + JudgementClassView: + additionalProperties: false + properties: + action: + type: string + connector: + type: string + count: + format: int64 + type: integer + decisions: + format: int64 + type: integer + default: + type: string + environment: + type: string + id: + type: string + last_decided_at: + format: date-time + type: + - string + - "null" + level: + type: string + reset_at: + format: date-time + type: + - string + - "null" + target_kind: + type: string + tightened_at: + format: date-time + type: + - string + - "null" + tightened_because: + type: string + required: + - id + - connector + - action + - target_kind + - environment + - level + - default + - decisions + - count + type: object + JudgementDecision: + additionalProperties: false + properties: + action: + $ref: "#/components/schemas/JudgementAction" + at: + format: date-time + type: string + calls: + items: + $ref: "#/components/schemas/ConnectorsCall" + type: + - array + - "null" + change_request: + type: boolean + change_request_rule: + type: string + dry: + type: boolean + id: + type: string + key: + type: string + level: + type: string + reason: + type: string + refused_by: + type: string + run_id: + type: string + verdicts: + items: + $ref: "#/components/schemas/JudgementVerdict" + type: + - array + - "null" + required: + - id + - run_id + - key + - action + - level + - verdicts + - at + type: object + JudgementFinding: + additionalProperties: false + properties: + evidence: + type: string + strength: + type: string + text: + type: string + required: + - text + type: object + JudgementHistoryEntry: + additionalProperties: false + properties: + answered_by: + type: string + approval: + type: string + at: + format: date-time + type: string + decision_id: + type: string + level: + type: string + refused_by: + type: string + run_id: + type: string + target: + type: string + required: + - decision_id + - run_id + - target + - level + - at + type: object + JudgementJudgeControl: + additionalProperties: false + properties: + advisory: + type: boolean + digest: + type: string + latest: + $ref: "#/components/schemas/JudgementJudgeStanding" + name: + type: string + settings: + additionalProperties: + type: string + type: object + settings_schema: + items: + $ref: "#/components/schemas/ConnectorsSetting" + type: + - array + - "null" + version: + type: string + required: + - name + - advisory + - settings + - settings_schema + type: object + JudgementJudgeRecord: + additionalProperties: false + properties: + advisory_reason: + type: string + answer: + type: string + answers: {} + basis: + type: string + basis_digest: + type: string + confidence: + format: double + type: number + endpoint_path: + type: string + eval_date: + type: string + http_status: + format: int64 + type: integer + latency_ms: + format: int64 + type: integer + model: + type: string + reason: + type: string + request: {} + response: {} + result_id: + type: string + trusted: + type: boolean + type: object + JudgementJudgeStanding: + additionalProperties: false + properties: + advisory_reason: + type: string + answer: + type: string + at: + format: date-time + type: string + eval_date: + type: string + model: + type: string + trusted: + type: boolean + required: + - trusted + - at + type: object + JudgementPolicySetView: + additionalProperties: false + properties: + body: + type: string + created_at: + format: date-time + type: string + created_by: + type: string + version: + format: int64 + type: integer + versions: + items: + $ref: "#/components/schemas/JudgementVersionView" + type: + - array + - "null" + required: + - version + - body + - created_by + - created_at + - versions + type: object + JudgementRaiseEvidence: + additionalProperties: false + properties: + at: + format: date-time + type: string + by: + type: string + decision_id: + type: string + required: + - decision_id + - by + - at + type: object + JudgementRaiseView: + additionalProperties: false + properties: + answered_at: + format: date-time + type: + - string + - "null" + answered_by: + type: string + deadline: + format: date-time + type: string + evidence: + items: + $ref: "#/components/schemas/JudgementRaiseEvidence" + type: + - array + - "null" + from: + type: string + id: + type: string + proposed_at: + format: date-time + type: string + state: + type: string + to: + type: string + required: + - id + - from + - to + - state + - deadline + - proposed_at + - evidence + type: object + JudgementResetView: + additionalProperties: false + properties: + at: + format: date-time + type: string + by: + type: string + from: + type: string + to: + type: string + required: + - from + - to + - by + - at + type: object + JudgementVerdict: + additionalProperties: false + properties: + advisory: + type: boolean + blind_spots: + items: + type: string + type: + - array + - "null" + ceiling: + type: string + digest: + type: string + failed: + type: string + findings: + items: + $ref: "#/components/schemas/JudgementFinding" + type: + - array + - "null" + guard: + type: string + judges: + items: + $ref: "#/components/schemas/JudgementJudgeRecord" + type: + - array + - "null" + owner: + type: string + version: + type: string + required: + - guard + - ceiling + type: object + JudgementVersionView: + additionalProperties: false + properties: + created_at: + format: date-time + type: string + created_by: + type: string + version: + format: int64 + type: integer + required: + - version + - created_by + - created_at + type: object + PolicyInputBody: + additionalProperties: false + properties: + body: + description: The whole policy set, as Cedar + type: string + required: + - body + type: object + PutKeyFieldsInputBody: + additionalProperties: false + properties: + paths: + description: Paths into the event's fields; none uses the connector's default + items: + type: string + type: + - array + - "null" + type: object + PutSourceInputBody: + additionalProperties: false + properties: + connector: + description: The connector that parses this source's events + type: string + required: + - connector + type: object + PutTriggerInputBody: + additionalProperties: false + properties: + disabled: + type: boolean + event_type: + description: The event type that fires it; fixed when every is set + type: string + every: + description: Fire on an interval instead of on events, such as 1h + examples: + - 1h + type: string + filter: + additionalProperties: + type: string + description: Event fields that must match exactly + type: object + source: + description: The source whose events fire it; fixed when every is set + type: string + workflow: + description: The workflow each match runs + type: string + required: + - workflow + type: object + RunsActionTrail: + additionalProperties: false + properties: + approval: + $ref: "#/components/schemas/ApprovalsView" + decision: + $ref: "#/components/schemas/JudgementDecision" + effect: + $ref: "#/components/schemas/RunsEffect" + rejudged: + $ref: "#/components/schemas/JudgementDecision" + required: + - decision + type: object + RunsDryAction: + additionalProperties: false + properties: + action: + type: string + ask: + items: + type: string + type: + - array + - "null" + level: + type: string + outcome: + type: string + summary: + type: string + target: + type: string + why: + type: string + required: + - action + - target + - level + - outcome + type: object + RunsDryNotice: + additionalProperties: false + properties: + body: + type: string + title: + type: string + required: + - title + - body + type: object + RunsDryReport: + additionalProperties: false + properties: + actions: + items: + $ref: "#/components/schemas/RunsDryAction" + type: + - array + - "null" + at: + format: date-time + type: string + error: + type: string + findings: + type: string + notice: + $ref: "#/components/schemas/RunsDryNotice" + run_id: + type: string + state: + type: string + required: + - run_id + - state + - actions + - at + type: object + RunsEffect: + additionalProperties: false + properties: + at: + format: date-time + type: string + error: + type: string + output: + type: string + state: + type: string + required: + - state + - at + type: object + RunsOrigin: + additionalProperties: false + properties: + event_id: + type: string + fields: {} + filter: {} + received_at: + format: date-time + type: string + source: + type: string + trigger: + type: string + type: + type: string + required: + - event_id + - source + - type + - fields + - received_at + - trigger + - filter + type: object + RunsRunView: + additionalProperties: false + properties: + attempts: + format: int64 + type: integer + created_at: + format: date-time + type: string + error: + type: string + finished_at: + format: date-time + type: + - string + - "null" + id: + type: string + result: {} + state: + type: string + workflow: + type: string + workflow_version: + format: int64 + type: integer + required: + - id + - workflow + - workflow_version + - state + - attempts + - created_at + type: object + RunsToolCallView: + additionalProperties: false + properties: + input: + type: string + name: + type: string + required: + - name + - input + type: object + RunsTrail: + additionalProperties: false + properties: + actions: + items: + $ref: "#/components/schemas/RunsActionTrail" + type: + - array + - "null" + entries: + items: + $ref: "#/components/schemas/RunsTrailEntry" + type: + - array + - "null" + origin: + $ref: "#/components/schemas/RunsOrigin" + run: + $ref: "#/components/schemas/RunsRunView" + required: + - run + - actions + - entries + type: object + RunsTrailEntry: + additionalProperties: false + properties: + at: + format: date-time + type: string + error: + type: string + finish_reason: + type: string + input: + type: string + kind: + type: string + name: + type: string + output: + type: string + reasoning: + type: string + request: {} + seq: + format: int64 + type: integer + text: + type: string + tool_calls: + items: + $ref: "#/components/schemas/RunsToolCallView" + type: + - array + - "null" + unknown: + type: boolean + usage: + $ref: "#/components/schemas/Usage" + value: {} + required: + - seq + - at + - kind + type: object + SystemAdminToken: + additionalProperties: false + properties: + token: + description: Shown once; only its hash is written to the config + type: string + required: + - token + type: object + SystemBootstrap: + additionalProperties: false + properties: + admin_token_hash_prefix: + type: string + admin_token_set: + type: boolean + database_host: + type: string + listen: + type: string + schemas: + format: int64 + type: integer + sealing_identity_set: + type: boolean + required: + - listen + - database_host + - schemas + - admin_token_hash_prefix + - admin_token_set + - sealing_identity_set + type: object + Usage: + additionalProperties: false + properties: + cache_creation_tokens: + format: int64 + type: integer + cached_tokens: + format: int64 + type: integer + completion_tokens: + format: int64 + type: integer + prompt_tokens: + format: int64 + type: integer + total_tokens: + format: int64 + type: integer + required: + - prompt_tokens + - completion_tokens + - total_tokens + type: object + securitySchemes: + admin: + description: The bootstrap admin token + scheme: bearer + type: http +info: + title: Archie + version: dev +openapi: 3.1.0 +paths: + /api/admin/token: + post: + operationId: rotate-admin-token + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/SystemAdminToken" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Rotate the admin token; the new one is shown once + tags: + - System + /api/approvals: + get: + operationId: list-approvals + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ApprovalsView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List approval requests waiting for an answer + tags: + - Approvals + /api/approvals/{id}/answer: + post: + operationId: answer-approval + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/AnswerInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ApprovalsView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Approve or refuse an action as the bootstrap admin + tags: + - Approvals + /api/classes: + get: + operationId: list-classes + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/JudgementClassView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List action classes with their earned levels + tags: + - Controls + /api/classes/{id}: + get: + operationId: get-class + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/JudgementClassDetail" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get an action class with its history and outcomes + tags: + - Controls + /api/classes/{id}/reset: + post: + operationId: reset-class + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/JudgementClassView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Reset an action class to its default level + tags: + - Controls + /api/composer/messages: + get: + operationId: list-composer-messages + parameters: + - description: Only messages after this seq; the latest page by default + explode: false + in: query + name: after + schema: + description: Only messages after this seq; the latest page by default + type: string + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/DeliveriesMessage" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List composer messages with their delivery attempts + tags: + - Composer + /api/composer/stream: + get: + operationId: stream-composer + responses: + "200": + content: + text/event-stream: + schema: + type: string + description: "Server-sent events: a message event carrying {\"seq\": n} for each new message, and a keepalive comment while idle" + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Stream the seq of each new composer message + tags: + - Composer + /api/connectors: + get: + operationId: list-connectors + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ConnectorsExtensionView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List accepted connectors + tags: + - Connectors + /api/connectors/{name}: + delete: + operationId: remove-connector + parameters: + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Remove an accepted package + tags: + - Connectors + put: + operationId: accept-connector + parameters: + - description: Lowercase letters, digits and hyphens + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsAcceptRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Accept a package and start it + tags: + - Connectors + /api/controls/judges: + get: + operationId: list-judges + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/JudgementJudgeControl" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List each guard's judge, its standing and its eval date + tags: + - Controls + /api/credentials: + get: + operationId: list-credentials + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ConnectorsCredentialView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List credentials, never their values + tags: + - Credentials + /api/credentials/{name}: + get: + operationId: get-credential + parameters: + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsCredentialView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get a credential, never its values + tags: + - Credentials + put: + operationId: put-credential + parameters: + - description: Lowercase letters, digits and hyphens + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsCredentialRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsCredentialSaved" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Store a credential sealed and restart what uses it + tags: + - Credentials + /api/drafts: + get: + operationId: list-drafts + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/DraftsView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List drafts + tags: + - Drafts + /api/drafts/{id}: + get: + operationId: get-draft + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DraftsView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get a draft + tags: + - Drafts + put: + operationId: edit-draft + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/EditInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DraftsView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Change a draft's name, workflow and policy + tags: + - Drafts + /api/drafts/{id}/dry-run: + post: + operationId: dry-run-draft + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/DryRunInputBody" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DraftsView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Replay one of the group's events through the draft, changing nothing + tags: + - Drafts + /api/drafts/{id}/publish: + post: + operationId: publish-draft + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DraftsView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Install the draft's workflow, policy and trigger + tags: + - Drafts + /api/events: + get: + operationId: list-events + parameters: + - explode: false + in: query + name: limit + schema: + default: 50 + format: int64 + maximum: 500 + minimum: 1 + type: integer + - explode: false + in: query + name: source + schema: + type: string + - explode: false + in: query + name: type + schema: + type: string + - description: Only events a trigger did or didn't match + explode: false + in: query + name: matched + schema: + description: Only events a trigger did or didn't match + enum: + - "true" + - "false" + type: string + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/EventsEventView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List recent events + tags: + - Events + /api/events/{id}: + get: + operationId: get-event + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/EventsEventDetail" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get an event with its payload and the runs it started + tags: + - Events + /api/groups: + get: + operationId: list-groups + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/EventsGroupView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List groups of unmatched events + tags: + - Events + /api/groups/{id}/draft: + post: + operationId: draft-group + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/DraftsView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Draft a trigger and workflow for a group of unmatched events + tags: + - Drafts + /api/guards: + get: + operationId: list-guards + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ConnectorsExtensionView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List accepted guards + tags: + - Guards + /api/guards/{name}: + delete: + operationId: remove-guard + parameters: + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Remove an accepted package + tags: + - Guards + put: + operationId: accept-guard + parameters: + - description: Lowercase letters, digits and hyphens + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsAcceptRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Accept a package and start it + tags: + - Guards + /api/mcp-servers: + get: + operationId: list-mcp-servers + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ConnectorsExtensionView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List accepted MCP servers + tags: + - MCP servers + /api/mcp-servers/{name}: + delete: + operationId: remove-mcp-server + parameters: + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Remove an accepted package + tags: + - MCP servers + put: + operationId: accept-mcp-server + parameters: + - description: Lowercase letters, digits and hyphens + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsMcpRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Accept an MCP server and the tools it may offer + tags: + - MCP servers + /api/people: + get: + operationId: list-people + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/GovernancePersonRequest" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List the people + tags: + - Governance + put: + operationId: put-people + requestBody: + content: + application/json: + schema: + items: + $ref: "#/components/schemas/GovernancePersonRequest" + type: + - array + - "null" + required: true + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/GovernancePersonRequest" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Replace the people + tags: + - Governance + /api/policies/change-request: + get: + operationId: get-change-request-rules + parameters: + - description: A past version; the current one by default + explode: false + in: query + name: version + schema: + description: A past version; the current one by default + format: int64 + minimum: 1 + type: integer + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/JudgementPolicySetView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get the change-request rules + tags: + - Controls + put: + operationId: put-change-request-rules + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PolicyInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/JudgementPolicySetView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Replace the change-request rules with a new version + tags: + - Controls + /api/policies/hard-rules: + get: + operationId: get-hard-rules + parameters: + - description: A past version; the current one by default + explode: false + in: query + name: version + schema: + description: A past version; the current one by default + format: int64 + minimum: 1 + type: integer + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/JudgementPolicySetView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get the hard rules + tags: + - Controls + put: + operationId: put-hard-rules + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PolicyInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/JudgementPolicySetView" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Replace the hard rules with a new version + tags: + - Controls + /api/runs: + get: + operationId: list-runs + parameters: + - explode: false + in: query + name: limit + schema: + default: 50 + format: int64 + maximum: 200 + minimum: 1 + type: integer + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/RunsRunView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List recent runs + tags: + - Runs + /api/runs/{id}: + get: + operationId: get-run + parameters: + - in: path + name: id + required: true + schema: + format: uuid + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/RunsTrail" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get a run's decision trail + tags: + - Runs + /api/secret-engines: + get: + operationId: list-secret-engines + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ConnectorsExtensionView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List accepted secret engines + tags: + - Secret engines + /api/secret-engines/{name}: + delete: + operationId: remove-secret-engine + parameters: + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Remove an accepted package + tags: + - Secret engines + put: + operationId: accept-secret-engine + parameters: + - description: Lowercase letters, digits and hyphens + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsAcceptRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/ConnectorsPackageState" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Accept a package and start it + tags: + - Secret engines + /api/settings: + get: + operationId: get-settings + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceSettingsRequest" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get the organisation settings + tags: + - Governance + put: + operationId: put-settings + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceSettingsRequest" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceSettingsRequest" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Change the organisation settings + tags: + - Governance + /api/settings/agent-model: + get: + operationId: get-agent-model + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceModel" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get the agent model + tags: + - Governance + put: + operationId: put-agent-model + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceModel" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceModel" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Set the agent model + tags: + - Governance + /api/settings/agent-model/test: + post: + operationId: test-agent-model + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceModel" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/GovernanceModelAnswer" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Ask a model one question before saving it + tags: + - Governance + /api/sources: + get: + operationId: list-sources + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/EventsSourceView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List sources + tags: + - Events + /api/sources/{name}: + put: + operationId: put-source + parameters: + - description: Lowercase letters, digits and hyphens; the webhook URL ends in it + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens; the webhook URL ends in it + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PutSourceInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/EventsSourceCreated" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Add a source or rotate its token + tags: + - Events + /api/sources/{name}/key-fields: + put: + operationId: put-source-key-fields + parameters: + - in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PutKeyFieldsInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/EventsKeyFieldsSaved" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Set the fields a source's events are grouped by + tags: + - Events + /api/system/bootstrap: + get: + operationId: get-bootstrap + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/SystemBootstrap" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Get the bootstrap values, which only the config file sets + tags: + - System + /api/triggers: + get: + operationId: list-triggers + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/EventsTriggerView" + type: + - array + - "null" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: List triggers + tags: + - Events + /api/triggers/{name}: + put: + operationId: put-trigger + parameters: + - description: Lowercase letters, digits and hyphens + in: path + name: name + required: true + schema: + description: Lowercase letters, digits and hyphens + type: string + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PutTriggerInputBody" + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/EventsTriggerSaved" + description: OK + default: + content: + application/problem+json: + schema: + $ref: "#/components/schemas/ErrorModel" + description: Error + summary: Add or change a trigger + tags: + - Events +security: + - admin: [] diff --git a/cmd/archie/main.go b/cmd/archie/main.go index 067b0c204..396a85379 100644 --- a/cmd/archie/main.go +++ b/cmd/archie/main.go @@ -25,11 +25,27 @@ func run() error { configPath := flag.String("config", archie.DefaultConfigPath(), "path to the bootstrap config file") newIdentity := flag.Bool("new-age-identity", false, "print a new age identity for age_identity and exit") showVersion := buildinfo.RegisterVersionFlag("archie") + flag.Usage = func() { + _, _ = fmt.Fprintln(flag.CommandLine.Output(), "usage: archie [flags]\n archie openapi print the API's OpenAPI document") + flag.PrintDefaults() + } flag.Parse() showVersion() if *newIdentity { return archie.NewAgeIdentity(os.Stdout) } + switch flag.Arg(0) { + case "": + case "openapi": + doc, err := archie.Document() + if err != nil { + return err + } + _, err = os.Stdout.Write(doc) + return err + default: + return fmt.Errorf("unknown command %q", flag.Arg(0)) + } ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() diff --git a/go.mod b/go.mod index 22cc1542d..219294e98 100644 --- a/go.mod +++ b/go.mod @@ -13,6 +13,7 @@ require ( github.com/cespare/xxhash/v2 v2.3.0 // indirect github.com/cloudflare/circl v1.6.5 // indirect github.com/containerd/errdefs/pkg v0.3.0 // indirect + github.com/danielgtaylor/huma/v2 v2.40.0 // indirect github.com/distribution/reference v0.6.0 // indirect github.com/docker/go-connections v0.8.2 // indirect github.com/docker/go-units v0.5.0 // indirect diff --git a/go.sum b/go.sum index 0a786d0cf..98126b6b6 100644 --- a/go.sum +++ b/go.sum @@ -47,6 +47,8 @@ github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151X github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk= github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM= github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4= +github.com/danielgtaylor/huma/v2 v2.40.0 h1:429ynr7/T9Iar+8P6NSsjcKwCRgaXvPKvqIFmbeL6vE= +github.com/danielgtaylor/huma/v2 v2.40.0/go.mod h1:x+utAArLHnM93jq2Wy7nLYkVorUF1vYML2hoPVb/5yo= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk= diff --git a/internal/app/archie/api.go b/internal/app/archie/api.go new file mode 100644 index 000000000..73be4ebcd --- /dev/null +++ b/internal/app/archie/api.go @@ -0,0 +1,62 @@ +package archie + +import ( + "net/http" + + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/buildinfo" + "github.com/samcharles93/archie-core/internal/platform/httpapi" + "github.com/samcharles93/archie-core/modules/approvals" + "github.com/samcharles93/archie-core/modules/connectors" + "github.com/samcharles93/archie-core/modules/deliveries" + "github.com/samcharles93/archie-core/modules/drafts" + "github.com/samcharles93/archie-core/modules/events" + "github.com/samcharles93/archie-core/modules/governance" + "github.com/samcharles93/archie-core/modules/judgement" + "github.com/samcharles93/archie-core/modules/runs" + "github.com/samcharles93/archie-core/modules/system" +) + +// apiModules are the modules that serve the HTTP API. +type apiModules struct { + settings *governance.Module + conns *connectors.Module + system *system.Module + tell *deliveries.Module + allow *approvals.Module + classes *judgement.Classes + policies *judgement.Policies + hear *events.Module + judge *judgement.Module + engine *runs.Engine + drafts *drafts.Module +} + +func (m apiModules) register(api huma.API) { + m.settings.Register(api) + m.conns.Register(api) + m.system.Register(api) + m.tell.Register(api) + m.allow.Register(api) + m.classes.Register(api, m.allow) + m.policies.Register(api) + m.hear.Register(api) + m.judge.Register(api) + m.engine.Register(api, orgID, m.hear, m.judge, m.allow) + m.drafts.Register(api) +} + +// Document returns the API's OpenAPI document as YAML. It makes the same +// registrations the server does, on modules with nothing behind them, so it +// needs no database. +func Document() ([]byte, error) { + api := httpapi.New(http.NewServeMux(), buildinfo.Version, "") + apiModules{ + settings: &governance.Module{}, conns: &connectors.Module{}, system: &system.Module{}, + tell: &deliveries.Module{}, allow: &approvals.Module{}, classes: &judgement.Classes{}, + policies: &judgement.Policies{}, hear: &events.Module{}, judge: &judgement.Module{}, + engine: &runs.Engine{}, drafts: &drafts.Module{}, + }.register(api) + return api.OpenAPI().YAML() +} diff --git a/internal/app/archie/run.go b/internal/app/archie/run.go index 1fb7ba905..b4512b6d1 100644 --- a/internal/app/archie/run.go +++ b/internal/app/archie/run.go @@ -20,7 +20,7 @@ import ( "github.com/samcharles93/archie-core/internal/buildinfo" "github.com/samcharles93/archie-core/internal/platform/health" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/internal/platform/hub" "github.com/samcharles93/archie-core/internal/platform/pg" "github.com/samcharles93/archie-core/modules/approvals" @@ -59,13 +59,12 @@ func Run(ctx context.Context, configPath string) error { checks := health.NewRegistry() checks.Register("database", db.PingContext) - guard := func(h http.Handler) http.Handler { return httpjson.Admin(cfg.AdminTokenSHA256, h) } mux := http.NewServeMux() checks.Routes(mux) + api := httpapi.New(mux, buildinfo.Version, cfg.AdminTokenSHA256) runtime.RegisterBuiltinClasses() settings := governance.NewModule(db, log.With("module", "governance"), orgID) - settings.Routes(mux, guard) conns, err := connectors.NewModule(db, log.With("module", "connectors"), orgID, connectors.Sealing{ Identity: cfg.AgeIdentity, Backups: cfg.AgeBackupRecipients, @@ -78,21 +77,19 @@ func Run(ctx context.Context, configPath string) error { return err } checks.Register("connectors", conns.Ready) - conns.Routes(mux, guard) // A model's key is a credential name resolved through the sealed store. settings.UseCredentials(conns) - system.New(system.Bootstrap{ + sys := system.New(system.Bootstrap{ Listen: cfg.Listen, Database: DatabaseHost(cfg.Database.URL), Schemas: len(schemas), AdminPrefix: cfg.AdminTokenSHA256[:8], AdminSet: cfg.AdminTokenSHA256 != "", Sealing: cfg.AgeIdentity != "", - }, func(hash string) error { return WriteAdminHash(configPath, hash) }, log.With("module", "system")).Routes(mux, guard) + }, func(hash string) error { return WriteAdminHash(configPath, hash) }, log.With("module", "system")) live := hub.New() // Messages go to the composer and to every accepted connector that delivers // them. tell := deliveries.NewModule(db, log.With("module", "deliveries"), orgID, live, conns) - tell.Routes(mux, guard) engine := runs.New(db, log.With("module", "runs"), runs.Options{Owner: owner()}) // A workflow takes its context from the run handle, as a handler takes it @@ -101,19 +98,18 @@ func Run(ctx context.Context, configPath string) error { // An approval request is carried by deliveries, and its answer wakes the run // that is waiting on it. allow := approvals.NewModule(db, log.With("module", "approvals"), orgID, tell, engine, classes, settings, settings) - allow.Routes(mux, guard) - classes.Routes(mux, guard, allow) - policies := newPolicies(db, log, mux, guard) + policies := judgement.NewPolicies(db, log.With("module", "judgement"), orgID) // An answer a channel delivers is an event, and settles its request. hear := events.NewModule(db, log.With("module", "events"), orgID, conns, engine, allow, tell) - hear.Routes(mux, guard) + hear.Routes(mux) judge := newJudgement(db, log, conns, classes, policies, settings, hear) - judge.Routes(mux, guard) if err := useWorkflows(ctx, engine, runs.Deps{Settings: settings, Toolbox: conns, Judge: judge, Approver: allow, Notifier: tell, Memory: memory.NewModule(db, orgID)}); err != nil { return err } - engine.Routes(mux, guard, orgID, hear, judge, allow) - drafts.NewModule(db, log.With("module", "drafts"), orgID, hear, engine, policies).Routes(mux, guard) + apiModules{ + settings: settings, conns: conns, system: sys, tell: tell, allow: allow, classes: classes, policies: policies, + hear: hear, judge: judge, engine: engine, drafts: drafts.NewModule(db, log.With("module", "drafts"), orgID, hear, engine, policies), + }.register(api) dashboard.Routes(mux, ui.DistDirFS) return serveWithWork(ctx, log, cfg.Listen, mux, engine.Work, hear.Work, tell.Work) @@ -151,14 +147,6 @@ func work(ctx context.Context, loops ...func(context.Context)) func() { return workers.Wait } -// newPolicies returns the hard rules and change-request rules, with their -// routes. -func newPolicies(db *sqlx.DB, log *slog.Logger, mux *http.ServeMux, guard func(http.Handler) http.Handler) *judgement.Policies { - policies := judgement.NewPolicies(db, log.With("module", "judgement"), orgID) - policies.Routes(mux, guard) - return policies -} - // newJudgement returns the judgement module with its hard rules, data guards // and change-request rules. A failed action tightens its class. func newJudgement(db *sqlx.DB, log *slog.Logger, conns *connectors.Module, classes *judgement.Classes, policies *judgement.Policies, settings *governance.Module, heard judgement.Events) *judgement.Module { diff --git a/internal/platform/httpapi/httpapi.go b/internal/platform/httpapi/httpapi.go new file mode 100644 index 000000000..47c8cb376 --- /dev/null +++ b/internal/platform/httpapi/httpapi.go @@ -0,0 +1,79 @@ +// Package httpapi builds the binary's HTTP API on Huma, so every operation a +// module registers is described in the OpenAPI document served beside it. +package httpapi + +import ( + "net/http" + "path" + "reflect" + "strings" + "unicode" + + "github.com/danielgtaylor/huma/v2" + "github.com/danielgtaylor/huma/v2/adapters/humago" + + "github.com/samcharles93/archie-core/internal/platform/httpjson" +) + +// DocumentPath is where the API serves its OpenAPI document, as .json and +// .yaml. +const DocumentPath = "/api/openapi" + +// Reply is an operation's output whose response body is T. +type Reply[T any] struct { + Body T +} + +// OK wraps v as an operation's response body. +func OK[T any](v T) *Reply[T] { + return &Reply[T]{Body: v} +} + +// New returns an API on mux whose every operation requires the bootstrap admin +// token, held only as its hash. +func New(mux *http.ServeMux, version, adminHash string) huma.API { + api := humago.New(mux, config(version)) + api.UseMiddleware(admin(api, adminHash)) + return api +} + +func config(version string) huma.Config { + cfg := huma.DefaultConfig("Archie", version) + cfg.OpenAPIPath = DocumentPath + cfg.DocsPath = "/api/docs" + // Schema links would put a $schema member in every response body. + cfg.SchemasPath = "" + cfg.CreateHooks = nil + cfg.Components.Schemas = huma.NewMapRegistry("#/components/schemas/", schemaName) + cfg.Components.SecuritySchemes = map[string]*huma.SecurityScheme{ + "admin": {Type: "http", Scheme: "bearer", Description: "The bootstrap admin token"}, + } + cfg.Security = []map[string][]string{{"admin": {}}} + return cfg +} + +func admin(api huma.API, hash string) func(huma.Context, func(huma.Context)) { + return func(ctx huma.Context, next func(huma.Context)) { + token, ok := strings.CutPrefix(ctx.Header("Authorization"), "Bearer ") + if !ok || !httpjson.TokenMatches(strings.TrimSpace(token), hash) { + _ = huma.WriteErr(api, ctx, http.StatusUnauthorized, "admin token required") + return + } + next(ctx) + } +} + +// schemaName prefixes a type of Archie's own with its package, since modules +// reuse short names like Source and Request. +func schemaName(t reflect.Type, hint string) string { + name := huma.DefaultSchemaNamer(t, hint) + for t.Kind() == reflect.Pointer { + t = t.Elem() + } + if t.Name() == "" || !strings.HasPrefix(t.PkgPath(), "github.com/samcharles93/archie-core/") { + return name + } + pkg := []rune(path.Base(t.PkgPath())) + pkg[0] = unicode.ToUpper(pkg[0]) + return string(pkg) + name +} diff --git a/internal/platform/httpapi/httpapi_test.go b/internal/platform/httpapi/httpapi_test.go new file mode 100644 index 000000000..51cf125ea --- /dev/null +++ b/internal/platform/httpapi/httpapi_test.go @@ -0,0 +1,50 @@ +package httpapi + +import ( + "context" + "net/http" + "net/http/httptest" + "testing" + + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/platform/httpjson" +) + +// TestEveryOperationRequiresTheAdminToken guards the bootstrap admin boundary: +// only a bearer token whose hash matches the configured one reaches an +// operation, and an empty configured hash locks everyone out rather than +// letting everyone in. +func TestEveryOperationRequiresTheAdminToken(t *testing.T) { + const token = "a-plainly-fake-admin-token" //nolint:gosec // test fixture, not a credential + tests := []struct { + name string + hash string + header string + want int + }{ + {name: "matching token", hash: httpjson.TokenHash(token), header: "Bearer " + token, want: http.StatusOK}, + {name: "wrong token", hash: httpjson.TokenHash(token), header: "Bearer other", want: http.StatusUnauthorized}, + {name: "no token", hash: httpjson.TokenHash(token), header: "", want: http.StatusUnauthorized}, + {name: "not a bearer token", hash: httpjson.TokenHash(token), header: "Basic " + token, want: http.StatusUnauthorized}, + {name: "no configured hash locks everyone out", hash: "", header: "Bearer ", want: http.StatusUnauthorized}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + mux := http.NewServeMux() + api := New(mux, "test", tt.hash) + huma.Get(api, "/api/thing", func(context.Context, *struct{}) (*Reply[string], error) { + return OK("reached"), nil + }) + req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/api/thing", nil) + if tt.header != "" { + req.Header.Set("Authorization", tt.header) + } + rec := httptest.NewRecorder() + mux.ServeHTTP(rec, req) + if rec.Code != tt.want { + t.Fatalf("status = %d, want %d", rec.Code, tt.want) + } + }) + } +} diff --git a/internal/platform/httpjson/httpjson.go b/internal/platform/httpjson/httpjson.go index e595ba9a4..fac2c382c 100644 --- a/internal/platform/httpjson/httpjson.go +++ b/internal/platform/httpjson/httpjson.go @@ -1,5 +1,5 @@ -// Package httpjson reads and writes the JSON bodies of the binary's HTTP API, -// and guards the admin routes with the bootstrap admin token. +// Package httpjson writes the JSON bodies of the routes outside the API, and +// stores and compares tokens as their hashes. package httpjson import ( @@ -29,14 +29,6 @@ func Error(w http.ResponseWriter, status int, msg string) { Write(w, status, map[string]string{"error": msg}) } -// Read decodes a bounded request body into v, refusing unknown fields. -func Read(r *http.Request, v any) error { - if err := json.UnmarshalRead(io.LimitReader(r.Body, maxBody), v, json.RejectUnknownMembers(true)); err != nil { - return fmt.Errorf("read request body: %w", err) - } - return nil -} - // Body reads a bounded raw request body. func Body(r *http.Request) ([]byte, error) { body, err := io.ReadAll(io.LimitReader(r.Body, maxBody+1)) @@ -71,14 +63,3 @@ func TokenMatches(token, hash string) bool { } return subtle.ConstantTimeCompare([]byte(TokenHash(token)), []byte(hash)) == 1 } - -// Admin guards next with the bootstrap admin token, held only as its hash. -func Admin(hash string, next http.Handler) http.Handler { - return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if !TokenMatches(Bearer(r), hash) { - Error(w, http.StatusUnauthorized, "admin token required") - return - } - next.ServeHTTP(w, r) - }) -} diff --git a/internal/platform/httpjson/httpjson_test.go b/internal/platform/httpjson/httpjson_test.go deleted file mode 100644 index 67bc8b45a..000000000 --- a/internal/platform/httpjson/httpjson_test.go +++ /dev/null @@ -1,40 +0,0 @@ -package httpjson - -import ( - "net/http" - "net/http/httptest" - "testing" -) - -// TestAdminGuardsWithTheTokenHash guards the bootstrap admin boundary: only a -// bearer token whose hash matches the configured one reaches the handler, and -// an empty configured hash locks everyone out rather than letting everyone in. -func TestAdminGuardsWithTheTokenHash(t *testing.T) { - const token = "a-plainly-fake-admin-token" //nolint:gosec // test fixture, not a credential - tests := []struct { - name string - hash string - header string - want int - }{ - {name: "matching token", hash: TokenHash(token), header: "Bearer " + token, want: http.StatusOK}, - {name: "wrong token", hash: TokenHash(token), header: "Bearer other", want: http.StatusUnauthorized}, - {name: "no token", hash: TokenHash(token), header: "", want: http.StatusUnauthorized}, - {name: "not a bearer token", hash: TokenHash(token), header: "Basic " + token, want: http.StatusUnauthorized}, - {name: "no configured hash locks everyone out", hash: "", header: "Bearer ", want: http.StatusUnauthorized}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - h := Admin(tt.hash, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) })) - req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/api/events", nil) - if tt.header != "" { - req.Header.Set("Authorization", tt.header) - } - rec := httptest.NewRecorder() - h.ServeHTTP(rec, req) - if rec.Code != tt.want { - t.Fatalf("status = %d, want %d", rec.Code, tt.want) - } - }) - } -} diff --git a/modules/approvals/approvals.go b/modules/approvals/approvals.go index e80d685cb..00c8f3b52 100644 --- a/modules/approvals/approvals.go +++ b/modules/approvals/approvals.go @@ -22,10 +22,11 @@ import ( "strings" "time" + "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/jmoiron/sqlx" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/approvals/internal/store" "github.com/samcharles93/archie-core/modules/deliveries" "github.com/samcharles93/archie-core/modules/governance" @@ -546,10 +547,17 @@ func (m *Module) Outcomes(ctx context.Context, ids []uuid.UUID) (map[uuid.UUID]j return out, nil } -// Routes adds the approvals API to mux behind guard. -func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { - mux.Handle("GET /api/approvals", guard(http.HandlerFunc(m.list))) - mux.Handle("POST /api/approvals/{id}/answer", guard(http.HandlerFunc(m.answer))) +// Register adds the approvals API. +func (m *Module) Register(api huma.API) { + tags := []string{"Approvals"} + huma.Register(api, huma.Operation{ + OperationID: "list-approvals", Method: http.MethodGet, Path: "/api/approvals", + Summary: "List approval requests waiting for an answer", Tags: tags, + }, m.list) + huma.Register(api, huma.Operation{ + OperationID: "answer-approval", Method: http.MethodPost, Path: "/api/approvals/{id}/answer", + Summary: "Approve or refuse an action as the bootstrap admin", Tags: tags, + }, m.answer) } // bootstrapAdmin names the identity the bootstrap admin token stands for. The @@ -557,49 +565,43 @@ func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handle // authority and skips the people check until real sign-in exists. const bootstrapAdmin = "admin" -type answerRequest struct { - Approved bool `json:"approved"` +type answerInput struct { + ID string `path:"id" format:"uuid"` + Body struct { + Approved bool `json:"approved"` + } } -func (m *Module) list(w http.ResponseWriter, r *http.Request) { - pending, err := m.Pending(r.Context()) +func (m *Module) list(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]View], error) { + pending, err := m.Pending(ctx) if err != nil { - m.log.ErrorContext(r.Context(), "list approvals", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't list approvals") - return + m.log.ErrorContext(ctx, "list approvals", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't list approvals") } out := make([]View, 0, len(pending)) for _, p := range pending { out = append(out, p.View()) } - httpjson.Write(w, http.StatusOK, out) + return httpapi.OK(out), nil } -func (m *Module) answer(w http.ResponseWriter, r *http.Request) { - id, err := uuid.Parse(r.PathValue("id")) +func (m *Module) answer(ctx context.Context, in *answerInput) (*httpapi.Reply[View], error) { + id, err := uuid.Parse(in.ID) if err != nil { - httpjson.Error(w, http.StatusBadRequest, "id is a request id") - return + return nil, huma.NewError(http.StatusBadRequest, "id is a request id") } - var req answerRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - out, err := m.answerAs(r.Context(), id, bootstrapAdmin, "composer", req.Approved) + req := in.Body + out, err := m.answerAs(ctx, id, bootstrapAdmin, "composer", req.Approved) switch { case errors.Is(err, ErrNotFound): - httpjson.Error(w, http.StatusNotFound, "no such approval request") - return + return nil, huma.NewError(http.StatusNotFound, "no such approval request") case errors.Is(err, ErrAnswered), errors.Is(err, ErrExpired): - httpjson.Error(w, http.StatusConflict, err.Error()) - return + return nil, huma.NewError(http.StatusConflict, err.Error()) case err != nil: - m.log.ErrorContext(r.Context(), "answer approval", "request", id, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't record the answer") - return + m.log.ErrorContext(ctx, "answer approval", "request", id, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't record the answer") } - httpjson.Write(w, http.StatusOK, out.View()) + return httpapi.OK(out.View()), nil } // pending reads a request that is still open and inside its deadline. The diff --git a/modules/connectors/credentials.go b/modules/connectors/credentials.go index fb2c762ae..e90009a52 100644 --- a/modules/connectors/credentials.go +++ b/modules/connectors/credentials.go @@ -9,16 +9,17 @@ import ( "net/http" "slices" + "github.com/danielgtaylor/huma/v2" "golang.org/x/crypto/ssh" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors/internal/store" ) // Field is one field of a credential: a value Archie keeps sealed, or the key // a secret engine resolves it from when the extension using it starts. type Field struct { - Value string `json:"value,omitzero"` + Value string `json:"value,omitzero" writeOnly:"true"` Engine string `json:"engine,omitzero"` Key string `json:"key,omitzero"` } @@ -43,6 +44,19 @@ type credentialRequest struct { Fields map[string]Field `json:"fields"` } +type credentialInput struct { + Name string `path:"name" doc:"Lowercase letters, digits and hyphens"` + Body credentialRequest +} + +// credentialSaved names a stored credential and the extensions restarted to +// pick it up. +type credentialSaved struct { + Name string `json:"name"` + Kind string `json:"kind"` + Restarted []string `json:"restarted"` +} + // credentialView shows where each field comes from, never a value. type credentialView struct { Name string `json:"name"` @@ -52,84 +66,68 @@ type credentialView struct { // putCredential stores a credential sealed, then restarts the extensions that // use it so they are configured with the new values. -func (m *Module) putCredential(w http.ResponseWriter, r *http.Request) { - name := r.PathValue("name") - var req credentialRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } +func (m *Module) putCredential(ctx context.Context, in *credentialInput) (*httpapi.Reply[credentialSaved], error) { + name, req := in.Name, in.Body if !validName.MatchString(name) { - httpjson.Error(w, http.StatusBadRequest, "a credential needs a lowercase name") - return + return nil, huma.NewError(http.StatusBadRequest, "a credential needs a lowercase name") } if err := checkCredential(req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } plain, err := json.Marshal(req.Fields) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } sealed, err := m.sealer.Seal(m.credentialLabel(name, req.Kind), plain) if err != nil { - m.log.ErrorContext(r.Context(), "seal credential", "credential", name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't seal the credential") - return + m.log.ErrorContext(ctx, "seal credential", "credential", name, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't seal the credential") } - if err := m.store.PutCredential(r.Context(), store.Credential{OrgID: m.orgID, Name: name, Kind: req.Kind, Sealed: sealed}); err != nil { - m.log.ErrorContext(r.Context(), "put credential", "credential", name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the credential") - return + if err := m.store.PutCredential(ctx, store.Credential{OrgID: m.orgID, Name: name, Kind: req.Kind, Sealed: sealed}); err != nil { + m.log.ErrorContext(ctx, "put credential", "credential", name, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the credential") } - restarted, err := m.relaunchUsers(context.WithoutCancel(r.Context()), name) + restarted, err := m.relaunchUsers(context.WithoutCancel(ctx), name) if err != nil { - httpjson.Error(w, http.StatusUnprocessableEntity, err.Error()) - return + return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error()) } - httpjson.Write(w, http.StatusOK, map[string]any{"name": name, "kind": req.Kind, "restarted": restarted}) + return httpapi.OK(credentialSaved{Name: name, Kind: req.Kind, Restarted: restarted}), nil } -func (m *Module) listCredentials(w http.ResponseWriter, r *http.Request) { - creds, err := m.store.Credentials(r.Context(), m.orgID) +func (m *Module) listCredentials(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]credentialView], error) { + creds, err := m.store.Credentials(ctx, m.orgID) if err != nil { - m.log.ErrorContext(r.Context(), "list credentials", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't list credentials") - return + m.log.ErrorContext(ctx, "list credentials", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't list credentials") } views := make([]credentialView, 0, len(creds)) for _, c := range creds { view, err := m.credentialViewOf(c) if err != nil { - m.log.ErrorContext(r.Context(), "open credential", "credential", c.Name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't open credential "+c.Name) - return + m.log.ErrorContext(ctx, "open credential", "credential", c.Name, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't open credential "+c.Name) } views = append(views, view) } - httpjson.Write(w, http.StatusOK, views) + return httpapi.OK(views), nil } -func (m *Module) getCredential(w http.ResponseWriter, r *http.Request) { - name := r.PathValue("name") - c, ok, err := m.store.Credential(r.Context(), m.orgID, name) +func (m *Module) getCredential(ctx context.Context, in *nameInput) (*httpapi.Reply[credentialView], error) { + name := in.Name + c, ok, err := m.store.Credential(ctx, m.orgID, name) if err != nil { - m.log.ErrorContext(r.Context(), "read credential", "credential", name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the credential") - return + m.log.ErrorContext(ctx, "read credential", "credential", name, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the credential") } if !ok { - httpjson.Error(w, http.StatusNotFound, "no such credential") - return + return nil, huma.NewError(http.StatusNotFound, "no such credential") } view, err := m.credentialViewOf(c) if err != nil { - m.log.ErrorContext(r.Context(), "open credential", "credential", name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't open the credential") - return + m.log.ErrorContext(ctx, "open credential", "credential", name, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't open the credential") } - httpjson.Write(w, http.StatusOK, view) + return httpapi.OK(view), nil } // credentialViewOf says where each field comes from: stored, or the secret diff --git a/modules/connectors/credentials_test.go b/modules/connectors/credentials_test.go index 00daa2e8b..b65d4a3e7 100644 --- a/modules/connectors/credentials_test.go +++ b/modules/connectors/credentials_test.go @@ -4,8 +4,6 @@ import ( "context" json "encoding/json/v2" "log/slog" - "net/http" - "net/http/httptest" "strings" "testing" @@ -46,20 +44,21 @@ func TestCredentialRoutesNeverReturnASecret(t *testing.T) { for _, tt := range []struct { name string - call func(http.ResponseWriter, *http.Request) + call func(context.Context) (any, error) }{ - {name: "list", call: module.listCredentials}, - {name: "read", call: module.getCredential}, + {name: "list", call: func(ctx context.Context) (any, error) { return module.listCredentials(ctx, nil) }}, + {name: "read", call: func(ctx context.Context) (any, error) { return module.getCredential(ctx, &nameInput{Name: "ops"}) }}, } { t.Run(tt.name, func(t *testing.T) { - rec := httptest.NewRecorder() - req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/api/credentials", nil) - req.SetPathValue("name", "ops") - tt.call(rec, req) - if rec.Code != http.StatusOK { - t.Fatalf("status %d: %s", rec.Code, rec.Body.String()) + reply, err := tt.call(t.Context()) + if err != nil { + t.Fatalf("read: %v", err) } - body := rec.Body.String() + raw, err := json.Marshal(reply) + if err != nil { + t.Fatal(err) + } + body := string(raw) if strings.Contains(body, secret) { t.Fatalf("the route returned the secret: %s", body) } diff --git a/modules/connectors/list.go b/modules/connectors/list.go index 0b8e0bd8b..04ca62d6a 100644 --- a/modules/connectors/list.go +++ b/modules/connectors/list.go @@ -1,12 +1,15 @@ package connectors import ( + "context" "encoding/json/jsontext" json "encoding/json/v2" "fmt" "net/http" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors/internal/store" ) @@ -33,13 +36,12 @@ type ExtensionView struct { } // list returns the accepted packages of one contract, in name order. -func (m *Module) list(contract string) http.HandlerFunc { - return func(w http.ResponseWriter, r *http.Request) { - accepted, err := m.store.List(r.Context(), m.orgID) +func (m *Module) list(contract string) func(context.Context, *struct{}) (*httpapi.Reply[[]ExtensionView], error) { + return func(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]ExtensionView], error) { + accepted, err := m.store.List(ctx, m.orgID) if err != nil { - m.log.ErrorContext(r.Context(), "list accepted packages", "contract", contract, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the accepted packages") - return + m.log.ErrorContext(ctx, "list accepted packages", "contract", contract, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the accepted packages") } views := make([]ExtensionView, 0, len(accepted)) for _, a := range accepted { @@ -48,13 +50,12 @@ func (m *Module) list(contract string) http.HandlerFunc { } view, err := m.viewOf(a) if err != nil { - m.log.ErrorContext(r.Context(), "read accepted package", "package", a.Name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read "+a.Name) - return + m.log.ErrorContext(ctx, "read accepted package", "package", a.Name, "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read "+a.Name) } views = append(views, view) } - httpjson.Write(w, http.StatusOK, views) + return httpapi.OK(views), nil } } diff --git a/modules/connectors/mcpaccept.go b/modules/connectors/mcpaccept.go index d9e46b66d..9fa48127c 100644 --- a/modules/connectors/mcpaccept.go +++ b/modules/connectors/mcpaccept.go @@ -11,7 +11,9 @@ import ( "regexp" "slices" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors/internal/store" ) @@ -19,26 +21,31 @@ import ( // are its environment. var envSettingName = regexp.MustCompile(`^[A-Z_][A-Z0-9_]*$`) +type mcpInput struct { + Name string `path:"name" doc:"Lowercase letters, digits and hyphens"` + Body mcpRequest +} + // mcpRequest is one acceptance of an MCP server. type mcpRequest struct { // URL reaches an HTTP server; Path and SHA256 name a stdio server's binary. // Setting one of the two picks the transport. - URL string `json:"url"` - Path string `json:"path"` - SHA256 string `json:"sha256"` + URL string `json:"url,omitzero"` + Path string `json:"path,omitzero"` + SHA256 string `json:"sha256,omitzero"` // Args are a stdio server's arguments. - Args []string `json:"args"` + Args []string `json:"args,omitzero"` // Env names host environment variables the server may see. - Env []string `json:"env"` + Env []string `json:"env,omitzero"` // Settings are handed to a stdio server as its environment. - Settings map[string]string `json:"settings"` + Settings map[string]string `json:"settings,omitzero"` // Egress is the accepted host list: everything the server may reach. - Egress []string `json:"egress"` + Egress []string `json:"egress,omitzero"` // Credentials maps each slot the server's credentials are read from to a // credential by name. - Credentials map[string]string `json:"credentials"` + Credentials map[string]string `json:"credentials,omitzero"` // Tools are the tools the server may offer, and nothing else is offered. - Tools []ToolDecl `json:"tools"` + Tools []ToolDecl `json:"tools,omitzero"` } // check refuses an acceptance that couldn't work, before anything is stored. @@ -130,44 +137,33 @@ func reversibility(name string) (Reversibility, bool) { // acceptServer stores an MCP server's acceptance and starts it. A server that // doesn't come up is still accepted: it is reported by readiness and retried // with backoff, so a restart fixes it without another acceptance. -func (m *Module) acceptServer(w http.ResponseWriter, r *http.Request) { - name := r.PathValue("name") - var req mcpRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } +func (m *Module) acceptServer(ctx context.Context, in *mcpInput) (*httpapi.Reply[packageState], error) { + name, req := in.Name, in.Body if !validName.MatchString(name) { - httpjson.Error(w, http.StatusBadRequest, "an MCP server needs a lowercase name") - return + return nil, huma.NewError(http.StatusBadRequest, "an MCP server needs a lowercase name") } if err := req.check(); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } a, err := req.accepted(m.orgID, name) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - if err := m.store.Upsert(r.Context(), a); err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return + if err := m.store.Upsert(ctx, a); err != nil { + return nil, huma.NewError(http.StatusInternalServerError, err.Error()) } - if err := m.launch(context.WithoutCancel(r.Context()), a); err != nil { - httpjson.Error(w, http.StatusUnprocessableEntity, err.Error()) - return + if err := m.launch(context.WithoutCancel(ctx), a); err != nil { + return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error()) } if err := m.checkAccepted(a); err != nil { - _, _ = m.store.Delete(context.WithoutCancel(r.Context()), m.orgID, name) + _, _ = m.store.Delete(context.WithoutCancel(ctx), m.orgID, name) m.release(name) m.mu.Lock() delete(m.failed, name) m.mu.Unlock() - httpjson.Error(w, http.StatusUnprocessableEntity, err.Error()) - return + return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error()) } - httpjson.Write(w, http.StatusOK, map[string]string{"name": name, "state": "running"}) + return httpapi.OK(packageState{Name: name, State: "running"}), nil } // accepted is the row an acceptance stores. diff --git a/modules/connectors/module.go b/modules/connectors/module.go index 5df08919b..3e2ccc8a2 100644 --- a/modules/connectors/module.go +++ b/modules/connectors/module.go @@ -16,9 +16,10 @@ import ( "strings" "sync" + "github.com/danielgtaylor/huma/v2" "github.com/jmoiron/sqlx" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors/internal/seal" "github.com/samcharles93/archie-core/modules/connectors/internal/store" ) @@ -249,60 +250,96 @@ func (m *Module) Close() { m.host.Close() } -// Routes adds the admin routes, each wrapped in guard. -func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { - mux.Handle("PUT /api/connectors/{name}", guard(m.accept(store.ContractConnector))) - mux.Handle("PUT /api/secret-engines/{name}", guard(m.accept(store.ContractSecretEngine))) - mux.Handle("PUT /api/guards/{name}", guard(m.accept(store.ContractGuard))) - mux.Handle("PUT /api/mcp-servers/{name}", guard(http.HandlerFunc(m.acceptServer))) - mux.Handle("DELETE /api/connectors/{name}", guard(m.remove(store.ContractConnector))) - mux.Handle("DELETE /api/secret-engines/{name}", guard(m.remove(store.ContractSecretEngine))) - mux.Handle("DELETE /api/guards/{name}", guard(m.remove(store.ContractGuard))) - mux.Handle("DELETE /api/mcp-servers/{name}", guard(m.remove(store.ContractMCP))) - mux.Handle("PUT /api/credentials/{name}", guard(http.HandlerFunc(m.putCredential))) - mux.Handle("GET /api/credentials", guard(http.HandlerFunc(m.listCredentials))) - mux.Handle("GET /api/credentials/{name}", guard(http.HandlerFunc(m.getCredential))) - mux.Handle("GET /api/connectors", guard(m.list(store.ContractConnector))) - mux.Handle("GET /api/secret-engines", guard(m.list(store.ContractSecretEngine))) - mux.Handle("GET /api/guards", guard(m.list(store.ContractGuard))) - mux.Handle("GET /api/mcp-servers", guard(m.list(store.ContractMCP))) +// Register adds the API for accepted packages and credentials. +func (m *Module) Register(api huma.API) { + for _, k := range []struct { + contract, path, noun, plural, tag string + }{ + {store.ContractConnector, "/api/connectors", "connector", "connectors", "Connectors"}, + {store.ContractSecretEngine, "/api/secret-engines", "secret-engine", "secret engines", "Secret engines"}, + {store.ContractGuard, "/api/guards", "guard", "guards", "Guards"}, + {store.ContractMCP, "/api/mcp-servers", "mcp-server", "MCP servers", "MCP servers"}, + } { + tags := []string{k.tag} + huma.Register(api, huma.Operation{ + OperationID: "list-" + k.noun + "s", Method: http.MethodGet, Path: k.path, + Summary: "List accepted " + k.plural, Tags: tags, + }, m.list(k.contract)) + huma.Register(api, huma.Operation{ + OperationID: "remove-" + k.noun, Method: http.MethodDelete, Path: k.path + "/{name}", + Summary: "Remove an accepted package", Tags: tags, + }, m.remove(k.contract)) + if k.contract == store.ContractMCP { + huma.Register(api, huma.Operation{ + OperationID: "accept-mcp-server", Method: http.MethodPut, Path: k.path + "/{name}", + Summary: "Accept an MCP server and the tools it may offer", Tags: tags, + }, m.acceptServer) + continue + } + huma.Register(api, huma.Operation{ + OperationID: "accept-" + k.noun, Method: http.MethodPut, Path: k.path + "/{name}", + Summary: "Accept a package and start it", Tags: tags, + }, m.accept(k.contract)) + } + tags := []string{"Credentials"} + huma.Register(api, huma.Operation{ + OperationID: "list-credentials", Method: http.MethodGet, Path: "/api/credentials", + Summary: "List credentials, never their values", Tags: tags, + }, m.listCredentials) + huma.Register(api, huma.Operation{ + OperationID: "get-credential", Method: http.MethodGet, Path: "/api/credentials/{name}", + Summary: "Get a credential, never its values", Tags: tags, + }, m.getCredential) + huma.Register(api, huma.Operation{ + OperationID: "put-credential", Method: http.MethodPut, Path: "/api/credentials/{name}", + Summary: "Store a credential sealed and restart what uses it", Tags: tags, + }, m.putCredential) } type acceptRequest struct { - Path string `json:"path"` - SHA256 string `json:"sha256"` - Egress []string `json:"egress"` - Env []string `json:"env"` - Settings map[string]string `json:"settings"` + Path string `json:"path" doc:"The extension binary on the host"` + SHA256 string `json:"sha256" doc:"The binary's digest; it runs only while the digest matches"` + Egress []string `json:"egress,omitzero" doc:"Every host the extension may reach"` + Env []string `json:"env,omitzero" doc:"Host environment variables the extension may see"` + Settings map[string]string `json:"settings,omitzero"` // Credentials maps each credential slot the package declares to a // credential by name. - Credentials map[string]string `json:"credentials"` + Credentials map[string]string `json:"credentials,omitzero"` } -func (m *Module) accept(contract string) http.HandlerFunc { - return func(w http.ResponseWriter, r *http.Request) { m.acceptAs(w, r, contract) } -} - -func (m *Module) acceptAs(w http.ResponseWriter, r *http.Request, contract string) { - name := r.PathValue("name") - var req acceptRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return +func (m *Module) accept(contract string) func(context.Context, *packageInput) (*httpapi.Reply[packageState], error) { + return func(ctx context.Context, in *packageInput) (*httpapi.Reply[packageState], error) { + return m.acceptAs(ctx, in, contract) } +} + +type packageInput struct { + Name string `path:"name" doc:"Lowercase letters, digits and hyphens"` + Body acceptRequest +} + +type nameInput struct { + Name string `path:"name"` +} + +// packageState is an accepted package's name and state after a change. +type packageState struct { + Name string `json:"name"` + State string `json:"state" enum:"running,removed"` +} + +func (m *Module) acceptAs(ctx context.Context, in *packageInput, contract string) (*httpapi.Reply[packageState], error) { + name, req := in.Name, in.Body if !validName.MatchString(name) || req.Path == "" || req.SHA256 == "" { - httpjson.Error(w, http.StatusBadRequest, "a connector needs a lowercase name, a path and a sha256") - return + return nil, huma.NewError(http.StatusBadRequest, "a connector needs a lowercase name, a path and a sha256") } settings, err := json.Marshal(req.Settings) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } slots, err := json.Marshal(req.Credentials, json.FormatNilMapAsNull(false)) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } a := store.Accepted{ OrgID: m.orgID, Name: name, Path: req.Path, SHA256: req.SHA256, @@ -311,27 +348,24 @@ func (m *Module) acceptAs(w http.ResponseWriter, r *http.Request, contract strin // holds a list either way. Tools: jsontext.Value(`[]`), } - if err := m.store.Upsert(r.Context(), a); err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return + if err := m.store.Upsert(ctx, a); err != nil { + return nil, huma.NewError(http.StatusInternalServerError, err.Error()) } - if err := m.launch(context.WithoutCancel(r.Context()), a); err != nil { - httpjson.Error(w, http.StatusUnprocessableEntity, err.Error()) - return + if err := m.launch(context.WithoutCancel(ctx), a); err != nil { + return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error()) } // The extension declares its settings when it starts. A value it doesn't // declare, or a required one that is missing, is refused now rather than // left for the extension to misread. if err := m.checkAccepted(a); err != nil { - _, _ = m.store.Delete(context.WithoutCancel(r.Context()), m.orgID, name) + _, _ = m.store.Delete(context.WithoutCancel(ctx), m.orgID, name) m.release(name) m.mu.Lock() delete(m.failed, name) m.mu.Unlock() - httpjson.Error(w, http.StatusUnprocessableEntity, err.Error()) - return + return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error()) } - httpjson.Write(w, http.StatusOK, map[string]string{"name": name, "state": "running"}) + return httpapi.OK(packageState{Name: name, State: "running"}), nil } // launch starts or restarts one accepted package and records the outcome. A diff --git a/modules/connectors/remove.go b/modules/connectors/remove.go index ec1a05415..8e7f225f5 100644 --- a/modules/connectors/remove.go +++ b/modules/connectors/remove.go @@ -7,12 +7,16 @@ import ( "slices" "strings" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors/internal/store" ) -func (m *Module) remove(contract string) http.HandlerFunc { - return func(w http.ResponseWriter, r *http.Request) { m.removeAs(w, r, contract) } +func (m *Module) remove(contract string) func(context.Context, *nameInput) (*httpapi.Reply[packageState], error) { + return func(ctx context.Context, in *nameInput) (*httpapi.Reply[packageState], error) { + return m.removeAs(ctx, in, contract) + } } // removeAs retires an accepted package: its row (and so its credential slots) @@ -20,41 +24,34 @@ func (m *Module) remove(contract string) http.HandlerFunc { // route's contract is a 404, which keeps a repeated removal harmless. A secret // engine a stored credential still resolves through is refused, since those // credentials would stop resolving. -func (m *Module) removeAs(w http.ResponseWriter, r *http.Request, contract string) { - ctx := r.Context() - name := r.PathValue("name") +func (m *Module) removeAs(ctx context.Context, in *nameInput, contract string) (*httpapi.Reply[packageState], error) { + name := in.Name accepted, err := m.store.List(ctx, m.orgID) if err != nil { m.log.ErrorContext(ctx, "list accepted packages", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the accepted packages") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the accepted packages") } if !slices.ContainsFunc(accepted, func(a store.Accepted) bool { return a.Name == name && a.Contract == contract }) { - httpjson.Error(w, http.StatusNotFound, fmt.Sprintf("no accepted %s named %s", contract, name)) - return + return nil, huma.NewError(http.StatusNotFound, fmt.Sprintf("no accepted %s named %s", contract, name)) } if contract == store.ContractSecretEngine { users, err := m.engineUsers(ctx, name) if err != nil { m.log.ErrorContext(ctx, "check secret engine use", "engine", name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't check the credentials that use "+name) - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't check the credentials that use "+name) } if len(users) > 0 { - httpjson.Error(w, http.StatusConflict, + return nil, huma.NewError(http.StatusConflict, fmt.Sprintf("secret engine %s is still used by credentials: %s", name, strings.Join(users, ", "))) - return } } found, err := m.store.Delete(ctx, m.orgID, name) if err != nil { m.log.ErrorContext(ctx, "remove accepted package", "package", name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't remove "+name) - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't remove "+name) } if !found { - httpjson.Error(w, http.StatusNotFound, fmt.Sprintf("no accepted %s named %s", contract, name)) - return + return nil, huma.NewError(http.StatusNotFound, fmt.Sprintf("no accepted %s named %s", contract, name)) } m.release(name) m.mu.Lock() @@ -63,7 +60,7 @@ func (m *Module) removeAs(w http.ResponseWriter, r *http.Request, contract strin // There is no audit trail module yet, so the removal is a structured log // line. m.log.InfoContext(ctx, "accepted package removed", "audit", true, "action", "package.remove", "contract", contract, "package", name) - httpjson.Write(w, http.StatusOK, map[string]string{"name": name, "state": "removed"}) + return httpapi.OK(packageState{Name: name, State: "removed"}), nil } // engineUsers names, in order, the credentials with a field resolved through diff --git a/modules/connectors/remove_test.go b/modules/connectors/remove_test.go index 8dcf6496b..054998a4a 100644 --- a/modules/connectors/remove_test.go +++ b/modules/connectors/remove_test.go @@ -3,13 +3,14 @@ package connectors import ( "context" json "encoding/json/v2" + "errors" "log/slog" "net/http" - "net/http/httptest" "strings" "testing" "filippo.io/age" + "github.com/danielgtaylor/huma/v2" "github.com/samcharles93/archie-core/modules/connectors/internal/seal" "github.com/samcharles93/archie-core/modules/connectors/internal/store" @@ -108,15 +109,13 @@ func TestRemovingAPackage(t *testing.T) { } m.store = reg m.failed[tt.target] = "boom" - req := httptest.NewRequestWithContext(t.Context(), http.MethodDelete, "/", nil) - req.SetPathValue("name", tt.target) - rec := httptest.NewRecorder() - m.removeAs(rec, req, tt.contract) - if rec.Code != tt.wantStatus { - t.Fatalf("status = %d, want %d (%s)", rec.Code, tt.wantStatus, rec.Body) + _, err := m.removeAs(t.Context(), &nameInput{Name: tt.target}, tt.contract) + status, body := statusOf(err) + if status != tt.wantStatus { + t.Fatalf("status = %d, want %d (%s)", status, tt.wantStatus, body) } - if !strings.Contains(rec.Body.String(), tt.wantBody) { - t.Errorf("body %q lacks %q", rec.Body, tt.wantBody) + if !strings.Contains(body, tt.wantBody) { + t.Errorf("body %q lacks %q", body, tt.wantBody) } if _, kept := reg.accepted[tt.target]; kept != tt.wantKept { t.Errorf("package kept = %v, want %v", kept, tt.wantKept) @@ -127,3 +126,14 @@ func TestRemovingAPackage(t *testing.T) { }) } } + +// statusOf is the status and message an operation's error answers with. +func statusOf(err error) (int, string) { + if err == nil { + return http.StatusOK, "" + } + if se, ok := errors.AsType[huma.StatusError](err); ok { + return se.GetStatus(), se.Error() + } + return http.StatusInternalServerError, err.Error() +} diff --git a/modules/deliveries/deliveries.go b/modules/deliveries/deliveries.go index 21bbd4958..6ba94b7e5 100644 --- a/modules/deliveries/deliveries.go +++ b/modules/deliveries/deliveries.go @@ -19,10 +19,11 @@ import ( "strconv" "time" + "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/jmoiron/sqlx" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/internal/platform/hub" "github.com/samcharles93/archie-core/modules/connectors" "github.com/samcharles93/archie-core/modules/deliveries/internal/store" @@ -251,42 +252,54 @@ func backoff(attempts int) time.Duration { return min(time.Duration(1< 0 { + if err := json.Unmarshal(src.KeyFields, &view.KeyFields); err != nil { + m.log.ErrorContext(ctx, "read source key fields", "source", src.Name, "error", err) + return nil, huma.Error500InternalServerError("couldn't read the key fields of " + src.Name) + } + } + out = append(out, view) + } + return httpapi.OK(out), nil +} + +// triggerView is a trigger as the API returns it. +type triggerView struct { + Name string `json:"name"` + Source string `json:"source"` + EventType string `json:"event_type"` + Filter map[string]string `json:"filter"` + Workflow string `json:"workflow"` + Enabled bool `json:"enabled"` + Every string `json:"every,omitempty"` +} + +func (m *Module) triggers(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]triggerView], error) { + triggers, err := m.store.AllTriggers(ctx, m.orgID) + if err != nil { + m.log.ErrorContext(ctx, "list triggers", "error", err) + return nil, huma.Error500InternalServerError("couldn't list triggers") + } + out := make([]triggerView, 0, len(triggers)) + for _, t := range triggers { + view := triggerView{Name: t.Name, Source: t.Source, EventType: t.EventType, Workflow: t.Workflow, Enabled: t.Enabled, Filter: map[string]string{}} + if len(t.Filter) > 0 { + if err := json.Unmarshal(t.Filter, &view.Filter); err != nil { + m.log.ErrorContext(ctx, "read trigger filter", "trigger", t.Name, "error", err) + return nil, huma.Error500InternalServerError("couldn't read the filter of " + t.Name) + } + } + if t.ScheduleEverySeconds.Valid { + view.Every = (time.Duration(t.ScheduleEverySeconds.Int64) * time.Second).String() + } + out = append(out, view) + } + return httpapi.OK(out), nil +} + +type recentInput struct { + Limit int `query:"limit" minimum:"1" maximum:"500" default:"50"` + Source string `query:"source"` + Type string `query:"type"` + Matched string `query:"matched" enum:"true,false" doc:"Only events a trigger did or didn't match"` +} + +func (m *Module) recent(ctx context.Context, in *recentInput) (*httpapi.Reply[[]eventView], error) { + filter := store.EventFilter{Source: in.Source, Type: in.Type, Limit: in.Limit} + if in.Matched != "" { + matched, err := strconv.ParseBool(in.Matched) + if err != nil { + return nil, huma.Error400BadRequest("matched is true or false") + } + filter.Matched = &matched + } + events, err := m.store.Recent(ctx, m.orgID, filter) + if err != nil { + return nil, huma.Error500InternalServerError("couldn't list events", err) + } + out := make([]eventView, 0, len(events)) + for _, e := range events { + out = append(out, viewOf(e)) + } + return httpapi.OK(out), nil +} + +// eventDetail is one event with the payload it arrived in and the runs it +// started. +type eventDetail struct { + eventView + Body jsontext.Value `json:"body"` + Runs []triggerRun `json:"runs"` +} + +type triggerRun struct { + Trigger string `json:"trigger"` + RunID uuid.UUID `json:"run_id"` +} + +type eventInput struct { + ID string `path:"id" format:"uuid"` +} + +func (m *Module) event(ctx context.Context, in *eventInput) (*httpapi.Reply[eventDetail], error) { + id, err := uuid.Parse(in.ID) + if err != nil { + return nil, huma.Error400BadRequest("an event id is a UUID") + } + e, err := m.store.Event(ctx, m.orgID, id) + if errors.Is(err, store.ErrNotFound) { + return nil, huma.Error404NotFound("no such event") + } + if err != nil { + m.log.ErrorContext(ctx, "read event", "event", id, "error", err) + return nil, huma.Error500InternalServerError("couldn't read the event") + } + runs, err := m.store.RunsForEvent(ctx, m.orgID, id) + if err != nil { + m.log.ErrorContext(ctx, "read event runs", "event", id, "error", err) + return nil, huma.Error500InternalServerError("couldn't read the runs of the event") + } + view := eventDetail{eventView: viewOf(e), Body: jsontext.Value(e.Body), Runs: make([]triggerRun, 0, len(runs))} + if len(view.Body) == 0 || !view.Body.IsValid() { + view.Body = jsontext.Value("null") + } + for _, run := range runs { + view.Runs = append(view.Runs, triggerRun{Trigger: run.Trigger, RunID: run.RunID}) + } + return httpapi.OK(view), nil +} + +// eventView is an event as the API returns it. +type eventView struct { + ID uuid.UUID `json:"id"` + Source string `json:"source"` + Type string `json:"type"` + Fields jsontext.Value `json:"fields"` + LinkedTo *uuid.UUID `json:"linked_to,omitempty"` + OccurredAt *time.Time `json:"occurred_at,omitempty"` + ReceivedAt time.Time `json:"received_at"` + Matched bool `json:"matched"` + DispatchedAt *time.Time `json:"dispatched_at,omitempty"` +} + +func viewOf(e store.Event) eventView { + v := eventView{ + ID: e.ID, Source: e.Source, Type: e.Type, Fields: e.Fields, LinkedTo: e.LinkedTo, + ReceivedAt: e.ReceivedAt, Matched: e.Matched, + } + if e.OccurredAt.Valid { + v.OccurredAt = &e.OccurredAt.Time + } + if e.DispatchedAt.Valid { + v.DispatchedAt = &e.DispatchedAt.Time + } + return v +} diff --git a/modules/events/events.go b/modules/events/events.go index 7935d0202..07b98dd00 100644 --- a/modules/events/events.go +++ b/modules/events/events.go @@ -10,7 +10,6 @@ package events import ( "context" "crypto/rand" - "database/sql" "encoding/hex" "encoding/json/jsontext" json "encoding/json/v2" @@ -19,7 +18,6 @@ import ( "log/slog" "net/http" "regexp" - "strconv" "sync" "time" @@ -81,17 +79,10 @@ func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, c Connectors, r Runs return &Module{orgID: orgID, store: store.New(db), connectors: c, runs: r, answers: a, deliveries: d, log: log, poll: time.Second} } -// Routes adds the webhook intake and the guarded admin routes. -func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { +// Routes adds the webhook intake. It stays outside the API because each +// source verifies its own token before the body is read. +func (m *Module) Routes(mux *http.ServeMux) { mux.HandleFunc("POST /hooks/{source}", m.intake) - mux.Handle("PUT /api/sources/{name}", guard(http.HandlerFunc(m.putSource))) - mux.Handle("PUT /api/sources/{name}/key-fields", guard(http.HandlerFunc(m.putKeyFields))) - mux.Handle("PUT /api/triggers/{name}", guard(http.HandlerFunc(m.putTrigger))) - mux.Handle("GET /api/sources", guard(http.HandlerFunc(m.sources))) - mux.Handle("GET /api/triggers", guard(http.HandlerFunc(m.triggers))) - mux.Handle("GET /api/groups", guard(http.HandlerFunc(m.groups))) - mux.Handle("GET /api/events", guard(http.HandlerFunc(m.recent))) - mux.Handle("GET /api/events/{id}", guard(http.HandlerFunc(m.event))) } // intake verifies the source's token before reading the body, has the @@ -333,325 +324,6 @@ func runInput(e store.Event) jsontext.Value { return input } -type sourceRequest struct { - Connector string `json:"connector"` -} - -// putSource creates a source or rotates its token. The token is returned once -// and stored only as its hash. -func (m *Module) putSource(w http.ResponseWriter, r *http.Request) { - name := r.PathValue("name") - var req sourceRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - if !validName.MatchString(name) || !validName.MatchString(req.Connector) { - httpjson.Error(w, http.StatusBadRequest, "a source needs a lowercase name and a connector") - return - } - token, err := newToken() - if err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return - } - if err := m.store.UpsertSource(r.Context(), store.Source{ - OrgID: m.orgID, Name: name, Connector: req.Connector, TokenSHA256: httpjson.TokenHash(token), - }); err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return - } - httpjson.Write(w, http.StatusOK, map[string]string{"source": name, "token": token, "url": "/hooks/" + name}) -} - -type triggerRequest struct { - Source string `json:"source"` - EventType string `json:"event_type"` - Filter map[string]string `json:"filter"` - Workflow string `json:"workflow"` - Disabled bool `json:"disabled"` - // Every makes the trigger fire on an interval ("1h") instead of on - // events; source and event_type are then fixed to the schedule's own. - Every string `json:"every"` -} - -func (m *Module) putTrigger(w http.ResponseWriter, r *http.Request) { - name := r.PathValue("name") - var req triggerRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - var every sql.NullInt64 - if req.Every != "" { - d, err := time.ParseDuration(req.Every) - if err != nil || d < minInterval || d%time.Second != 0 { - httpjson.Error(w, http.StatusBadRequest, "every is a whole number of seconds of at least one minute, such as 1h") - return - } - every = sql.NullInt64{Int64: int64(d / time.Second), Valid: true} - req.Source, req.EventType = scheduleSource, scheduleType - // Every schedule's ticks share a source and type, so the filter keeps - // this trigger to its own. - req.Filter = map[string]string{"trigger": name} - } - if !validName.MatchString(name) || req.Source == "" || req.EventType == "" || req.Workflow == "" { - httpjson.Error(w, http.StatusBadRequest, "a trigger needs a lowercase name, a workflow, and either a source and event type or an every interval") - return - } - filter, err := json.Marshal(req.Filter) - if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - if err := m.store.UpsertTrigger(r.Context(), store.Trigger{ - OrgID: m.orgID, Name: name, Source: req.Source, EventType: req.EventType, - Filter: filter, Workflow: req.Workflow, Enabled: !req.Disabled, ScheduleEverySeconds: every, - }); err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return - } - httpjson.Write(w, http.StatusOK, map[string]string{"trigger": name}) -} - -type keyFieldsRequest struct { - Paths []string `json:"paths"` -} - -// putKeyFields sets the fields a source's events are grouped by. It applies to -// events that arrive after it. -func (m *Module) putKeyFields(w http.ResponseWriter, r *http.Request) { - var req keyFieldsRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - if req.Paths == nil { - req.Paths = []string{} - } - raw, err := json.Marshal(req.Paths) - if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - err = m.store.SetKeyFields(r.Context(), m.orgID, r.PathValue("name"), raw) - if errors.Is(err, store.ErrNotFound) { - httpjson.Error(w, http.StatusNotFound, "no such source") - return - } - if err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return - } - httpjson.Write(w, http.StatusOK, map[string][]string{"key_fields": req.Paths}) -} - -// groupView is a group of unmatched events as the API returns it. Proposed is -// the trigger it suggests, with the workflow left for the person to choose. -type groupView struct { - ID uuid.UUID `json:"id"` - Count int64 `json:"count"` - FirstSeen time.Time `json:"first_seen"` - LastSeen time.Time `json:"last_seen"` - Proposed proposedTrigger `json:"proposed"` -} - -type proposedTrigger struct { - Source string `json:"source"` - EventType string `json:"event_type"` - Filter jsontext.Value `json:"filter"` - Workflow string `json:"workflow"` -} - -func (m *Module) groups(w http.ResponseWriter, r *http.Request) { - groups, err := m.store.Groups(r.Context(), m.orgID, 200) - if err != nil { - m.log.ErrorContext(r.Context(), "list groups", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't list groups") - return - } - out := make([]groupView, 0, len(groups)) - for _, g := range groups { - out = append(out, groupView{ - ID: g.ID, Count: g.Count, FirstSeen: g.FirstSeen, LastSeen: g.LastSeen, - Proposed: proposedTrigger{Source: g.Source, EventType: g.EventType, Filter: g.Filter}, - }) - } - httpjson.Write(w, http.StatusOK, out) -} - -// sourceView is a source as the API returns it. The token is returned only -// when it is created or rotated, never here. -type sourceView struct { - Name string `json:"name"` - Connector string `json:"connector"` - KeyFields []string `json:"key_fields"` - TokenSet bool `json:"token_set"` -} - -func (m *Module) sources(w http.ResponseWriter, r *http.Request) { - sources, err := m.store.Sources(r.Context(), m.orgID) - if err != nil { - m.log.ErrorContext(r.Context(), "list sources", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't list sources") - return - } - out := make([]sourceView, 0, len(sources)) - for _, src := range sources { - view := sourceView{Name: src.Name, Connector: src.Connector, TokenSet: src.TokenSHA256 != "", KeyFields: []string{}} - if len(src.KeyFields) > 0 { - if err := json.Unmarshal(src.KeyFields, &view.KeyFields); err != nil { - m.log.ErrorContext(r.Context(), "read source key fields", "source", src.Name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the key fields of "+src.Name) - return - } - } - out = append(out, view) - } - httpjson.Write(w, http.StatusOK, out) -} - -// triggerView is a trigger as the API returns it. -type triggerView struct { - Name string `json:"name"` - Source string `json:"source"` - EventType string `json:"event_type"` - Filter map[string]string `json:"filter"` - Workflow string `json:"workflow"` - Enabled bool `json:"enabled"` - Every string `json:"every,omitempty"` -} - -func (m *Module) triggers(w http.ResponseWriter, r *http.Request) { - triggers, err := m.store.AllTriggers(r.Context(), m.orgID) - if err != nil { - m.log.ErrorContext(r.Context(), "list triggers", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't list triggers") - return - } - out := make([]triggerView, 0, len(triggers)) - for _, t := range triggers { - view := triggerView{Name: t.Name, Source: t.Source, EventType: t.EventType, Workflow: t.Workflow, Enabled: t.Enabled, Filter: map[string]string{}} - if len(t.Filter) > 0 { - if err := json.Unmarshal(t.Filter, &view.Filter); err != nil { - m.log.ErrorContext(r.Context(), "read trigger filter", "trigger", t.Name, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the filter of "+t.Name) - return - } - } - if t.ScheduleEverySeconds.Valid { - view.Every = (time.Duration(t.ScheduleEverySeconds.Int64) * time.Second).String() - } - out = append(out, view) - } - httpjson.Write(w, http.StatusOK, out) -} - -func (m *Module) recent(w http.ResponseWriter, r *http.Request) { - limit := 50 - if n, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil && n > 0 && n <= 500 { - limit = n - } - filter := store.EventFilter{ - Source: r.URL.Query().Get("source"), - Type: r.URL.Query().Get("type"), - Limit: limit, - } - if q := r.URL.Query().Get("matched"); q != "" { - matched, err := strconv.ParseBool(q) - if err != nil { - httpjson.Error(w, http.StatusBadRequest, "matched is true or false") - return - } - filter.Matched = &matched - } - events, err := m.store.Recent(r.Context(), m.orgID, filter) - if err != nil { - httpjson.Error(w, http.StatusInternalServerError, err.Error()) - return - } - out := make([]eventView, 0, len(events)) - for _, e := range events { - out = append(out, viewOf(e)) - } - httpjson.Write(w, http.StatusOK, out) -} - -// eventDetail is one event with the payload it arrived in and the runs it -// started. -type eventDetail struct { - eventView - Body jsontext.Value `json:"body"` - Runs []triggerRun `json:"runs"` -} - -type triggerRun struct { - Trigger string `json:"trigger"` - RunID uuid.UUID `json:"run_id"` -} - -func (m *Module) event(w http.ResponseWriter, r *http.Request) { - id, err := uuid.Parse(r.PathValue("id")) - if err != nil { - httpjson.Error(w, http.StatusBadRequest, "an event id is a UUID") - return - } - e, err := m.store.Event(r.Context(), m.orgID, id) - if errors.Is(err, store.ErrNotFound) { - httpjson.Error(w, http.StatusNotFound, "no such event") - return - } - if err != nil { - m.log.ErrorContext(r.Context(), "read event", "event", id, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the event") - return - } - runs, err := m.store.RunsForEvent(r.Context(), m.orgID, id) - if err != nil { - m.log.ErrorContext(r.Context(), "read event runs", "event", id, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the runs of the event") - return - } - view := eventDetail{eventView: viewOf(e), Body: jsontext.Value(e.Body), Runs: make([]triggerRun, 0, len(runs))} - if len(view.Body) == 0 { - view.Body = jsontext.Value("null") - } - if !view.Body.IsValid() { - view.Body = jsontext.Value("null") - } - for _, run := range runs { - view.Runs = append(view.Runs, triggerRun{Trigger: run.Trigger, RunID: run.RunID}) - } - httpjson.Write(w, http.StatusOK, view) -} - -// eventView is an event as the API returns it. -type eventView struct { - ID uuid.UUID `json:"id"` - Source string `json:"source"` - Type string `json:"type"` - Fields jsontext.Value `json:"fields"` - LinkedTo *uuid.UUID `json:"linked_to,omitempty"` - OccurredAt *time.Time `json:"occurred_at,omitempty"` - ReceivedAt time.Time `json:"received_at"` - Matched bool `json:"matched"` - DispatchedAt *time.Time `json:"dispatched_at,omitempty"` -} - -func viewOf(e store.Event) eventView { - v := eventView{ - ID: e.ID, Source: e.Source, Type: e.Type, Fields: e.Fields, LinkedTo: e.LinkedTo, - ReceivedAt: e.ReceivedAt, Matched: e.Matched, - } - if e.OccurredAt.Valid { - v.OccurredAt = &e.OccurredAt.Time - } - if e.DispatchedAt.Valid { - v.DispatchedAt = &e.DispatchedAt.Time - } - return v -} - func newToken() (string, error) { b := make([]byte, 32) if _, err := rand.Read(b); err != nil { diff --git a/modules/governance/governance.go b/modules/governance/governance.go index fdd1a5aef..12b998a15 100644 --- a/modules/governance/governance.go +++ b/modules/governance/governance.go @@ -16,11 +16,12 @@ import ( "slices" "time" + "github.com/danielgtaylor/huma/v2" "github.com/jmoiron/sqlx" "github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/ai-sdk/runtime" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/governance/internal/store" ) @@ -342,42 +343,58 @@ func (m *Module) ApprovalDeadline(ctx context.Context) (time.Duration, error) { return set.ApprovalDeadline, nil } -// Routes adds the settings API to mux behind guard. -func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { - mux.Handle("GET /api/settings/agent-model", guard(http.HandlerFunc(m.getAgentModel))) - mux.Handle("PUT /api/settings/agent-model", guard(http.HandlerFunc(m.putAgentModel))) - mux.Handle("POST /api/settings/agent-model/test", guard(http.HandlerFunc(m.testAgentModel))) - mux.Handle("GET /api/settings", guard(http.HandlerFunc(m.getSettings))) - mux.Handle("PUT /api/settings", guard(http.HandlerFunc(m.putSettings))) - mux.Handle("GET /api/people", guard(http.HandlerFunc(m.getPeople))) - mux.Handle("PUT /api/people", guard(http.HandlerFunc(m.putPeople))) +// Register adds the settings API: organisation settings, the agent model and +// people. +func (m *Module) Register(api huma.API) { + tags := []string{"Governance"} + huma.Register(api, huma.Operation{ + OperationID: "get-settings", Method: http.MethodGet, Path: "/api/settings", + Summary: "Get the organisation settings", Tags: tags, + }, m.getSettings) + huma.Register(api, huma.Operation{ + OperationID: "put-settings", Method: http.MethodPut, Path: "/api/settings", + Summary: "Change the organisation settings", Tags: tags, + }, m.putSettings) + huma.Register(api, huma.Operation{ + OperationID: "get-agent-model", Method: http.MethodGet, Path: "/api/settings/agent-model", + Summary: "Get the agent model", Tags: tags, + }, m.getAgentModel) + huma.Register(api, huma.Operation{ + OperationID: "put-agent-model", Method: http.MethodPut, Path: "/api/settings/agent-model", + Summary: "Set the agent model", Tags: tags, + }, m.putAgentModel) + huma.Register(api, huma.Operation{ + OperationID: "test-agent-model", Method: http.MethodPost, Path: "/api/settings/agent-model/test", + Summary: "Ask a model one question before saving it", Tags: tags, + }, m.testAgentModel) + huma.Register(api, huma.Operation{ + OperationID: "list-people", Method: http.MethodGet, Path: "/api/people", + Summary: "List the people", Tags: tags, + }, m.getPeople) + huma.Register(api, huma.Operation{ + OperationID: "put-people", Method: http.MethodPut, Path: "/api/people", + Summary: "Replace the people", Tags: tags, + }, m.putPeople) } -func (m *Module) getSettings(w http.ResponseWriter, r *http.Request) { - set, err := m.Settings(r.Context()) +func (m *Module) getSettings(ctx context.Context, _ *struct{}) (*httpapi.Reply[settingsRequest], error) { + set, err := m.Settings(ctx) if err != nil { - m.log.ErrorContext(r.Context(), "read settings", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the settings") - return + m.log.ErrorContext(ctx, "read settings", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the settings") } - httpjson.Write(w, http.StatusOK, set.request()) + return httpapi.OK(set.request()), nil } -func (m *Module) putSettings(w http.ResponseWriter, r *http.Request) { - var req settingsRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } +func (m *Module) putSettings(ctx context.Context, in *struct{ Body settingsRequest }) (*httpapi.Reply[settingsRequest], error) { + req := in.Body deadline, err := time.ParseDuration(req.ApprovalDeadline) if err != nil { - httpjson.Error(w, http.StatusBadRequest, "approval deadline is a duration, such as 24h") - return + return nil, huma.NewError(http.StatusBadRequest, "approval deadline is a duration, such as 24h") } steps, err := stepsOf(req.Escalation) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } set := Settings{ ApprovalDeadline: deadline, RaiseAfter: req.RaiseAfter, Frozen: req.Frozen, @@ -386,18 +403,15 @@ func (m *Module) putSettings(w http.ResponseWriter, r *http.Request) { Timing: req.Timing.normalised(), ActionsPerRun: req.ActionsPerRun, ActionsPerDay: req.ActionsPerDay, } if err := set.validate(); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - people, err := m.store.People(r.Context(), m.orgID) + people, err := m.store.People(ctx, m.orgID) if err != nil { - m.log.ErrorContext(r.Context(), "read people", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings") - return + m.log.ErrorContext(ctx, "read people", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the settings") } if err := set.knows(people); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } rows := make([]stepRow, 0, len(set.Escalation)) for _, st := range set.Escalation { @@ -405,25 +419,22 @@ func (m *Module) putSettings(w http.ResponseWriter, r *http.Request) { } escalation, err := json.Marshal(rows) if err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the settings") } timing, err := json.Marshal(set.Timing) if err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the settings") } - if err := m.store.PutSettings(r.Context(), store.Settings{ + if err := m.store.PutSettings(ctx, store.Settings{ OrgID: m.orgID, ApprovalDeadlineMS: set.ApprovalDeadline.Milliseconds(), RaiseAfter: set.RaiseAfter, Frozen: set.Frozen, RecurrenceThreshold: set.RecurrenceThreshold, AttemptsPerRun: set.AttemptsPerRun, DefaultOwner: set.DefaultOwner, Escalation: string(escalation), Timing: string(timing), ActionsPerRun: set.ActionsPerRun, ActionsPerDay: set.ActionsPerDay, }); err != nil { - m.log.ErrorContext(r.Context(), "put settings", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings") - return + m.log.ErrorContext(ctx, "put settings", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the settings") } - httpjson.Write(w, http.StatusOK, set.request()) + return httpapi.OK(set.request()), nil } // validate keeps a deadline inside the range an answer can be given in, the @@ -484,45 +495,44 @@ func (s Settings) knows(people []store.Person) error { return nil } -func (m *Module) getAgentModel(w http.ResponseWriter, r *http.Request) { - model, err := m.AgentModel(r.Context()) +func (m *Module) getAgentModel(ctx context.Context, _ *struct{}) (*httpapi.Reply[Model], error) { + model, err := m.AgentModel(ctx) switch { case errors.Is(err, ErrNoAgentModel): - httpjson.Error(w, http.StatusNotFound, err.Error()) + return nil, huma.NewError(http.StatusNotFound, err.Error()) case err != nil: - m.log.ErrorContext(r.Context(), "read agent model", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the agent model") + m.log.ErrorContext(ctx, "read agent model", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the agent model") default: - httpjson.Write(w, http.StatusOK, model) + return httpapi.OK(model), nil } } // putAgentModel sets the agent model. An empty base URL takes the class's // published default, and the stored value is always explicit. -func (m *Module) putAgentModel(w http.ResponseWriter, r *http.Request) { - var req Model - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } +func (m *Module) putAgentModel(ctx context.Context, in *struct{ Body Model }) (*httpapi.Reply[Model], error) { + req := in.Body model, err := settle(req) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - if _, _, err := m.provider(r.Context(), model); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + if _, _, err := m.provider(ctx, model); err != nil { + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - if err := m.store.PutModelRole(r.Context(), store.ModelRole{ + if err := m.store.PutModelRole(ctx, store.ModelRole{ OrgID: m.orgID, Role: roleAgent, Class: model.Class, BaseURL: model.BaseURL, Model: model.Model, APIKeyCredential: model.APIKeyCredential, }); err != nil { - m.log.ErrorContext(r.Context(), "put agent model", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the agent model") - return + m.log.ErrorContext(ctx, "put agent model", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the agent model") } - httpjson.Write(w, http.StatusOK, model) + return httpapi.OK(model), nil +} + +// modelAnswer is a test call's answer. +type modelAnswer struct { + Model string `json:"model"` + Answer string `json:"answer"` } // testTimeout bounds a test call, so a slow endpoint answers the operator with @@ -531,23 +541,17 @@ const testTimeout = 60 * time.Second // testAgentModel asks the model one question and reports its answer, so the // operator knows the endpoint, model and key work before saving them. -func (m *Module) testAgentModel(w http.ResponseWriter, r *http.Request) { - var req Model - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } +func (m *Module) testAgentModel(ctx context.Context, in *struct{ Body Model }) (*httpapi.Reply[modelAnswer], error) { + req := in.Body model, err := settle(req) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - provider, _, err := m.provider(r.Context(), model) + provider, _, err := m.provider(ctx, model) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - ctx, cancel := context.WithTimeout(r.Context(), testTimeout) + ctx, cancel := context.WithTimeout(ctx, testTimeout) defer cancel() resp, err := provider.Chat(ctx, chat.Request{ Model: model.Model, @@ -555,10 +559,9 @@ func (m *Module) testAgentModel(w http.ResponseWriter, r *http.Request) { MaxTokens: 32, }) if err != nil { - httpjson.Error(w, http.StatusBadGateway, err.Error()) - return + return nil, huma.NewError(http.StatusBadGateway, err.Error()) } - httpjson.Write(w, http.StatusOK, map[string]string{"model": model.Model, "answer": resp.Content}) + return httpapi.OK(modelAnswer{Model: model.Model, Answer: resp.Content}), nil } func settle(req Model) (Model, error) { diff --git a/modules/governance/people.go b/modules/governance/people.go index 0a50d810c..1afba4b09 100644 --- a/modules/governance/people.go +++ b/modules/governance/people.go @@ -8,9 +8,10 @@ import ( "slices" "strings" + "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/governance/internal/store" ) @@ -59,54 +60,45 @@ func (m *Module) PersonID(ctx context.Context, identity string) (string, bool, e // personRequest is a person as the API shows and sets them. An empty id is a // new person. type personRequest struct { - ID string `json:"id"` + ID string `json:"id" required:"false" doc:"Empty for a new person"` Name string `json:"name"` Authority bool `json:"authority"` Identities []string `json:"identities"` } -func (m *Module) getPeople(w http.ResponseWriter, r *http.Request) { - people, err := m.store.People(r.Context(), m.orgID) +func (m *Module) getPeople(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]personRequest], error) { + people, err := m.store.People(ctx, m.orgID) if err != nil { - m.log.ErrorContext(r.Context(), "read people", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the people") - return + m.log.ErrorContext(ctx, "read people", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the people") } out := make([]personRequest, 0, len(people)) for _, p := range people { out = append(out, personRequest{ID: p.ID.String(), Name: p.Name, Authority: p.Authority, Identities: p.Identities}) } - httpjson.Write(w, http.StatusOK, out) + return httpapi.OK(out), nil } // putPeople replaces the organisation's people with the list in the request. -func (m *Module) putPeople(w http.ResponseWriter, r *http.Request) { - var req []personRequest - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } +func (m *Module) putPeople(ctx context.Context, in *struct{ Body []personRequest }) (*httpapi.Reply[[]personRequest], error) { + req := in.Body people, err := peopleOf(req) if err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return + return nil, huma.NewError(http.StatusBadRequest, err.Error()) } - set, err := m.Settings(r.Context()) + set, err := m.Settings(ctx) if err != nil { - m.log.ErrorContext(r.Context(), "read settings", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the people") - return + m.log.ErrorContext(ctx, "read settings", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the people") } if err := set.stillKnows(people); err != nil { - httpjson.Error(w, http.StatusConflict, err.Error()) - return + return nil, huma.NewError(http.StatusConflict, err.Error()) } - if err := m.store.ReplacePeople(r.Context(), m.orgID, people); err != nil { - m.log.ErrorContext(r.Context(), "put people", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the people") - return + if err := m.store.ReplacePeople(ctx, m.orgID, people); err != nil { + m.log.ErrorContext(ctx, "put people", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't save the people") } - m.getPeople(w, r) + return m.getPeople(ctx, nil) } // stillKnows refuses to remove a person the settings name. diff --git a/modules/judgement/classes.go b/modules/judgement/classes.go index 26376e4e8..54ac6afa3 100644 --- a/modules/judgement/classes.go +++ b/modules/judgement/classes.go @@ -9,10 +9,11 @@ import ( "net/http" "time" + "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/jmoiron/sqlx" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/judgement/internal/store" ) @@ -317,68 +318,75 @@ func (c *Classes) Reset(ctx context.Context, id uuid.UUID, by string) (ClassView // bootstrapAdmin names the identity the bootstrap admin token stands for. const bootstrapAdmin = "admin" -// Routes adds the action classes API to mux behind guard. -func (c *Classes) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler, outcomes Outcomes) { - mux.Handle("GET /api/classes", guard(http.HandlerFunc(c.list))) - mux.Handle("GET /api/classes/{id}", guard(c.detail(outcomes))) - mux.Handle("POST /api/classes/{id}/reset", guard(http.HandlerFunc(c.reset))) +// Register adds the action classes API. +func (c *Classes) Register(api huma.API, outcomes Outcomes) { + tags := []string{"Controls"} + huma.Register(api, huma.Operation{ + OperationID: "list-classes", Method: http.MethodGet, Path: "/api/classes", + Summary: "List action classes with their earned levels", Tags: tags, + }, c.list) + huma.Register(api, huma.Operation{ + OperationID: "get-class", Method: http.MethodGet, Path: "/api/classes/{id}", + Summary: "Get an action class with its history and outcomes", Tags: tags, + }, c.detail(outcomes)) + huma.Register(api, huma.Operation{ + OperationID: "reset-class", Method: http.MethodPost, Path: "/api/classes/{id}/reset", + Summary: "Reset an action class to its default level", Tags: tags, + }, c.reset) } -func (c *Classes) list(w http.ResponseWriter, r *http.Request) { - out, err := c.List(r.Context()) +func (c *Classes) list(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]ClassView], error) { + out, err := c.List(ctx) if err != nil { - c.log.ErrorContext(r.Context(), "list classes", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't list action classes") - return + c.log.ErrorContext(ctx, "list classes", "error", err) + return nil, huma.Error500InternalServerError("couldn't list action classes") } - httpjson.Write(w, http.StatusOK, out) + return httpapi.OK(out), nil } -func (c *Classes) detail(outcomes Outcomes) http.Handler { - return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - id, ok := classID(w, r) - if !ok { - return +func (c *Classes) detail(outcomes Outcomes) func(context.Context, *classInput) (*httpapi.Reply[ClassDetail], error) { + return func(ctx context.Context, in *classInput) (*httpapi.Reply[ClassDetail], error) { + id, err := classID(in.ID) + if err != nil { + return nil, err } - out, err := c.Detail(r.Context(), id, outcomes) - if !c.found(w, r, err) { - return + out, err := c.Detail(ctx, id, outcomes) + if err != nil { + return nil, c.notFound(ctx, err) } - httpjson.Write(w, http.StatusOK, out) - }) + return httpapi.OK(out), nil + } } -func (c *Classes) reset(w http.ResponseWriter, r *http.Request) { - id, ok := classID(w, r) - if !ok { - return - } - out, err := c.Reset(r.Context(), id, bootstrapAdmin) - if !c.found(w, r, err) { - return - } - httpjson.Write(w, http.StatusOK, out) +type classInput struct { + ID string `path:"id" format:"uuid"` } -func classID(w http.ResponseWriter, r *http.Request) (uuid.UUID, bool) { - id, err := uuid.Parse(r.PathValue("id")) +func (c *Classes) reset(ctx context.Context, in *classInput) (*httpapi.Reply[ClassView], error) { + id, err := classID(in.ID) if err != nil { - httpjson.Error(w, http.StatusBadRequest, "id is a class id") - return uuid.Nil, false + return nil, err } - return id, true + out, err := c.Reset(ctx, id, bootstrapAdmin) + if err != nil { + return nil, c.notFound(ctx, err) + } + return httpapi.OK(out), nil +} + +func classID(raw string) (uuid.UUID, error) { + id, err := uuid.Parse(raw) + if err != nil { + return uuid.Nil, huma.Error400BadRequest("id is a class id") + } + return id, nil } // found writes the error response for err and reports whether there was none. -func (c *Classes) found(w http.ResponseWriter, r *http.Request, err error) bool { - switch { - case err == nil: - return true - case errors.Is(err, ErrNoClass): - httpjson.Error(w, http.StatusNotFound, "no such action class") - default: - c.log.ErrorContext(r.Context(), "action class", "path", r.URL.Path, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the action class") +func (c *Classes) notFound(ctx context.Context, err error) error { + if errors.Is(err, ErrNoClass) { + return huma.Error404NotFound("no such action class") } - return false + c.log.ErrorContext(ctx, "action class", "error", err) + return huma.Error500InternalServerError("couldn't read the action class") } diff --git a/modules/judgement/judges.go b/modules/judgement/judges.go index 2729dc7df..161f7460a 100644 --- a/modules/judgement/judges.go +++ b/modules/judgement/judges.go @@ -6,7 +6,9 @@ import ( "net/http" "time" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors" ) @@ -86,17 +88,19 @@ func (m *Module) latestJudge(ctx context.Context, guard string) (*JudgeStanding, return nil, nil } -// Routes adds the judgement controls API to mux behind guard. -func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { - mux.Handle("GET /api/controls/judges", guard(http.HandlerFunc(m.listJudges))) +// Register adds the judgement controls API. +func (m *Module) Register(api huma.API) { + huma.Register(api, huma.Operation{ + OperationID: "list-judges", Method: http.MethodGet, Path: "/api/controls/judges", + Summary: "List each guard's judge, its standing and its eval date", Tags: []string{"Controls"}, + }, m.listJudges) } -func (m *Module) listJudges(w http.ResponseWriter, r *http.Request) { - out, err := m.Judges(r.Context()) +func (m *Module) listJudges(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]JudgeControl], error) { + out, err := m.Judges(ctx) if err != nil { - m.log.ErrorContext(r.Context(), "list judges", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the judges") - return + m.log.ErrorContext(ctx, "list judges", "error", err) + return nil, huma.Error500InternalServerError("couldn't read the judges") } - httpjson.Write(w, http.StatusOK, out) + return httpapi.OK(out), nil } diff --git a/modules/judgement/policies.go b/modules/judgement/policies.go index 5932d9554..41e20b73d 100644 --- a/modules/judgement/policies.go +++ b/modules/judgement/policies.go @@ -17,10 +17,11 @@ import ( cedar "github.com/cedar-policy/cedar-go" "github.com/cedar-policy/cedar-go/types" + "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/jmoiron/sqlx" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/connectors" "github.com/samcharles93/archie-core/modules/judgement/internal/store" ) @@ -381,56 +382,58 @@ func (p *Policies) Put(ctx context.Context, kind, body, by string) (PolicySetVie // ErrInvalidPolicy means a policy set didn't compile or didn't fit its kind. var ErrInvalidPolicy = errors.New("invalid policy set") -// Routes adds the policy API to mux behind guard. -func (p *Policies) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { - for path, kind := range map[string]string{"/api/policies/hard-rules": KindHardRules, "/api/policies/change-request": KindChangeRequest} { - mux.Handle("GET "+path, guard(p.get(kind))) - mux.Handle("PUT "+path, guard(p.put(kind))) +// Register adds the policy API. +func (p *Policies) Register(api huma.API) { + tags := []string{"Controls"} + for _, k := range []struct{ kind, path, id, noun string }{ + {KindHardRules, "/api/policies/hard-rules", "hard-rules", "hard rules"}, + {KindChangeRequest, "/api/policies/change-request", "change-request-rules", "change-request rules"}, + } { + huma.Register(api, huma.Operation{ + OperationID: "get-" + k.id, Method: http.MethodGet, Path: k.path, + Summary: "Get the " + k.noun, Tags: tags, + }, p.get(k.kind)) + huma.Register(api, huma.Operation{ + OperationID: "put-" + k.id, Method: http.MethodPut, Path: k.path, + Summary: "Replace the " + k.noun + " with a new version", Tags: tags, + }, p.put(k.kind)) } } -func (p *Policies) get(kind string) http.Handler { - return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - version := 0 - if q := r.URL.Query().Get("version"); q != "" { - n, err := strconv.Atoi(q) - if err != nil || n < 1 { - httpjson.Error(w, http.StatusBadRequest, "version is a number") - return - } - version = n - } - out, err := p.View(r.Context(), kind, version) +func (p *Policies) get(kind string) func(context.Context, *policyVersionInput) (*httpapi.Reply[PolicySetView], error) { + return func(ctx context.Context, in *policyVersionInput) (*httpapi.Reply[PolicySetView], error) { + out, err := p.View(ctx, kind, in.Version) switch { case errors.Is(err, store.ErrNoPolicySet): - httpjson.Error(w, http.StatusNotFound, "no such version") + return nil, huma.Error404NotFound("no such version") case err != nil: - p.log.ErrorContext(r.Context(), "read policies", "kind", kind, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the policies") - default: - httpjson.Write(w, http.StatusOK, out) + p.log.ErrorContext(ctx, "read policies", "kind", kind, "error", err) + return nil, huma.Error500InternalServerError("couldn't read the policies") } - }) + return httpapi.OK(out), nil + } } -func (p *Policies) put(kind string) http.Handler { - return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - var req struct { - Body string `json:"body"` - } - if err := httpjson.Read(r, &req); err != nil { - httpjson.Error(w, http.StatusBadRequest, err.Error()) - return - } - out, err := p.Put(r.Context(), kind, req.Body, bootstrapAdmin) +type policyVersionInput struct { + Version int `query:"version" minimum:"1" doc:"A past version; the current one by default"` +} + +type policyInput struct { + Body struct { + Body string `json:"body" doc:"The whole policy set, as Cedar"` + } +} + +func (p *Policies) put(kind string) func(context.Context, *policyInput) (*httpapi.Reply[PolicySetView], error) { + return func(ctx context.Context, in *policyInput) (*httpapi.Reply[PolicySetView], error) { + out, err := p.Put(ctx, kind, in.Body.Body, bootstrapAdmin) switch { case errors.Is(err, ErrInvalidPolicy): - httpjson.Error(w, http.StatusBadRequest, err.Error()) + return nil, huma.Error400BadRequest(err.Error()) case err != nil: - p.log.ErrorContext(r.Context(), "save policies", "kind", kind, "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't save the policies") - default: - httpjson.Write(w, http.StatusOK, out) + p.log.ErrorContext(ctx, "save policies", "kind", kind, "error", err) + return nil, huma.Error500InternalServerError("couldn't save the policies") } - }) + return httpapi.OK(out), nil + } } diff --git a/modules/runs/trail.go b/modules/runs/trail.go index d3977b880..fff76dea2 100644 --- a/modules/runs/trail.go +++ b/modules/runs/trail.go @@ -9,11 +9,12 @@ import ( "strings" "time" + "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/samcharles93/ai-sdk/agentloop" "github.com/samcharles93/ai-sdk/chat" - "github.com/samcharles93/archie-core/internal/platform/httpjson" + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/approvals" "github.com/samcharles93/archie-core/modules/judgement" "github.com/samcharles93/archie-core/modules/runs/internal/store" @@ -129,11 +130,26 @@ type Approvals interface { ForRun(ctx context.Context, runID uuid.UUID) ([]approvals.Request, error) } -// Routes adds the run API for orgID to mux behind guard. -func (e *Engine) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler, orgID string, origins Origins, decisions Decisions, asked Approvals) { - api := &runAPI{db: e.db, orgID: orgID, origins: origins, decisions: decisions, approvals: asked} - mux.Handle("GET /api/runs", guard(http.HandlerFunc(api.recent))) - mux.Handle("GET /api/runs/{id}", guard(http.HandlerFunc(api.trail))) +// Register adds the run API for orgID: recent runs and each run's trail. +func (e *Engine) Register(api huma.API, orgID string, origins Origins, decisions Decisions, asked Approvals) { + a := &runAPI{db: e.db, orgID: orgID, origins: origins, decisions: decisions, approvals: asked} + tags := []string{"Runs"} + huma.Register(api, huma.Operation{ + OperationID: "list-runs", Method: http.MethodGet, Path: "/api/runs", + Summary: "List recent runs", Tags: tags, + }, a.recent) + huma.Register(api, huma.Operation{ + OperationID: "get-run", Method: http.MethodGet, Path: "/api/runs/{id}", + Summary: "Get a run's decision trail", Tags: tags, + }, a.trail) +} + +type recentRunsInput struct { + Limit int `query:"limit" minimum:"1" maximum:"200" default:"50"` +} + +type runInput struct { + ID string `path:"id" format:"uuid"` } type runAPI struct { @@ -144,65 +160,53 @@ type runAPI struct { approvals Approvals } -func (a *runAPI) recent(w http.ResponseWriter, r *http.Request) { - limit := 50 - if n, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil && n > 0 && n <= 200 { - limit = n - } - runs, err := a.db.Recent(r.Context(), a.orgID, limit) +func (a *runAPI) recent(ctx context.Context, in *recentRunsInput) (*httpapi.Reply[[]RunView], error) { + runs, err := a.db.Recent(ctx, a.orgID, in.Limit) if err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't list runs") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't list runs") } views := make([]RunView, 0, len(runs)) for _, s := range runs { views = append(views, view(s, nil)) } - httpjson.Write(w, http.StatusOK, views) + return httpapi.OK(views), nil } -func (a *runAPI) trail(w http.ResponseWriter, r *http.Request) { - id, err := uuid.Parse(r.PathValue("id")) +func (a *runAPI) trail(ctx context.Context, in *runInput) (*httpapi.Reply[Trail], error) { + id, err := uuid.Parse(in.ID) if err != nil { - httpjson.Error(w, http.StatusBadRequest, "a run id is a UUID") - return + return nil, huma.NewError(http.StatusBadRequest, "a run id is a UUID") } - d, ok, err := a.db.Detail(r.Context(), a.orgID, id) + d, ok, err := a.db.Detail(ctx, a.orgID, id) switch { case err != nil: - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the run") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the run") case !ok: - httpjson.Error(w, http.StatusNotFound, "no such run") - return + return nil, huma.NewError(http.StatusNotFound, "no such run") } - steps, err := a.db.RecordedSteps(r.Context(), id) + steps, err := a.db.RecordedSteps(ctx, id) if err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the run's steps") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the run's steps") } t := Trail{Run: view(d.Summary, d.Result), Entries: make([]TrailEntry, 0, len(steps))} - if o, ok, err := a.origins.Origin(r.Context(), id); err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't read what started the run") - return + if o, ok, err := a.origins.Origin(ctx, id); err != nil { + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read what started the run") } else if ok { t.Origin = &o } for _, s := range steps { t.Entries = append(t.Entries, entry(s)) } - decisions, err := a.decisions.ForRun(r.Context(), id) + decisions, err := a.decisions.ForRun(ctx, id) if err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the run's decisions") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the run's decisions") } - asked, err := a.approvals.ForRun(r.Context(), id) + asked, err := a.approvals.ForRun(ctx, id) if err != nil { - httpjson.Error(w, http.StatusInternalServerError, "couldn't read the run's approvals") - return + return nil, huma.NewError(http.StatusInternalServerError, "couldn't read the run's approvals") } t.Actions = actions(decisions, asked, steps) - httpjson.Write(w, http.StatusOK, t) + return httpapi.OK(t), nil } // actions joins each decision with its approval and its effect. An approved diff --git a/modules/system/system.go b/modules/system/system.go index c6d29bfb6..7e81176ac 100644 --- a/modules/system/system.go +++ b/modules/system/system.go @@ -4,6 +4,7 @@ package system import ( + "context" "crypto/rand" "encoding/hex" "fmt" @@ -11,6 +12,9 @@ import ( "net/http" "sync" + "github.com/danielgtaylor/huma/v2" + + "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/internal/platform/httpjson" ) @@ -39,39 +43,49 @@ func New(b Bootstrap, rotate func(hash string) error, log *slog.Logger) *Module return &Module{bootstrap: b, rotate: rotate, log: log} } -// Routes adds the system API to mux behind guard. -func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) { - mux.Handle("GET /api/system/bootstrap", guard(http.HandlerFunc(m.getBootstrap))) - mux.Handle("POST /api/admin/token", guard(http.HandlerFunc(m.rotateAdminToken))) +// Register adds the system API. +func (m *Module) Register(api huma.API) { + tags := []string{"System"} + huma.Register(api, huma.Operation{ + OperationID: "get-bootstrap", Method: http.MethodGet, Path: "/api/system/bootstrap", + Summary: "Get the bootstrap values, which only the config file sets", Tags: tags, + }, m.getBootstrap) + huma.Register(api, huma.Operation{ + OperationID: "rotate-admin-token", Method: http.MethodPost, Path: "/api/admin/token", + Summary: "Rotate the admin token; the new one is shown once", Tags: tags, + }, m.rotateAdminToken) } -func (m *Module) getBootstrap(w http.ResponseWriter, _ *http.Request) { +// adminToken is a new admin token, returned once. +type adminToken struct { + Token string `json:"token" doc:"Shown once; only its hash is written to the config"` +} + +func (m *Module) getBootstrap(_ context.Context, _ *struct{}) (*httpapi.Reply[Bootstrap], error) { m.mu.RLock() defer m.mu.RUnlock() - httpjson.Write(w, http.StatusOK, m.bootstrap) + return httpapi.OK(m.bootstrap), nil } // rotateAdminToken generates a new token, writes only its hash to the config, // and returns the token once. The old token and the old hash are never read // back or logged. -func (m *Module) rotateAdminToken(w http.ResponseWriter, r *http.Request) { +func (m *Module) rotateAdminToken(ctx context.Context, _ *struct{}) (*httpapi.Reply[adminToken], error) { token, err := newToken() if err != nil { - m.log.ErrorContext(r.Context(), "generate admin token", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't generate a token") - return + m.log.ErrorContext(ctx, "generate admin token", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't generate a token") } hash := httpjson.TokenHash(token) if err := m.rotate(hash); err != nil { - m.log.ErrorContext(r.Context(), "write admin token hash", "error", err) - httpjson.Error(w, http.StatusInternalServerError, "couldn't write the new token hash to the config") - return + m.log.ErrorContext(ctx, "write admin token hash", "error", err) + return nil, huma.NewError(http.StatusInternalServerError, "couldn't write the new token hash to the config") } m.mu.Lock() m.bootstrap.AdminPrefix, m.bootstrap.AdminSet = hash[:8], true m.mu.Unlock() - m.log.InfoContext(r.Context(), "admin token rotated", "audit", true, "action", "admin.token.rotate") - httpjson.Write(w, http.StatusOK, map[string]string{"token": token}) + m.log.InfoContext(ctx, "admin token rotated", "audit", true, "action", "admin.token.rotate") + return httpapi.OK(adminToken{Token: token}), nil } func newToken() (string, error) { diff --git a/ui/src/archie/api.ts b/ui/src/archie/api.ts index 9c6ef54da..f43acd4f7 100644 --- a/ui/src/archie/api.ts +++ b/ui/src/archie/api.ts @@ -22,8 +22,8 @@ async function request(path: string, signal?: AbortSignal): Promise { const res = await fetch(path, { headers: { Authorization: `Bearer ${token()}` }, signal }); if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (!res.ok) { - const body = (await res.json().catch(() => ({}))) as { error?: string }; - throw new ApiError(body.error ?? `${res.status} ${res.statusText}`, res.status); + const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; + throw new ApiError(body.detail ?? body.error ?? `${res.status} ${res.statusText}`, res.status); } return res; } @@ -276,8 +276,8 @@ async function send(method: string, path: string, payload?: unknown): Promise }); if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (!res.ok) { - const body = (await res.json().catch(() => ({}))) as { error?: string }; - throw new ApiError(body.error ?? `${res.status} ${res.statusText}`, res.status); + const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; + throw new ApiError(body.detail ?? body.error ?? `${res.status} ${res.statusText}`, res.status); } return (await res.json().catch(() => undefined)) as T; } @@ -309,8 +309,8 @@ export async function answerApproval(id: string, approved: boolean): Promise ({}))) as { error?: string }; - throw new Error(body.error ?? `${res.status} ${res.statusText}`); + const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; + throw new Error(body.detail ?? body.error ?? `${res.status} ${res.statusText}`); } } export type Level = "act_quietly" | "act_and_tell" | "propose_and_wait" | "escalate" | "never"; @@ -373,8 +373,8 @@ export async function resetClass(id: string): Promise { }); if (res.status === 401) throw new Unauthorized("The admin token was refused."); if (!res.ok) { - const body = (await res.json().catch(() => ({}))) as { error?: string }; - throw new Error(body.error ?? `${res.status} ${res.statusText}`); + const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }; + throw new Error(body.detail ?? body.error ?? `${res.status} ${res.statusText}`); } }