phase 2 (part 1): OpenAPI-generated API server, first 9 endpoints

- api/openapi.yaml converted 3.1 → 3.0.3 (oapi-codegen/kin-openapi supports 3.0; nullable syntax + example keywords), still redocly-clean - oapi-codegen (v2.4.1, strict server + chi) generates internal/httpapi/gen from the spec; `make generate` wired - internal/httpapi: chi router, /healthz (unauthenticated, SG18), RFC 9457 problem+json mapping from domain sentinels (SG11), 5xx detail logged server-side only, request logging with request IDs, graceful shutdown (SG4), interim static bearer auth (constant-time; dev-open when no token; OIDC JWT still to come in Phase 2) - Implemented: listEntities (type filter walks the hierarchy, keyset pagination), getEntity (UUID or slug, ETag), getEntityRelations, getBlastRadius, getGraph (nodes+edges for UIs), getOntology, listSignals, getFleetHealth, exportSeeds. Remaining 38 ops return 501 problem+json stubs (compiler-enforced interface completeness) - `oikos api` role live: migrate-on-start, serves :8090 - 15 API integration tests (auth, pagination, hierarchy filter, ETag, 404/501 problem shapes, graph, export) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-07 08:25:19 +02:00
parent 1b04683639
commit f2fe812cda
13 changed files with 10888 additions and 807 deletions
--- a/internal/httpapi/impl.go
+++ b/internal/httpapi/impl.go
@@ -0,0 +1,517 @@
+package httpapi
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"time"
+
+	"github.com/dtoro/oikos/internal/db"
+	"github.com/dtoro/oikos/internal/domain"
+	"github.com/dtoro/oikos/internal/httpapi/gen"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+const (
+	defaultLimit = 50
+	maxLimit     = 200
+	graphNodeCap = 500
+)
+
+func clampLimit(l *int) int {
+	if l == nil {
+		return defaultLimit
+	}
+	if *l < 1 {
+		return 1
+	}
+	if *l > maxLimit {
+		return maxLimit
+	}
+	return *l
+}
+
+// resolveEntityID resolves a UUID-or-slug path/query value to the entity UUID.
+func (s *Server) resolveEntityID(ctx context.Context, idOrSlug string) (uuid.UUID, error) {
+	if id, err := uuid.Parse(idOrSlug); err == nil {
+		var found uuid.UUID
+		err := s.pool.QueryRow(ctx, "SELECT id FROM entities WHERE id = $1", id).Scan(&found)
+		if err == pgx.ErrNoRows {
+			return uuid.Nil, fmt.Errorf("%w: %s", domain.ErrNotFound, idOrSlug)
+		}
+		return found, err
+	}
+	var id uuid.UUID
+	err := s.pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", idOrSlug).Scan(&id)
+	if err == pgx.ErrNoRows {
+		return uuid.Nil, fmt.Errorf("%w: %s", domain.ErrNotFound, idOrSlug)
+	}
+	return id, err
+}
+
+// entityCols requires the entities table to be aliased as `e`.
+const entityCols = `e.id, e.slug, e.type, e.name, e.state, e.attributes,
+                    e.maintenance_until, e.version, e.created_at, e.updated_at`
+
+func scanEntity(row pgx.Row) (gen.Entity, error) {
+	var e gen.Entity
+	var state *string
+	var attrsJSON []byte
+	var maint *time.Time
+	err := row.Scan(&e.Id, &e.Slug, &e.Type, &e.Name, &state, &attrsJSON,
+		&maint, &e.Version, &e.CreatedAt, &e.UpdatedAt)
+	if err != nil {
+		return e, err
+	}
+	e.State = state
+	e.MaintenanceUntil = maint
+	var attrs map[string]any
+	if len(attrsJSON) > 0 && json.Unmarshal(attrsJSON, &attrs) == nil && len(attrs) > 0 {
+		e.Attributes = &attrs
+	}
+	return e, nil
+}
+
+// ─── Entities ─────────────────────────────────────────────────────────
+
+func (s *Server) ListEntities(ctx context.Context, req gen.ListEntitiesRequestObject) (gen.ListEntitiesResponseObject, error) {
+	limit := clampLimit(req.Params.Limit)
+
+	// Type filter includes descendants via the parent hierarchy (R3-1).
+	query := `
+		WITH RECURSIVE tt AS (
+			SELECT name FROM entity_types WHERE $1::text IS NULL OR name = $1
+			UNION
+			SELECT et.name FROM entity_types et JOIN tt ON et.parent_type = tt.name
+			WHERE $1::text IS NOT NULL
+		)
+		SELECT ` + entityCols + ` FROM entities e
+		JOIN entity_types et ON et.name = e.type
+		WHERE e.type IN (SELECT name FROM tt)
+		  AND ($2::text IS NULL OR e.state = $2)
+		  AND ($3::text IS NULL OR et.domain = $3)
+		  AND ($4::text IS NULL OR et.layer = $4)
+		  AND ($5::text IS NULL OR e.slug ILIKE '%'||$5||'%' OR e.name ILIKE '%'||$5||'%')
+		  AND ($6::text IS NULL OR e.slug > $6)
+		ORDER BY e.slug
+		LIMIT $7`
+
+	rows, err := s.pool.Query(ctx, query,
+		req.Params.Type, req.Params.State, req.Params.Domain, req.Params.Layer,
+		req.Params.Q, req.Params.Cursor, limit+1)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var items []gen.Entity
+	for rows.Next() {
+		e, err := scanEntity(rows)
+		if err != nil {
+			return nil, err
+		}
+		items = append(items, e)
+	}
+	if rows.Err() != nil {
+		return nil, rows.Err()
+	}
+
+	var next *string
+	if len(items) > limit {
+		items = items[:limit]
+		next = &items[len(items)-1].Slug
+	}
+	if items == nil {
+		items = []gen.Entity{}
+	}
+	return gen.ListEntities200JSONResponse{Items: items, NextCursor: next}, nil
+}
+
+func (s *Server) GetEntity(ctx context.Context, req gen.GetEntityRequestObject) (gen.GetEntityResponseObject, error) {
+	id, err := s.resolveEntityID(ctx, req.Id)
+	if err != nil {
+		return nil, err
+	}
+	e, err := scanEntity(s.pool.QueryRow(ctx,
+		"SELECT "+entityCols+" FROM entities e WHERE e.id = $1", id))
+	if err != nil {
+		return nil, err
+	}
+	return gen.GetEntity200JSONResponse{
+		Body:    e,
+		Headers: gen.GetEntity200ResponseHeaders{ETag: `"` + strconv.Itoa(e.Version) + `"`},
+	}, nil
+}
+
+func (s *Server) GetEntityRelations(ctx context.Context, req gen.GetEntityRelationsRequestObject) (gen.GetEntityRelationsResponseObject, error) {
+	id, err := s.resolveEntityID(ctx, req.Id)
+	if err != nil {
+		return nil, err
+	}
+	dir := "both"
+	if req.Params.Direction != nil {
+		dir = string(*req.Params.Direction)
+	}
+	rows, err := s.pool.Query(ctx, `
+		SELECT se.slug, te.slug, r.type, r.attributes, r.valid_from, r.valid_to
+		FROM relationships r
+		JOIN entities se ON se.id = r.source_id
+		JOIN entities te ON te.id = r.target_id
+		WHERE r.valid_to IS NULL
+		  AND (($3 IN ('out','both') AND r.source_id = $1)
+		    OR ($3 IN ('in','both')  AND r.target_id = $1))
+		  AND ($2::text IS NULL OR r.type = $2)
+		ORDER BY r.type, se.slug, te.slug`,
+		id, req.Params.RelType, dir)
+	if err != nil {
+		return nil, err
+	}
+	items, err := scanRelationships(rows)
+	if err != nil {
+		return nil, err
+	}
+	return gen.GetEntityRelations200JSONResponse{Items: items}, nil
+}
+
+func scanRelationships(rows pgx.Rows) ([]gen.Relationship, error) {
+	defer rows.Close()
+	items := []gen.Relationship{}
+	for rows.Next() {
+		var rel gen.Relationship
+		var attrsJSON []byte
+		if err := rows.Scan(&rel.Source, &rel.Target, &rel.Type,
+			&attrsJSON, &rel.ValidFrom, &rel.ValidTo); err != nil {
+			return nil, err
+		}
+		var attrs map[string]any
+		if len(attrsJSON) > 0 && json.Unmarshal(attrsJSON, &attrs) == nil && len(attrs) > 0 {
+			rel.Attributes = &attrs
+		}
+		items = append(items, rel)
+	}
+	return items, rows.Err()
+}
+
+func (s *Server) GetBlastRadius(ctx context.Context, req gen.GetBlastRadiusRequestObject) (gen.GetBlastRadiusResponseObject, error) {
+	id, err := s.resolveEntityID(ctx, req.Id)
+	if err != nil {
+		return nil, err
+	}
+	depth := 3
+	if req.Params.Depth != nil {
+		depth = *req.Params.Depth
+	}
+	rows, err := s.pool.Query(ctx, `
+		SELECT `+entityCols+`, b.depth
+		FROM blast_radius($1, $2) b
+		JOIN entities e ON e.id = b.entity_id
+		ORDER BY b.depth, e.slug`, id, depth)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	resp := gen.GetBlastRadius200JSONResponse{Items: []struct {
+		Depth  int        `json:"depth"`
+		Entity gen.Entity `json:"entity"`
+	}{}}
+	for rows.Next() {
+		var e gen.Entity
+		var state *string
+		var attrsJSON []byte
+		var maint *time.Time
+		var d int
+		if err := rows.Scan(&e.Id, &e.Slug, &e.Type, &e.Name, &state, &attrsJSON,
+			&maint, &e.Version, &e.CreatedAt, &e.UpdatedAt, &d); err != nil {
+			return nil, err
+		}
+		e.State = state
+		e.MaintenanceUntil = maint
+		var attrs map[string]any
+		if len(attrsJSON) > 0 && json.Unmarshal(attrsJSON, &attrs) == nil && len(attrs) > 0 {
+			e.Attributes = &attrs
+		}
+		resp.Items = append(resp.Items, struct {
+			Depth  int        `json:"depth"`
+			Entity gen.Entity `json:"entity"`
+		}{Depth: d, Entity: e})
+	}
+	return resp, rows.Err()
+}
+
+func (s *Server) GetGraph(ctx context.Context, req gen.GetGraphRequestObject) (gen.GetGraphResponseObject, error) {
+	depth := 2
+	if req.Params.Depth != nil {
+		depth = *req.Params.Depth
+	}
+
+	var nodes []gen.Entity
+	var err error
+	truncated := false
+
+	if req.Params.Root != nil && *req.Params.Root != "" {
+		rootID, rerr := s.resolveEntityID(ctx, *req.Params.Root)
+		if rerr != nil {
+			return nil, rerr
+		}
+		nodes, err = s.queryEntities(ctx, `
+			SELECT `+entityCols+`
+			FROM blast_radius($1, $2, $3) b JOIN entities e ON e.id = b.entity_id
+			ORDER BY e.slug`, rootID, depth, req.Params.RelType)
+	} else {
+		nodes, err = s.queryEntities(ctx, `
+			SELECT `+entityCols+` FROM entities e ORDER BY e.slug LIMIT $1`,
+			graphNodeCap+1)
+		if err == nil && len(nodes) > graphNodeCap {
+			nodes = nodes[:graphNodeCap]
+			truncated = true
+		}
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	ids := make([]uuid.UUID, len(nodes))
+	for i, n := range nodes {
+		ids[i] = uuid.UUID(n.Id)
+	}
+	rows, err := s.pool.Query(ctx, `
+		SELECT se.slug, te.slug, r.type, r.attributes, r.valid_from, r.valid_to
+		FROM relationships r
+		JOIN entities se ON se.id = r.source_id
+		JOIN entities te ON te.id = r.target_id
+		WHERE r.valid_to IS NULL
+		  AND r.source_id = ANY($1) AND r.target_id = ANY($1)
+		  AND ($2::text[] IS NULL OR r.type = ANY($2))
+		ORDER BY r.type, se.slug, te.slug`, ids, req.Params.RelType)
+	if err != nil {
+		return nil, err
+	}
+	edges, err := scanRelationships(rows)
+	if err != nil {
+		return nil, err
+	}
+
+	resp := gen.GetGraph200JSONResponse{Nodes: nodes, Edges: edges}
+	if truncated {
+		resp.Truncated = &truncated
+	}
+	return resp, nil
+}
+
+func (s *Server) queryEntities(ctx context.Context, query string, args ...any) ([]gen.Entity, error) {
+	rows, err := s.pool.Query(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []gen.Entity{}
+	for rows.Next() {
+		e, err := scanEntity(rows)
+		if err != nil {
+			return nil, err
+		}
+		items = append(items, e)
+	}
+	return items, rows.Err()
+}
+
+// ─── Ontology ─────────────────────────────────────────────────────────
+
+func (s *Server) GetOntology(ctx context.Context, req gen.GetOntologyRequestObject) (gen.GetOntologyResponseObject, error) {
+	resp := gen.GetOntology200JSONResponse{
+		EntityTypes:       []gen.EntityType{},
+		RelationshipTypes: []gen.RelationshipType{},
+		Lifecycles:        []gen.LifecycleDef{},
+	}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT name, parent_type, is_abstract, domain, layer, description,
+		       lifecycle_id, attribute_schema, schema_version, status
+		FROM entity_types ORDER BY name`)
+	if err != nil {
+		return nil, err
+	}
+	for rows.Next() {
+		var et gen.EntityType
+		var schemaVersion int
+		var schemaJSON []byte
+		if err := rows.Scan(&et.Name, &et.ParentType, &et.IsAbstract, &et.Domain,
+			&et.Layer, &et.Description, &et.LifecycleId, &schemaJSON,
+			&schemaVersion, &et.Status); err != nil {
+			rows.Close()
+			return nil, err
+		}
+		et.SchemaVersion = &schemaVersion
+		var schema map[string]any
+		if len(schemaJSON) > 0 && json.Unmarshal(schemaJSON, &schema) == nil && schema != nil {
+			et.AttributeSchema = &schema
+		}
+		resp.EntityTypes = append(resp.EntityTypes, et)
+	}
+	rows.Close()
+	if rows.Err() != nil {
+		return nil, rows.Err()
+	}
+
+	rows, err = s.pool.Query(ctx, `
+		SELECT name, inverse, source_type, target_type, cardinality, description
+		FROM relationship_types ORDER BY name`)
+	if err != nil {
+		return nil, err
+	}
+	for rows.Next() {
+		var rt gen.RelationshipType
+		if err := rows.Scan(&rt.Name, &rt.Inverse, &rt.SourceType, &rt.TargetType,
+			&rt.Cardinality, &rt.Description); err != nil {
+			rows.Close()
+			return nil, err
+		}
+		resp.RelationshipTypes = append(resp.RelationshipTypes, rt)
+	}
+	rows.Close()
+	if rows.Err() != nil {
+		return nil, rows.Err()
+	}
+
+	rows, err = s.pool.Query(ctx, `
+		SELECT id, states, default_state, terminal_states, transitions
+		FROM lifecycle_defs ORDER BY id`)
+	if err != nil {
+		return nil, err
+	}
+	for rows.Next() {
+		var lc gen.LifecycleDef
+		var terminal []string
+		var transJSON []byte
+		if err := rows.Scan(&lc.Id, &lc.States, &lc.DefaultState, &terminal, &transJSON); err != nil {
+			rows.Close()
+			return nil, err
+		}
+		lc.TerminalStates = &terminal
+		if err := json.Unmarshal(transJSON, &lc.Transitions); err != nil {
+			rows.Close()
+			return nil, fmt.Errorf("lifecycle %s transitions: %w", lc.Id, err)
+		}
+		resp.Lifecycles = append(resp.Lifecycles, lc)
+	}
+	rows.Close()
+	return resp, rows.Err()
+}
+
+// ─── Signals ──────────────────────────────────────────────────────────
+
+func (s *Server) ListSignals(ctx context.Context, req gen.ListSignalsRequestObject) (gen.ListSignalsResponseObject, error) {
+	limit := clampLimit(req.Params.Limit)
+	rows, err := s.pool.Query(ctx, `
+		SELECT sig.entity_id, se.slug, sig.kind, sig.severity, sig.state,
+		       te.slug, sig.check_id::text, sig.evidence, sig.likely_cause,
+		       sig.occurrence_count, sig.flap_count, sig.hold_down_until,
+		       sig.mute_until, sig.first_seen_at, sig.last_seen_at
+		FROM signals sig
+		JOIN entities se ON se.id = sig.entity_id
+		LEFT JOIN entities te ON te.id = sig.target_entity_id
+		WHERE ($1::text IS NULL OR sig.state = $1)
+		  AND ($2::text IS NULL OR sig.severity = $2)
+		  AND ($3::text IS NULL OR te.slug = $3)
+		  AND ($4::text IS NULL OR sig.kind = $4)
+		  AND ($5::text IS NULL OR se.slug > $5)
+		ORDER BY se.slug
+		LIMIT $6`,
+		req.Params.State, (*string)(req.Params.Severity), req.Params.EntityId,
+		req.Params.Kind, req.Params.Cursor, limit+1)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	items := []gen.Signal{}
+	for rows.Next() {
+		var sig gen.Signal
+		var flap int
+		if err := rows.Scan(&sig.Id, &sig.Slug, &sig.Kind, &sig.Severity, &sig.State,
+			&sig.Target, &sig.CheckId, &sig.Evidence, &sig.LikelyCause,
+			&sig.OccurrenceCount, &flap, &sig.HoldDownUntil,
+			&sig.MuteUntil, &sig.FirstSeenAt, &sig.LastSeenAt); err != nil {
+			return nil, err
+		}
+		sig.FlapCount = &flap
+		items = append(items, sig)
+	}
+	if rows.Err() != nil {
+		return nil, rows.Err()
+	}
+
+	var next *string
+	if len(items) > limit {
+		items = items[:limit]
+		next = &items[len(items)-1].Slug
+	}
+	return gen.ListSignals200JSONResponse{Items: items, NextCursor: next}, nil
+}
+
+// ─── Observability + system ───────────────────────────────────────────
+
+func (s *Server) GetFleetHealth(ctx context.Context, req gen.GetFleetHealthRequestObject) (gen.GetFleetHealthResponseObject, error) {
+	resp := gen.GetFleetHealth200JSONResponse{}
+	resp.Entities = []struct {
+		Health      gen.HealthSummaryEntitiesHealth `json:"health"`
+		LastCheckAt *time.Time                      `json:"last_check_at"`
+		Slug        string                          `json:"slug"`
+		Trend       *gen.HealthSummaryEntitiesTrend `json:"trend"`
+		Type        string                          `json:"type"`
+	}{}
+
+	rows, err := s.pool.Query(ctx, `
+		SELECT e.slug, e.type, st.health, st.last_check_at
+		FROM entity_status st JOIN entities e ON e.id = st.entity_id
+		ORDER BY e.slug`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var slug, typ, health string
+		var lastCheck *time.Time
+		if err := rows.Scan(&slug, &typ, &health, &lastCheck); err != nil {
+			return nil, err
+		}
+		switch health {
+		case "healthy":
+			resp.Summary.Healthy++
+		case "degraded":
+			resp.Summary.Degraded++
+		case "down":
+			resp.Summary.Down++
+		default:
+			resp.Summary.Unknown++
+		}
+		resp.Entities = append(resp.Entities, struct {
+			Health      gen.HealthSummaryEntitiesHealth `json:"health"`
+			LastCheckAt *time.Time                      `json:"last_check_at"`
+			Slug        string                          `json:"slug"`
+			Trend       *gen.HealthSummaryEntitiesTrend `json:"trend"`
+			Type        string                          `json:"type"`
+		}{
+			Health:      gen.HealthSummaryEntitiesHealth(health),
+			LastCheckAt: lastCheck,
+			Slug:        slug,
+			Type:        typ,
+		})
+	}
+	return resp, rows.Err()
+}
+
+func (s *Server) ExportSeeds(ctx context.Context, req gen.ExportSeedsRequestObject) (gen.ExportSeedsResponseObject, error) {
+	exports, err := db.ExportToYAML(ctx, s.pool)
+	if err != nil {
+		return nil, err
+	}
+	return gen.ExportSeeds200JSONResponse{
+		Ontology:  string(exports["ontology.yaml"]),
+		Inventory: string(exports["inventory.yaml"]),
+		Policy:    string(exports["policy.yaml"]),
+	}, nil
+}