feat(httpapi): the API is described by an OpenAPI document generated with Huma (#2028)

Every /api operation is registered with Huma behind one admin-token
middleware, served at /api/openapi.json with a docs page at /api/docs,
and committed as api/openapi.yaml, which task check keeps current.
This commit is contained in:
sam committed 2026-11-16 20:05:05 +11:00
1 parent ee4c3f9c16
commit 1026d5e3b6
32 files changed
+4467 -1105

No files matched your search

+4 -4
View File
@@ -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.
+13
View File
@@ -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:
+3111
View File
File diff suppressed because it is too large. Load diff
+16
View File
@@ -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()
+1
View File
@@ -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
+2
View File
@@ -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=
+62
View File
@@ -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()
}
+10 -22
View File
@@ -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 {
+79
View File
@@ -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
}
+50
View File
@@ -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)
}
})
}
}
+2 -21
View File
@@ -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)
})
}
@@ -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)
}
})
}
}
+33 -31
View File
@@ -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
+45 -47
View File
@@ -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
+11 -12
View File
@@ -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)
}
+12 -11
View File
@@ -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
}
}
+29 -33
View File
@@ -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.
+84 -50
View File
@@ -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
+16 -19
View File
@@ -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
+19 -9
View File
@@ -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()
}
+65 -49
View File
@@ -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<<attempts)*time.Second, maxBackoff)
}
// Routes adds the composer API to mux behind guard.
func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) {
mux.Handle("GET /api/composer/messages", guard(http.HandlerFunc(m.messages)))
mux.Handle("GET /api/composer/stream", guard(http.HandlerFunc(m.stream)))
// Register adds the composer API.
func (m *Module) Register(api huma.API) {
tags := []string{"Composer"}
huma.Register(api, huma.Operation{
OperationID: "list-composer-messages", Method: http.MethodGet, Path: "/api/composer/messages",
Summary: "List composer messages with their delivery attempts", Tags: tags,
}, m.messages)
huma.Register(api, huma.Operation{
OperationID: "stream-composer", Method: http.MethodGet, Path: "/api/composer/stream",
Summary: "Stream the seq of each new composer message", Tags: tags,
Responses: map[string]*huma.Response{"200": {
Description: "Server-sent events: a message event carrying {\"seq\": n} for each new message, and a keepalive comment while idle",
Content: map[string]*huma.MediaType{"text/event-stream": {Schema: &huma.Schema{Type: huma.TypeString}}},
}},
}, m.stream)
}
type messagesInput struct {
After string `query:"after" doc:"Only messages after this seq; the latest page by default"`
}
// messages returns the newest page, or the messages after ?after=seq.
func (m *Module) messages(w http.ResponseWriter, r *http.Request) {
func (m *Module) messages(ctx context.Context, in *messagesInput) (*httpapi.Reply[[]Message], error) {
var (
rows []store.Message
err error
)
if after := r.URL.Query().Get("after"); after != "" {
seq, perr := strconv.ParseInt(after, 10, 64)
if in.After != "" {
seq, perr := strconv.ParseInt(in.After, 10, 64)
if perr != nil || seq < 0 {
httpjson.Error(w, http.StatusBadRequest, "after is a message seq")
return
return nil, huma.NewError(http.StatusBadRequest, "after is a message seq")
}
rows, err = m.store.After(r.Context(), m.orgID, channelComposer, seq, pageSize)
rows, err = m.store.After(ctx, m.orgID, channelComposer, seq, pageSize)
} else {
rows, err = m.store.Latest(r.Context(), m.orgID, channelComposer, pageSize)
rows, err = m.store.Latest(ctx, m.orgID, channelComposer, pageSize)
}
if err != nil {
m.log.ErrorContext(r.Context(), "list composer messages", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't list messages")
return
m.log.ErrorContext(ctx, "list composer messages", "error", err)
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list messages")
}
keys := make([]string, 0, len(rows))
for _, row := range rows {
keys = append(keys, row.Key)
}
attempts, err := m.store.AttemptsFor(r.Context(), m.orgID, keys)
attempts, err := m.store.AttemptsFor(ctx, m.orgID, keys)
if err != nil {
m.log.ErrorContext(r.Context(), "list delivery attempts", "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't list messages")
return
m.log.ErrorContext(ctx, "list delivery attempts", "error", err)
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list messages")
}
byKey := make(map[string][]Attempt, len(rows))
for _, a := range attempts {
@@ -309,42 +322,45 @@ func (m *Module) messages(w http.ResponseWriter, r *http.Request) {
}
out = append(out, msg)
}
httpjson.Write(w, http.StatusOK, out)
return httpapi.OK(out), nil
}
// stream sends a server-sent event each time a composer message lands. It
// carries only the new seq: the client reads the messages themselves. A
// client that falls behind is cut off and reconnects with its cursor.
func (m *Module) stream(w http.ResponseWriter, r *http.Request) {
flusher, ok := w.(http.Flusher)
if !ok {
httpjson.Error(w, http.StatusInternalServerError, "streaming unsupported")
return
}
notes, stop := m.hub.Subscribe(topicComposer)
defer stop()
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-store")
w.WriteHeader(http.StatusOK)
flusher.Flush()
tick := time.NewTicker(heartbeat)
defer tick.Stop()
for {
select {
case <-r.Context().Done():
func (m *Module) stream(_ context.Context, _ *struct{}) (*huma.StreamResponse, error) {
return &huma.StreamResponse{Body: func(hc huma.Context) {
w := hc.BodyWriter()
flusher, ok := w.(http.Flusher)
if !ok {
hc.SetStatus(http.StatusInternalServerError)
return
case <-tick.C:
if _, err := fmt.Fprint(w, ": keepalive\n\n"); err != nil {
return
}
case n, ok := <-notes:
if !ok {
return
}
if _, err := fmt.Fprintf(w, "event: message\ndata: {\"seq\":%d}\n\n", n.Seq); err != nil {
return
}
}
notes, stop := m.hub.Subscribe(topicComposer)
defer stop()
hc.SetHeader("Content-Type", "text/event-stream")
hc.SetHeader("Cache-Control", "no-store")
hc.SetStatus(http.StatusOK)
flusher.Flush()
}
tick := time.NewTicker(heartbeat)
defer tick.Stop()
for {
select {
case <-hc.Context().Done():
return
case <-tick.C:
if _, err := fmt.Fprint(w, ": keepalive\n\n"); err != nil {
return
}
case n, ok := <-notes:
if !ok {
return
}
if _, err := fmt.Fprintf(w, "event: message\ndata: {\"seq\":%d}\n\n", n.Seq); err != nil {
return
}
}
flusher.Flush()
}
}}, nil
}
+147 -162
View File
@@ -10,7 +10,6 @@ import (
json "encoding/json/v2"
"errors"
"fmt"
"io"
"log/slog"
"net/http"
"regexp"
@@ -18,10 +17,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/drafts/internal/store"
"github.com/samcharles93/archie-core/modules/events"
"github.com/samcharles93/archie-core/modules/judgement"
@@ -69,14 +69,37 @@ func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, g Groups, w Workflow
return &Module{orgID: orgID, store: store.New(db), groups: g, workflows: w, policies: p, log: log}
}
// Routes adds the draft API behind guard.
func (m *Module) Routes(mux *http.ServeMux, guard func(http.Handler) http.Handler) {
mux.Handle("GET /api/drafts", guard(http.HandlerFunc(m.list)))
mux.Handle("POST /api/groups/{id}/draft", guard(http.HandlerFunc(m.create)))
mux.Handle("GET /api/drafts/{id}", guard(http.HandlerFunc(m.get)))
mux.Handle("PUT /api/drafts/{id}", guard(http.HandlerFunc(m.edit)))
mux.Handle("POST /api/drafts/{id}/dry-run", guard(http.HandlerFunc(m.dryRun)))
mux.Handle("POST /api/drafts/{id}/publish", guard(http.HandlerFunc(m.publish)))
// Register adds the draft API.
func (m *Module) Register(api huma.API) {
tags := []string{"Drafts"}
huma.Register(api, huma.Operation{
OperationID: "list-drafts", Method: http.MethodGet, Path: "/api/drafts",
Summary: "List drafts", Tags: tags,
}, m.list)
huma.Register(api, huma.Operation{
OperationID: "draft-group", Method: http.MethodPost, Path: "/api/groups/{id}/draft",
Summary: "Draft a trigger and workflow for a group of unmatched events", Tags: tags,
}, m.create)
huma.Register(api, huma.Operation{
OperationID: "get-draft", Method: http.MethodGet, Path: "/api/drafts/{id}",
Summary: "Get a draft", Tags: tags,
}, m.get)
huma.Register(api, huma.Operation{
OperationID: "edit-draft", Method: http.MethodPut, Path: "/api/drafts/{id}",
Summary: "Change a draft's name, workflow and policy", Tags: tags,
}, m.edit)
huma.Register(api, huma.Operation{
OperationID: "dry-run-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/dry-run",
Summary: "Replay one of the group's events through the draft, changing nothing", Tags: tags,
}, m.dryRun)
huma.Register(api, huma.Operation{
OperationID: "publish-draft", Method: http.MethodPost, Path: "/api/drafts/{id}/publish",
Summary: "Install the draft's workflow, policy and trigger", Tags: tags,
}, m.publish)
}
type idInput struct {
ID string `path:"id" format:"uuid"`
}
// View is a draft as the API returns it.
@@ -183,105 +206,93 @@ func defaultName(g events.Group) string {
return slug + "-" + g.ID.String()[:6]
}
func (m *Module) list(w http.ResponseWriter, r *http.Request) {
rows, err := m.store.List(r.Context(), m.orgID)
func (m *Module) list(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]View], error) {
rows, err := m.store.List(ctx, m.orgID)
if err != nil {
m.fail(w, r, "list drafts", err)
return
return nil, m.fail(ctx, "list drafts", err)
}
out := make([]View, 0, len(rows))
for _, d := range rows {
v, err := m.view(r.Context(), d)
v, err := m.view(ctx, d)
if err != nil {
m.fail(w, r, "read draft", err)
return
return nil, m.fail(ctx, "read draft", err)
}
out = append(out, v)
}
httpjson.Write(w, http.StatusOK, out)
return httpapi.OK(out), nil
}
// create makes a group's draft, or returns the one it has. A new draft
// proposes the group's trigger and a copy of the investigate workflow.
func (m *Module) create(w http.ResponseWriter, r *http.Request) {
id, ok := pathID(w, r)
if !ok {
return
func (m *Module) create(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.Error400BadRequest("an id is a UUID")
}
g, found, err := m.groups.Group(r.Context(), id)
g, found, err := m.groups.Group(ctx, id)
switch {
case err != nil:
m.fail(w, r, "read group", err)
return
return nil, m.fail(ctx, "read group", err)
case !found:
httpjson.Error(w, http.StatusNotFound, "no such group")
return
return nil, huma.Error404NotFound("no such group")
}
filter, err := json.Marshal(g.Filter)
if err != nil {
m.fail(w, r, "encode filter", err)
return
return nil, m.fail(ctx, "encode filter", err)
}
d, err := m.store.Create(r.Context(), store.Draft{
d, err := m.store.Create(ctx, store.Draft{
ID: uuid.New(), OrgID: m.orgID, GroupID: g.ID, Name: defaultName(g), Source: g.Source, EventType: g.EventType,
Filter: filter, Document: runs.InvestigateDocument(), PolicyKind: judgement.KindHardRules,
})
if err != nil {
m.fail(w, r, "create draft", err)
return
return nil, m.fail(ctx, "create draft", err)
}
m.respond(w, r, d)
return m.respond(ctx, d)
}
func (m *Module) get(w http.ResponseWriter, r *http.Request) {
d, ok := m.draft(w, r)
if !ok {
return
func (m *Module) get(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
m.respond(w, r, d)
return m.respond(ctx, d)
}
type editRequest struct {
Name string `json:"name"`
Workflow string `json:"workflow"`
PolicyKind string `json:"policy_kind"`
Policy string `json:"policy"`
type editInput struct {
ID string `path:"id" format:"uuid"`
Body struct {
Name string `json:"name"`
Workflow string `json:"workflow" doc:"The workflow document"`
PolicyKind string `json:"policy_kind" enum:"hard_rules,change_request"`
Policy string `json:"policy,omitzero" doc:"Cedar policy text added when the draft is published"`
}
}
// edit replaces a draft's name, workflow and policy after checking them. What
// doesn't validate changes nothing.
func (m *Module) edit(w http.ResponseWriter, r *http.Request) {
d, ok := m.draft(w, r)
if !ok {
return
func (m *Module) edit(ctx context.Context, in *editInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
if d.PublishedAt.Valid {
httpjson.Error(w, http.StatusConflict, "a published draft can't be edited")
return
return nil, huma.Error409Conflict("a published draft can't be edited")
}
var req editRequest
if err := httpjson.Read(r, &req); err != nil {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
req := in.Body
if err := m.check(ctx, req.Name, req.Workflow, req.PolicyKind, req.Policy); err != nil {
return nil, invalid(err)
}
if err := m.check(r.Context(), req.Name, req.Workflow, req.PolicyKind, req.Policy); err != nil {
writeInvalid(w, err)
return
}
switch err := m.store.Edit(r.Context(), m.orgID, d.ID, req.Name, req.Workflow, req.PolicyKind, req.Policy); {
switch err := m.store.Edit(ctx, m.orgID, d.ID, req.Name, req.Workflow, req.PolicyKind, req.Policy); {
case errors.Is(err, store.ErrTaken):
httpjson.Error(w, http.StatusConflict, "another draft has that name")
return
return nil, huma.Error409Conflict("another draft has that name")
case err != nil:
m.fail(w, r, "edit draft", err)
return
return nil, m.fail(ctx, "edit draft", err)
}
d, err := m.store.ByID(r.Context(), m.orgID, d.ID)
d, err = m.store.ByID(ctx, m.orgID, d.ID)
if err != nil {
m.fail(w, r, "read draft", err)
return
return nil, m.fail(ctx, "read draft", err)
}
m.respond(w, r, d)
return m.respond(ctx, d)
}
// check validates what a draft would put in force.
@@ -301,71 +312,68 @@ func (m *Module) check(ctx context.Context, name, document, policyKind, policy s
return m.policies.Check(ctx, policyKind, policy)
}
func writeInvalid(w http.ResponseWriter, err error) {
var invalid *runs.InvalidError
func invalid(err error) error {
var problem *runs.InvalidError
switch {
case errors.As(err, &invalid):
httpjson.Write(w, http.StatusBadRequest, map[string]any{"error": invalid.Error(), "problems": invalid.Problems})
case errors.As(err, &problem):
details := make([]error, 0, len(problem.Problems))
for _, p := range problem.Problems {
details = append(details, &huma.ErrorDetail{Location: p.Path, Message: p.Message})
}
return huma.Error400BadRequest(problem.Error(), details...)
case errors.Is(err, judgement.ErrInvalidPolicy):
httpjson.Write(w, http.StatusBadRequest, map[string]any{
"error": err.Error(), "problems": []runs.Problem{{Path: "policy", Message: err.Error()}},
})
return huma.Error400BadRequest(err.Error(), &huma.ErrorDetail{Location: "policy", Message: err.Error()})
default:
httpjson.Error(w, http.StatusInternalServerError, "couldn't check the draft")
return huma.Error500InternalServerError("couldn't check the draft")
}
}
type dryRunRequest struct {
EventID uuid.UUID `json:"event_id"`
type dryRunInput struct {
ID string `path:"id" format:"uuid"`
Body *struct {
EventID uuid.UUID `json:"event_id,omitzero" doc:"The stored event to replay; the newest by default"`
}
}
// dryRun replays one of the group's stored events through the draft's workflow
// in dry mode: the newest by default.
func (m *Module) dryRun(w http.ResponseWriter, r *http.Request) {
d, ok := m.draft(w, r)
if !ok {
return
}
var req dryRunRequest
if err := httpjson.Read(r, &req); err != nil && !errors.Is(err, io.EOF) {
httpjson.Error(w, http.StatusBadRequest, err.Error())
return
}
if err := m.check(r.Context(), d.Name, d.Document, d.PolicyKind, d.Policy); err != nil {
writeInvalid(w, err)
return
}
stored, err := m.groups.GroupEvents(r.Context(), d.GroupID, replayable)
func (m *Module) dryRun(ctx context.Context, in *dryRunInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
m.fail(w, r, "read the group's events", err)
return
return nil, err
}
event, found := pick(stored, req.EventID)
var eventID uuid.UUID
if in.Body != nil {
eventID = in.Body.EventID
}
if err := m.check(ctx, d.Name, d.Document, d.PolicyKind, d.Policy); err != nil {
return nil, invalid(err)
}
stored, err := m.groups.GroupEvents(ctx, d.GroupID, replayable)
if err != nil {
return nil, m.fail(ctx, "read the group's events", err)
}
event, found := pick(stored, eventID)
if !found {
httpjson.Error(w, http.StatusConflict, "the group has no stored event to replay")
return
return nil, huma.Error409Conflict("the group has no stored event to replay")
}
runID, err := m.workflows.StartDry(r.Context(), runs.DryRequest{
runID, err := m.workflows.StartDry(ctx, runs.DryRequest{
OrgID: m.orgID, Workflow: d.Name, Document: d.Document, PolicyKind: d.PolicyKind, Policy: d.Policy, Input: event.Input,
})
if err != nil {
m.fail(w, r, "start the dry run", err)
return
return nil, m.fail(ctx, "start the dry run", err)
}
if err := m.groups.Replayed(r.Context(), event.ID, d.Name, runID); err != nil {
m.fail(w, r, "record the replay", err)
return
if err := m.groups.Replayed(ctx, event.ID, d.Name, runID); err != nil {
return nil, m.fail(ctx, "record the replay", err)
}
if err := m.store.SetDryRun(r.Context(), m.orgID, d.ID, runID, event.ID); err != nil {
m.fail(w, r, "record the dry run", err)
return
if err := m.store.SetDryRun(ctx, m.orgID, d.ID, runID, event.ID); err != nil {
return nil, m.fail(ctx, "record the dry run", err)
}
d, err = m.store.ByID(r.Context(), m.orgID, d.ID)
d, err = m.store.ByID(ctx, m.orgID, d.ID)
if err != nil {
m.fail(w, r, "read draft", err)
return
return nil, m.fail(ctx, "read draft", err)
}
m.respond(w, r, d)
return m.respond(ctx, d)
}
// pick returns the event asked for, or the newest when none is.
@@ -382,102 +390,79 @@ func pick(stored []events.Stored, id uuid.UUID) (events.Stored, bool) {
// is installed as the next version, and last its trigger is saved, so nothing
// fires before the rules that govern it exist. A retry after a failure carries
// on from where it stopped.
func (m *Module) publish(w http.ResponseWriter, r *http.Request) {
d, ok := m.draft(w, r)
if !ok {
return
func (m *Module) publish(ctx context.Context, in *idInput) (*httpapi.Reply[View], error) {
d, err := m.draft(ctx, in.ID)
if err != nil {
return nil, err
}
ctx := r.Context()
if err := m.check(ctx, d.Name, d.Document, d.PolicyKind, d.Policy); err != nil {
writeInvalid(w, err)
return
return nil, invalid(err)
}
if !d.InstalledVersion.Valid {
taken, err := m.workflows.Has(ctx, m.orgID, d.Name)
if err != nil {
m.fail(w, r, "check the workflow name", err)
return
return nil, m.fail(ctx, "check the workflow name", err)
}
if taken {
httpjson.Error(w, http.StatusConflict, "a workflow named "+d.Name+" already exists; rename the draft")
return
return nil, huma.Error409Conflict("a workflow named " + d.Name + " already exists; rename the draft")
}
}
by := "draft:" + d.Name
if strings.TrimSpace(d.Policy) != "" {
if _, err := m.policies.Append(ctx, d.PolicyKind, d.Policy, by); err != nil {
m.fail(w, r, "add the policy", err)
return
return nil, m.fail(ctx, "add the policy", err)
}
}
version, err := m.workflows.Install(ctx, m.orgID, d.Name, d.Document, by)
if err != nil {
m.fail(w, r, "install the workflow", err)
return
return nil, m.fail(ctx, "install the workflow", err)
}
if err := m.store.MarkInstalled(ctx, m.orgID, d.ID, version); err != nil {
m.fail(w, r, "record the workflow version", err)
return
return nil, m.fail(ctx, "record the workflow version", err)
}
var filter map[string]string
if err := json.Unmarshal(d.Filter, &filter); err != nil {
m.fail(w, r, "read the trigger filter", err)
return
return nil, m.fail(ctx, "read the trigger filter", err)
}
if err := m.groups.SaveTrigger(ctx, events.TriggerSpec{
Name: d.Name, Source: d.Source, EventType: d.EventType, Filter: filter, Workflow: d.Name,
}); err != nil {
m.fail(w, r, "save the trigger", err)
return
return nil, m.fail(ctx, "save the trigger", err)
}
if err := m.store.MarkPublished(ctx, m.orgID, d.ID); err != nil {
m.fail(w, r, "mark the draft published", err)
return
return nil, m.fail(ctx, "mark the draft published", err)
}
d, err = m.store.ByID(ctx, m.orgID, d.ID)
if err != nil {
m.fail(w, r, "read draft", err)
return
return nil, m.fail(ctx, "read draft", err)
}
m.respond(w, r, d)
return m.respond(ctx, d)
}
func (m *Module) draft(w http.ResponseWriter, r *http.Request) (store.Draft, bool) {
id, ok := pathID(w, r)
if !ok {
return store.Draft{}, false
func (m *Module) draft(ctx context.Context, rawID string) (store.Draft, error) {
id, err := uuid.Parse(rawID)
if err != nil {
return store.Draft{}, huma.Error400BadRequest("an id is a UUID")
}
d, err := m.store.ByID(r.Context(), m.orgID, id)
d, err := m.store.ByID(ctx, m.orgID, id)
switch {
case errors.Is(err, store.ErrNotFound):
httpjson.Error(w, http.StatusNotFound, "no such draft")
return store.Draft{}, false
return store.Draft{}, huma.Error404NotFound("no such draft")
case err != nil:
m.fail(w, r, "read draft", err)
return store.Draft{}, false
return store.Draft{}, m.fail(ctx, "read draft", err)
}
return d, true
return d, nil
}
func (m *Module) respond(w http.ResponseWriter, r *http.Request, d store.Draft) {
v, err := m.view(r.Context(), d)
func (m *Module) respond(ctx context.Context, d store.Draft) (*httpapi.Reply[View], error) {
v, err := m.view(ctx, d)
if err != nil {
m.fail(w, r, "read draft", err)
return
return nil, m.fail(ctx, "read draft", err)
}
httpjson.Write(w, http.StatusOK, v)
return httpapi.OK(v), nil
}
func (m *Module) fail(w http.ResponseWriter, r *http.Request, what string, err error) {
m.log.ErrorContext(r.Context(), what, "error", err)
httpjson.Error(w, http.StatusInternalServerError, "couldn't "+what)
}
func pathID(w http.ResponseWriter, r *http.Request) (uuid.UUID, bool) {
id, err := uuid.Parse(r.PathValue("id"))
if err != nil {
httpjson.Error(w, http.StatusBadRequest, "an id is a UUID")
return uuid.Nil, false
}
return id, true
func (m *Module) fail(ctx context.Context, what string, err error) error {
m.log.ErrorContext(ctx, what, "error", err)
return huma.Error500InternalServerError("couldn't " + what)
}
+361
View File
@@ -0,0 +1,361 @@
package events
import (
"context"
"database/sql"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"net/http"
"strconv"
"time"
"github.com/danielgtaylor/huma/v2"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
"github.com/samcharles93/archie-core/modules/events/internal/store"
)
// Register adds the events API: sources, triggers, groups of unmatched events
// and the events themselves.
func (m *Module) Register(api huma.API) {
tags := []string{"Events"}
huma.Register(api, huma.Operation{
OperationID: "list-sources", Method: http.MethodGet, Path: "/api/sources",
Summary: "List sources", Tags: tags,
}, m.sources)
huma.Register(api, huma.Operation{
OperationID: "put-source", Method: http.MethodPut, Path: "/api/sources/{name}",
Summary: "Add a source or rotate its token", Tags: tags,
}, m.putSource)
huma.Register(api, huma.Operation{
OperationID: "put-source-key-fields", Method: http.MethodPut, Path: "/api/sources/{name}/key-fields",
Summary: "Set the fields a source's events are grouped by", Tags: tags,
}, m.putKeyFields)
huma.Register(api, huma.Operation{
OperationID: "list-triggers", Method: http.MethodGet, Path: "/api/triggers",
Summary: "List triggers", Tags: tags,
}, m.triggers)
huma.Register(api, huma.Operation{
OperationID: "put-trigger", Method: http.MethodPut, Path: "/api/triggers/{name}",
Summary: "Add or change a trigger", Tags: tags,
}, m.putTrigger)
huma.Register(api, huma.Operation{
OperationID: "list-groups", Method: http.MethodGet, Path: "/api/groups",
Summary: "List groups of unmatched events", Tags: tags,
}, m.groups)
huma.Register(api, huma.Operation{
OperationID: "list-events", Method: http.MethodGet, Path: "/api/events",
Summary: "List recent events", Tags: tags,
}, m.recent)
huma.Register(api, huma.Operation{
OperationID: "get-event", Method: http.MethodGet, Path: "/api/events/{id}",
Summary: "Get an event with its payload and the runs it started", Tags: tags,
}, m.event)
}
type putSourceInput struct {
Name string `path:"name" doc:"Lowercase letters, digits and hyphens; the webhook URL ends in it"`
Body struct {
Connector string `json:"connector" doc:"The connector that parses this source's events"`
}
}
type sourceCreated struct {
Source string `json:"source"`
Token string `json:"token" doc:"Shown once; only its hash is stored"`
URL string `json:"url" doc:"Where the sender posts its events"`
}
// putSource creates a source or rotates its token. The token is returned once
// and stored only as its hash.
func (m *Module) putSource(ctx context.Context, in *putSourceInput) (*httpapi.Reply[sourceCreated], error) {
if !validName.MatchString(in.Name) || !validName.MatchString(in.Body.Connector) {
return nil, huma.Error400BadRequest("a source needs a lowercase name and a connector")
}
token, err := newToken()
if err != nil {
return nil, huma.Error500InternalServerError("couldn't make a token", err)
}
if err := m.store.UpsertSource(ctx, store.Source{
OrgID: m.orgID, Name: in.Name, Connector: in.Body.Connector, TokenSHA256: httpjson.TokenHash(token),
}); err != nil {
return nil, huma.Error500InternalServerError("couldn't save the source", err)
}
return httpapi.OK(sourceCreated{Source: in.Name, Token: token, URL: "/hooks/" + in.Name}), nil
}
type putTriggerInput struct {
Name string `path:"name" doc:"Lowercase letters, digits and hyphens"`
Body struct {
Source string `json:"source,omitzero" doc:"The source whose events fire it; fixed when every is set"`
EventType string `json:"event_type,omitzero" doc:"The event type that fires it; fixed when every is set"`
Filter map[string]string `json:"filter,omitzero" doc:"Event fields that must match exactly"`
Workflow string `json:"workflow" doc:"The workflow each match runs"`
Disabled bool `json:"disabled,omitzero"`
Every string `json:"every,omitzero" doc:"Fire on an interval instead of on events, such as 1h" example:"1h"`
}
}
type triggerSaved struct {
Trigger string `json:"trigger"`
}
func (m *Module) putTrigger(ctx context.Context, in *putTriggerInput) (*httpapi.Reply[triggerSaved], error) {
req := in.Body
var every sql.NullInt64
if req.Every != "" {
d, err := time.ParseDuration(req.Every)
if err != nil || d < minInterval || d%time.Second != 0 {
return nil, huma.Error400BadRequest("every is a whole number of seconds of at least one minute, such as 1h")
}
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": in.Name}
}
if !validName.MatchString(in.Name) || req.Source == "" || req.EventType == "" || req.Workflow == "" {
return nil, huma.Error400BadRequest("a trigger needs a lowercase name, a workflow, and either a source and event type or an every interval")
}
filter, err := json.Marshal(req.Filter)
if err != nil {
return nil, huma.Error400BadRequest(err.Error())
}
if err := m.store.UpsertTrigger(ctx, store.Trigger{
OrgID: m.orgID, Name: in.Name, Source: req.Source, EventType: req.EventType,
Filter: filter, Workflow: req.Workflow, Enabled: !req.Disabled, ScheduleEverySeconds: every,
}); err != nil {
return nil, huma.Error500InternalServerError("couldn't save the trigger", err)
}
return httpapi.OK(triggerSaved{Trigger: in.Name}), nil
}
type putKeyFieldsInput struct {
Name string `path:"name"`
Body struct {
Paths []string `json:"paths,omitzero" doc:"Paths into the event's fields; none uses the connector's default"`
}
}
type keyFieldsSaved struct {
KeyFields []string `json:"key_fields"`
}
// putKeyFields sets the fields a source's events are grouped by. It applies to
// events that arrive after it.
func (m *Module) putKeyFields(ctx context.Context, in *putKeyFieldsInput) (*httpapi.Reply[keyFieldsSaved], error) {
paths := in.Body.Paths
if paths == nil {
paths = []string{}
}
raw, err := json.Marshal(paths)
if err != nil {
return nil, huma.Error400BadRequest(err.Error())
}
err = m.store.SetKeyFields(ctx, m.orgID, in.Name, raw)
if errors.Is(err, store.ErrNotFound) {
return nil, huma.Error404NotFound("no such source")
}
if err != nil {
return nil, huma.Error500InternalServerError("couldn't save the key fields", err)
}
return httpapi.OK(keyFieldsSaved{KeyFields: paths}), nil
}
// 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(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]groupView], error) {
groups, err := m.store.Groups(ctx, m.orgID, 200)
if err != nil {
m.log.ErrorContext(ctx, "list groups", "error", err)
return nil, huma.Error500InternalServerError("couldn't list groups")
}
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},
})
}
return httpapi.OK(out), nil
}
// 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(ctx context.Context, _ *struct{}) (*httpapi.Reply[[]sourceView], error) {
sources, err := m.store.Sources(ctx, m.orgID)
if err != nil {
m.log.ErrorContext(ctx, "list sources", "error", err)
return nil, huma.Error500InternalServerError("couldn't list sources")
}
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(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
}
+3 -331
View File
@@ -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 {
+83 -80
View File
@@ -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) {
+19 -27
View File
@@ -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.
+55 -47
View File
@@ -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")
}
+14 -10
View File
@@ -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
}
+43 -40
View File
@@ -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
}
}
+41 -37
View File
@@ -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
+29 -15
View File
@@ -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) {
+8 -8
View File
@@ -22,8 +22,8 @@ async function request(path: string, signal?: AbortSignal): Promise<Response> {
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<T>(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<voi
});
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}`);
}
}
export type Level = "act_quietly" | "act_and_tell" | "propose_and_wait" | "escalate" | "never";
@@ -373,8 +373,8 @@ export async function resetClass(id: string): Promise<void> {
});
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}`);
}
}