Repository Public
1package api23import (4 "context"5 "encoding/json"6 "errors"7 "net/netip"8 "regexp"9 "slices"10 "strconv"11 "strings"12 "time"1314 "github.com/google/uuid"15 "github.com/jackc/pgx/v5"1617 "clustr.spboucher.ai/mcc/internal/audit"18 "clustr.spboucher.ai/mcc/internal/authz"19 "clustr.spboucher.ai/mcc/internal/events"20 "clustr.spboucher.ai/mcc/internal/httpx"21 "clustr.spboucher.ai/mcc/internal/ids"22 "clustr.spboucher.ai/mcc/internal/protocol"23)2425// ── Node model ─────────────────────────────────────────────────────────────2627// clNodeFrom joins a node with its latest state and active agent and derives,28// in SQL, what lists filter and sort on. Parameters $1..$3 are clFreshArgs.29//30// t1.seen last contact: the later of the last stored report and nodes.last_seen_at31// t2.fresh freshness per DESIGN-BRIEF §6 (never seen = offline)32// t3.* headline values; NULL when the node is offline (an old value is33// not a current value) or when the metric was not reported34const clNodeFrom = ` from nodes n35 left join node_state s on s.node_id = n.id36 left join agents a on a.node_id = n.id and a.revoked_at is null37 cross join lateral (select greatest(s.received_at, n.last_seen_at) as seen) t138 cross join lateral (select case when t1.seen is null then 'offline'39 when $1::timestamptz - t1.seen < make_interval(secs => $2::float8) then 'fresh'40 when $1::timestamptz - t1.seen <= make_interval(secs => $3::float8) then 'stale'41 else 'offline' end as fresh) t242 cross join lateral (select43 case when t2.fresh <> 'offline' and jsonb_typeof(s.values->'cpu.usage') = 'number' then (s.values->>'cpu.usage')::float8 end as cpu,44 case when t2.fresh <> 'offline' and jsonb_typeof(s.values->'load.1') = 'number' then (s.values->>'load.1')::float8 end as load1,45 case when t2.fresh <> 'offline' and jsonb_typeof(s.values->'mem.used') = 'number' then46 (s.values->>'mem.used')::float8 * 100 / nullif(coalesce(47 case when jsonb_typeof(s.values->'mem.total') = 'number' then (s.values->>'mem.total')::float8 end, n.mem_bytes::float8), 0) end as mem,48 case when t2.fresh <> 'offline' then (select max(v.used_bytes::float8 * 100 / v.total_bytes) from volumes v49 where v.node_id = n.id and v.gone_at is null and v.kind = 'internal' and v.total_bytes > 0 and v.used_bytes is not null) end as disk) t3 `5051const clNodeCols = `n.id, n.hardware_uuid, n.alias::text, n.kind::text, n.hostname, n.site, n.role, n.environment, n.tags,52 n.model, n.chip, n.arch, n.cpu_cores, n.gpu_cores, n.mem_bytes, n.storage_bytes, n.os_name, n.os_version, n.os_build,53 host(n.primary_ip), n.registered_via, n.maintenance, n.maintenance_reason, n.created_at, n.retired_at, n.inventory_at,54 s.ts, t1.seen, t3.cpu, t3.mem, t3.disk, t3.load1, coalesce(a.version, ''),55 (select count(*) from alerts al where al.node_id = n.id and al.state <> 'resolved')`5657type clNode struct {58 ID uuid.UUID59 HardwareUUID *string60 Alias string61 Kind string62 Hostname string63 Site string64 Role string65 Environment string66 Tags []string67 Model *string68 Chip *string69 Arch *string70 CPUCores *int71 GPUCores *int72 MemBytes *int6473 StorageBytes *int6474 OSName *string75 OSVersion *string76 OSBuild *string77 PrimaryIP *string78 RegisteredVia string79 Maintenance bool80 MaintReason string81 CreatedAt time.Time82 RetiredAt *time.Time83 InventoryAt *time.Time84 ObservedAt *time.Time // agent clock of the latest report; nil when the node never reported85 Seen *time.Time86 CPU *float6487 Mem *float6488 Disk *float6489 Load1 *float6490 AgentVersion string91 OpenAlerts int92}9394func clScanNode(row pgx.Row, extra ...any) (clNode, error) {95 var n clNode96 dst := append([]any{&n.ID, &n.HardwareUUID, &n.Alias, &n.Kind, &n.Hostname, &n.Site, &n.Role, &n.Environment, &n.Tags,97 &n.Model, &n.Chip, &n.Arch, &n.CPUCores, &n.GPUCores, &n.MemBytes, &n.StorageBytes, &n.OSName, &n.OSVersion, &n.OSBuild,98 &n.PrimaryIP, &n.RegisteredVia, &n.Maintenance, &n.MaintReason, &n.CreatedAt, &n.RetiredAt, &n.InventoryAt,99 &n.ObservedAt, &n.Seen, &n.CPU, &n.Mem, &n.Disk, &n.Load1, &n.AgentVersion, &n.OpenAlerts}, extra...)100 err := row.Scan(dst...)101 if n.Tags == nil {102 n.Tags = []string{}103 }104 return n, err105}106107func (n *clNode) facets() []authz.Resource { return clNodeFacets(n.ID, n.Site, n.Tags) }108109// clNodeView says which optional parts of a node the caller may see.110type clNodeView struct {111 private bool // nodes.private.read on this node: addresses, identifiers112 alerts bool // alerts.read: open alert count113}114115func (h *clusterHandlers) nodeView(acc *clAccess, n *clNode) clNodeView {116 return clNodeView{private: acc.can(authz.NodesPrivateRead, n.facets()...), alerts: acc.can(authz.AlertsRead)}117}118119func (h *clusterHandlers) toNode(n *clNode, now time.Time, v clNodeView) Node {120 out := Node{Id: n.ID, Alias: n.Alias, Kind: NodeKind(n.Kind), Hostname: n.Hostname, Site: n.Site, Role: n.Role, Environment: n.Environment,121 Tags: n.Tags, Model: clNonEmpty(n.Model), Chip: clNonEmpty(n.Chip), Arch: clNonEmpty(n.Arch), CpuCores: n.CPUCores, GpuCores: n.GPUCores,122 MemBytes: n.MemBytes, StorageBytes: n.StorageBytes, OsName: clNonEmpty(n.OSName), OsVersion: clNonEmpty(n.OSVersion),123 RegisteredVia: NodeRegisteredVia(n.RegisteredVia), Maintenance: n.Maintenance, MaintenanceReason: n.MaintReason, CreatedAt: n.CreatedAt,124 LastSeenAt: n.Seen, RetiredAt: n.RetiredAt, ObservedAt: n.ObservedAt, Freshness: h.clFresh(now, n.Seen)}125 if v.private {126 out.PrimaryIp = n.PrimaryIP127 }128 if n.AgentVersion != "" {129 out.AgentVersion = &n.AgentVersion130 }131 if n.CPU != nil || n.Mem != nil || n.Disk != nil || n.Load1 != nil {132 out.Headline = &NodeHeadline{CpuUsagePct: clF32(n.CPU), MemUsedPct: clF32(n.Mem), DiskUsedPct: clF32(n.Disk), Load1: clF32(n.Load1)}133 }134 if v.alerts {135 out.OpenAlerts = &n.OpenAlerts136 }137 return out138}139140// clQuerier is satisfied by the pool and by a transaction.141type clQuerier interface {142 QueryRow(ctx context.Context, sql string, args ...any) pgx.Row143 Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)144}145146func (h *clusterHandlers) nodeByID(ctx context.Context, q clQuerier, now time.Time, id uuid.UUID, extraCols string, extra ...any) (clNode, error) {147 n, err := clScanNode(q.QueryRow(ctx, `select `+clNodeCols+extraCols+clNodeFrom+` where n.id = $4`, append(h.clFreshArgs(now), id)...), extra...)148 if errors.Is(err, pgx.ErrNoRows) {149 return n, httpx.ErrNotFound150 }151 return n, err152}153154// readableNode loads a node the caller may read. A node hidden by a scoped155// deny is reported as not found, like an unknown one.156func (h *clusterHandlers) readableNode(ctx context.Context, acc *clAccess, now time.Time, id uuid.UUID, extraCols string, extra ...any) (clNode, error) {157 n, err := h.nodeByID(ctx, h.Pool, now, id, extraCols, extra...)158 if err != nil {159 return n, err160 }161 if !acc.can(authz.NodesRead, n.facets()...) {162 return n, httpx.ErrNotFound163 }164 return n, nil165}166167// ── List ───────────────────────────────────────────────────────────────────168169// clSQL accumulates conditions and their parameters.170type clSQL struct {171 args []any172 conds []string173}174175func (b *clSQL) arg(v any) string {176 b.args = append(b.args, v)177 return "$" + strconv.Itoa(len(b.args))178}179180func (b *clSQL) and(cond string) { b.conds = append(b.conds, cond) }181182func (b *clSQL) where() string {183 if len(b.conds) == 0 {184 return ""185 }186 return " where " + strings.Join(b.conds, " and ")187}188189// clKeyset appends the "rows after the cursor" condition for an ordering by190// (key [asc|desc] nulls last, id asc) and returns the ORDER BY clause.191// cur is nil for the first page, else [isNull, keyText, id].192func (b *clSQL) clKeyset(key, cast, idCol string, desc bool, cur []string) (string, error) {193 dir, cmp := "asc", ">"194 if desc {195 dir, cmp = "desc", "<"196 }197 if cur != nil {198 id, err := clCursorUUID(cur[2])199 if err != nil {200 return "", err201 }202 if cur[0] == "1" {203 b.and("(" + key + " is null and " + idCol + " > " + b.arg(id) + ")")204 } else {205 k := b.arg(cur[1]) + "::" + cast206 b.and("(" + key + " " + cmp + " " + k + " or (" + key + " = " + k + " and " + idCol + " > " + b.arg(id) + ") or " + key + " is null)")207 }208 }209 return " order by " + key + " " + dir + " nulls last, " + idCol + " asc", nil210}211212type clSortKey struct{ expr, cast string }213214var clNodeSorts = map[ListNodesParamsSort]clSortKey{215 ListNodesParamsSortAlias: {"lower(n.alias::text)", "text"},216 ListNodesParamsSortSite: {"n.site", "text"},217 ListNodesParamsSortRole: {"n.role", "text"},218 ListNodesParamsSortLastSeen: {"t1.seen", "timestamptz"},219 ListNodesParamsSortCpu: {"t3.cpu", "float8"},220 ListNodesParamsSortMemory: {"t3.mem", "float8"},221 ListNodesParamsSortDisk: {"t3.disk", "float8"},222}223224// clCheckKey rejects a cursor whose key cannot be cast to the sort column's type.225func clCheckKey(cast, v string) error {226 var err error227 switch cast {228 case "float8":229 _, err = strconv.ParseFloat(v, 64)230 case "timestamptz":231 if _, err = time.Parse("2006-01-02 15:04:05.999999999Z07", v); err != nil {232 _, err = time.Parse("2006-01-02 15:04:05.999999999Z07:00", v)233 }234 }235 if err != nil {236 return errClCursor237 }238 return nil239}240241func (h *clusterHandlers) ListNodes(ctx context.Context, req ListNodesRequestObject) (ListNodesResponseObject, error) {242 p := req.Params243 limit, err := clLimit(p.Limit)244 if err != nil {245 return nil, err246 }247 q, err := clQuery(p.Q)248 if err != nil {249 return nil, err250 }251 sort, order := ListNodesParamsSortAlias, ListNodesParamsOrderAsc252 if p.Sort != nil {253 sort = *p.Sort254 }255 if p.Order != nil {256 order = *p.Order257 }258 sk, ok := clNodeSorts[sort]259 if !ok {260 return nil, clInvalid("sort", "must be one of alias, site, role, last_seen, cpu, memory, disk")261 }262 if order != ListNodesParamsOrderAsc && order != ListNodesParamsOrderDesc {263 return nil, clInvalid("order", "must be asc or desc")264 }265 acc, err := h.clAccessFor(ctx)266 if err != nil {267 return nil, err268 }269 now := time.Now().UTC()270 b := &clSQL{args: h.clFreshArgs(now)}271 if q != "" {272 a := b.arg(clLike(q))273 b.and(`(n.alias::text ilike ` + a + ` escape '\' or n.hostname ilike ` + a + ` escape '\' or coalesce(n.model,'') ilike ` + a +274 ` escape '\' or coalesce(n.chip,'') ilike ` + a + ` escape '\')`)275 }276 for _, f := range []struct {277 name, col string278 v *string279 }{{"site", "n.site", p.Site}, {"role", "n.role", p.Role}} {280 if f.v != nil {281 if len(*f.v) > 64 {282 return nil, clInvalid(f.name, "must be at most 64 characters")283 }284 b.and(f.col + " = " + b.arg(*f.v))285 }286 }287 if p.Tag != nil {288 if len(*p.Tag) > 48 {289 return nil, clInvalid("tag", "must be at most 48 characters")290 }291 b.and(b.arg(*p.Tag) + " = any(n.tags)")292 }293 if p.Kind != nil {294 if !slices.Contains([]NodeKind{NodeKindMac, NodeKindLinux, NodeKindNas}, *p.Kind) {295 return nil, clInvalid("kind", "must be mac, linux or nas")296 }297 b.and("n.kind = " + b.arg(string(*p.Kind)) + "::node_kind")298 }299 if p.Freshness != nil {300 if !slices.Contains([]Freshness{FreshnessFresh, FreshnessStale, FreshnessOffline}, *p.Freshness) {301 return nil, clInvalid("freshness", "must be fresh, stale or offline")302 }303 b.and("t2.fresh = " + b.arg(string(*p.Freshness)))304 }305 if p.Maintenance != nil {306 b.and("n.maintenance = " + b.arg(*p.Maintenance))307 }308 if p.Retired == nil || !*p.Retired {309 b.and("n.retired_at is null")310 }311 kind := "nodes:" + string(sort) + ":" + string(order)312 cur, err := clDecodeCursor(p.Cursor, kind, 3)313 if err != nil {314 return nil, err315 }316 if cur != nil && cur[0] != "1" {317 if err := clCheckKey(sk.cast, cur[1]); err != nil {318 return nil, err319 }320 }321 orderBy, err := b.clKeyset(sk.expr, sk.cast, "n.id", order == ListNodesParamsOrderDesc, cur)322 if err != nil {323 return nil, err324 }325 rows, err := h.Pool.Query(ctx, `select `+clNodeCols+`, (`+sk.expr+`)::text`+clNodeFrom+b.where()+orderBy+` limit `+b.arg(limit+1), b.args...)326 if err != nil {327 return nil, err328 }329 type row struct {330 n clNode331 key *string332 }333 list, err := pgx.CollectRows(rows, func(r pgx.CollectableRow) (row, error) {334 var x row335 var err error336 x.n, err = clScanNode(r, &x.key)337 return x, err338 })339 if err != nil {340 return nil, err341 }342 out := NodeList{Items: make([]Node, 0, len(list))}343 if len(list) > limit {344 list = list[:limit]345 last := list[limit-1]346 isNull, key := "1", ""347 if last.key != nil {348 isNull, key = "0", *last.key349 }350 out.NextCursor = clEncodeCursor(kind, isNull, key, last.n.ID.String())351 }352 filter := acc.scoped(authz.NodesRead)353 for i := range list {354 n := &list[i].n355 if filter && !acc.can(authz.NodesRead, n.facets()...) {356 continue // hidden by a scoped deny; the page is simply shorter357 }358 out.Items = append(out.Items, h.toNode(n, now, h.nodeView(acc, n)))359 }360 return ListNodes200JSONResponse{Body: out}, nil361}362363// ── Manual registration, update, retirement ────────────────────────────────364365var clAliasRe = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)366367func clAlias(field, v string) (string, error) {368 if !clAliasRe.MatchString(v) {369 return "", clInvalid(field, "must be 1 to 64 characters: letters, digits, dot, underscore or hyphen, starting with a letter or digit")370 }371 return v, nil372}373374func clTags(in *[]string) ([]string, error) {375 out := []string{}376 if in == nil {377 return out, nil378 }379 if len(*in) > 32 {380 return nil, clInvalid("tags", "at most 32 tags")381 }382 for _, t := range *in {383 t, err := clText("tags", &t, 1, 48)384 if err != nil {385 return nil, err386 }387 if !slices.Contains(out, t) {388 out = append(out, t)389 }390 }391 return out, nil392}393394func clNodeKind(k NodeKind) error {395 if k != NodeKindMac && k != NodeKindLinux && k != NodeKindNas {396 return clInvalid("kind", "must be mac, linux or nas")397 }398 return nil399}400401func (h *clusterHandlers) CreateNode(ctx context.Context, req CreateNodeRequestObject) (CreateNodeResponseObject, error) {402 if req.Body == nil {403 return nil, httpx.Validation("Body required.")404 }405 body := req.Body406 alias, err := clAlias("alias", body.Alias)407 if err != nil {408 return nil, err409 }410 if err := clNodeKind(body.Kind); err != nil {411 return nil, err412 }413 fields := map[string]string{"site": "default", "role": "worker", "environment": "production"}414 for name, v := range map[string]*string{"site": body.Site, "role": body.Role, "environment": body.Environment} {415 if v != nil {416 s, err := clText(name, v, 1, 64)417 if err != nil {418 return nil, err419 }420 fields[name] = s421 }422 }423 tags, err := clTags(body.Tags)424 if err != nil {425 return nil, err426 }427 // Declared hardware is kept apart from the measured columns: it is what428 // someone expects, not what an agent observed, and the first agent429 // inventory replaces it.430 inventory := map[string]any{}431 if e := body.Expected; e != nil {432 exp := map[string]any{}433 for name, v := range map[string]*string{"model": e.Model, "chip": e.Chip} {434 if v != nil {435 s, err := clText("expected."+name, v, 1, 80)436 if err != nil {437 return nil, err438 }439 exp[name] = s440 }441 }442 if e.CpuCores != nil {443 if *e.CpuCores < 1 || *e.CpuCores > 4096 {444 return nil, clInvalid("expected.cpu_cores", "must be between 1 and 4096")445 }446 exp["cpu_cores"] = *e.CpuCores447 }448 for name, v := range map[string]*int64{"mem_bytes": e.MemBytes, "storage_bytes": e.StorageBytes} {449 if v != nil {450 if *v < 1 {451 return nil, clInvalid("expected."+name, "must be positive")452 }453 exp[name] = *v454 }455 }456 if len(exp) > 0 {457 inventory["expected"] = exp458 }459 }460 acc, err := h.clAccessFor(ctx)461 if err != nil {462 return nil, err463 }464 id := ids.New()465 // The new node must itself be writable by the caller (a scoped deny on its site or tags applies).466 if err := h.clAuthorizeWrite(ctx, acc, authz.NodesWrite, authz.Resource{Kind: "node", ID: id.String()}, clNodeFacets(id, fields["site"], tags)); err != nil {467 return nil, err468 }469 tx, err := h.Pool.Begin(ctx)470 if err != nil {471 return nil, err472 }473 defer tx.Rollback(ctx)474 _, err = tx.Exec(ctx, `insert into nodes(id, alias, kind, site, role, environment, tags, registered_via, inventory)475 values ($1, $2, $3::node_kind, $4, $5, $6, $7, 'manual', $8)`,476 id, alias, string(body.Kind), fields["site"], fields["role"], fields["environment"], tags, inventory)477 if clUniqueViolation(err) {478 tx.Rollback(ctx)479 return nil, h.aliasConflict(ctx, alias)480 } else if err != nil {481 return nil, err482 }483 if err := h.audit(ctx, tx, "node.create", "node", id.String(), audit.Success, "", map[string]any{"alias": alias, "kind": string(body.Kind),484 "site": fields["site"], "role": fields["role"], "environment": fields["environment"], "tags": tags, "registered_via": "manual"}); err != nil {485 return nil, err486 }487 if err := events.Publish(ctx, tx, "node.updated", NodeUpdatedEvent{NodeId: id, Change: NodeUpdatedEventChangeCreated}); err != nil {488 return nil, err489 }490 if err := tx.Commit(ctx); err != nil {491 return nil, err492 }493 now := time.Now().UTC()494 n, err := h.nodeByID(ctx, h.Pool, now, id, "")495 if err != nil {496 return nil, err497 }498 return CreateNode201JSONResponse{Body: h.toNode(&n, now, h.nodeView(acc, &n))}, nil499}500501// aliasConflict explains a refused alias; a retired node keeps its alias so502// that its history stays attributable.503func (h *clusterHandlers) aliasConflict(ctx context.Context, alias string) error {504 var retired bool505 if err := h.Pool.QueryRow(ctx, `select retired_at is not null from nodes where alias = $1`, alias).Scan(&retired); err == nil && retired {506 return clConflict("Alias already in use by a retired node.").With("retired", true)507 }508 return clConflict("Alias already in use.")509}510511func (h *clusterHandlers) UpdateNode(ctx context.Context, req UpdateNodeRequestObject) (UpdateNodeResponseObject, error) {512 if req.Body == nil {513 return nil, httpx.Validation("Body required.")514 }515 body := req.Body516 if body.Alias == nil && body.Site == nil && body.Role == nil && body.Environment == nil && body.Tags == nil {517 return nil, httpx.Validation("Nothing to update: give alias, site, role, environment or tags.")518 }519 var alias *string520 if body.Alias != nil {521 a, err := clAlias("alias", *body.Alias)522 if err != nil {523 return nil, err524 }525 alias = &a526 }527 set := map[string]*string{}528 for name, v := range map[string]*string{"site": body.Site, "role": body.Role, "environment": body.Environment} {529 if v != nil {530 s, err := clText(name, v, 1, 64)531 if err != nil {532 return nil, err533 }534 set[name] = &s535 }536 }537 var tags []string538 if body.Tags != nil {539 t, err := clTags(body.Tags)540 if err != nil {541 return nil, err542 }543 tags = t544 }545 acc, err := h.clAccessFor(ctx)546 if err != nil {547 return nil, err548 }549 tx, err := h.Pool.Begin(ctx)550 if err != nil {551 return nil, err552 }553 defer tx.Rollback(ctx)554 var cur struct {555 alias, site, role, env string556 tags []string557 retired bool558 }559 err = tx.QueryRow(ctx, `select alias::text, site, role, environment, tags, retired_at is not null from nodes where id = $1 for update`, req.Id).560 Scan(&cur.alias, &cur.site, &cur.role, &cur.env, &cur.tags, &cur.retired)561 if errors.Is(err, pgx.ErrNoRows) {562 return nil, httpx.ErrNotFound563 } else if err != nil {564 return nil, err565 }566 target := authz.Resource{Kind: "node", ID: req.Id.String()}567 if !acc.can(authz.NodesRead, clNodeFacets(req.Id, cur.site, cur.tags)...) {568 return nil, httpx.ErrNotFound569 }570 // The caller must be allowed to write the node as it is AND as it would become571 // (moving a node into a site one may not write is refused).572 next := cur573 changes := map[string]any{}574 change := func(name, from, to string) {575 if from != to {576 changes[name] = map[string]any{"from": from, "to": to}577 }578 }579 if alias != nil {580 change("alias", cur.alias, *alias)581 next.alias = *alias582 }583 if v := set["site"]; v != nil {584 change("site", cur.site, *v)585 next.site = *v586 }587 if v := set["role"]; v != nil {588 change("role", cur.role, *v)589 next.role = *v590 }591 if v := set["environment"]; v != nil {592 change("environment", cur.env, *v)593 next.env = *v594 }595 if body.Tags != nil && !slices.Equal(cur.tags, tags) {596 changes["tags"] = map[string]any{"from": cur.tags, "to": tags}597 next.tags = tags598 }599 for _, facets := range [][]authz.Resource{clNodeFacets(req.Id, cur.site, cur.tags), clNodeFacets(req.Id, next.site, next.tags)} {600 if err := h.clAuthorizeWrite(ctx, acc, authz.NodesWrite, target, facets); err != nil {601 tx.Rollback(ctx)602 return nil, err603 }604 }605 if cur.retired {606 return nil, clConflict("A retired node cannot be modified.").With("retired", true)607 }608 if len(changes) > 0 {609 _, err = tx.Exec(ctx, `update nodes set alias = $2, site = $3, role = $4, environment = $5, tags = $6 where id = $1`,610 req.Id, next.alias, next.site, next.role, next.env, next.tags)611 if clUniqueViolation(err) {612 tx.Rollback(ctx)613 return nil, h.aliasConflict(ctx, next.alias)614 } else if err != nil {615 return nil, err616 }617 if next.alias != cur.alias {618 // A pending enrollment token designates its node by alias: keep it pointing at this node.619 if _, err := tx.Exec(ctx, `update agent_enrollment_tokens set node_alias = $2620 where node_alias = $1 and consumed_at is null and revoked_at is null`, cur.alias, next.alias); err != nil {621 return nil, err622 }623 }624 if err := h.audit(ctx, tx, "node.update", "node", req.Id.String(), audit.Success, "", changes); err != nil {625 return nil, err626 }627 if err := events.Publish(ctx, tx, "node.updated", NodeUpdatedEvent{NodeId: req.Id, Change: NodeUpdatedEventChangeUpdated}); err != nil {628 return nil, err629 }630 if err := tx.Commit(ctx); err != nil {631 return nil, err632 }633 } else {634 tx.Rollback(ctx)635 }636 now := time.Now().UTC()637 n, err := h.nodeByID(ctx, h.Pool, now, req.Id, "")638 if err != nil {639 return nil, err640 }641 return UpdateNode200JSONResponse{Body: h.toNode(&n, now, h.nodeView(acc, &n))}, nil642}643644// RetireNode marks the node retired, revokes its agent and resolves its open645// alerts, atomically. History (samples, audit, alerts) is kept. Retiring a646// node that is already retired is a no-op.647func (h *clusterHandlers) RetireNode(ctx context.Context, req RetireNodeRequestObject) (RetireNodeResponseObject, error) {648 acc, err := h.clAccessFor(ctx)649 if err != nil {650 return nil, err651 }652 sess := principalFrom(ctx).Session653 tx, err := h.Pool.Begin(ctx)654 if err != nil {655 return nil, err656 }657 defer tx.Rollback(ctx)658 var alias, site string659 var tags []string660 var retired bool661 err = tx.QueryRow(ctx, `select alias::text, site, tags, retired_at is not null from nodes where id = $1 for update`, req.Id).Scan(&alias, &site, &tags, &retired)662 if errors.Is(err, pgx.ErrNoRows) {663 return nil, httpx.ErrNotFound664 } else if err != nil {665 return nil, err666 }667 facets := clNodeFacets(req.Id, site, tags)668 if !acc.can(authz.NodesRead, facets...) {669 return nil, httpx.ErrNotFound670 }671 if err := h.clAuthorizeWrite(ctx, acc, authz.NodesWrite, authz.Resource{Kind: "node", ID: req.Id.String()}, facets); err != nil {672 tx.Rollback(ctx)673 return nil, err674 }675 if retired {676 return RetireNode204Response{}, nil677 }678 if _, err := tx.Exec(ctx, `update nodes set retired_at = now() where id = $1`, req.Id); err != nil {679 return nil, err680 }681 tag, err := tx.Exec(ctx, `update agents set revoked_at = now(), revoked_reason = 'node retired' where node_id = $1 and revoked_at is null`, req.Id)682 if err != nil {683 return nil, err684 }685 rows, err := tx.Query(ctx, `update alerts set state = 'resolved', resolved_at = now(), last_eval_at = now()686 where node_id = $1 and state <> 'resolved' returning id, rule_id, severity::text, summary`, req.Id)687 if err != nil {688 return nil, err689 }690 type resolved struct {691 ID, RuleID uuid.UUID692 Severity, Summary string693 }694 alerts, err := pgx.CollectRows(rows, func(r pgx.CollectableRow) (resolved, error) {695 var a resolved696 err := r.Scan(&a.ID, &a.RuleID, &a.Severity, &a.Summary)697 return a, err698 })699 if err != nil {700 return nil, err701 }702 for _, a := range alerts {703 if _, err := tx.Exec(ctx, `insert into timeline_events(id, alert_id, kind, actor_id, body) values ($1, $2, 'resolved', $3, 'Node retired.')`,704 ids.New(), a.ID, sess.User.ID); err != nil {705 return nil, err706 }707 if err := events.Publish(ctx, tx, "alert.changed", map[string]any{"alert_id": a.ID, "rule_id": a.RuleID, "node_id": req.Id,708 "state": "resolved", "severity": a.Severity, "summary": a.Summary}); err != nil {709 return nil, err710 }711 }712 if err := h.audit(ctx, tx, "node.retire", "node", req.Id.String(), audit.Success, "", map[string]any{"alias": alias,713 "agents_revoked": tag.RowsAffected(), "alerts_resolved": len(alerts)}); err != nil {714 return nil, err715 }716 if err := events.Publish(ctx, tx, "node.updated", NodeUpdatedEvent{NodeId: req.Id, Change: NodeUpdatedEventChangeRetired}); err != nil {717 return nil, err718 }719 if err := tx.Commit(ctx); err != nil {720 return nil, err721 }722 return RetireNode204Response{}, nil723}724725// ── Detail ─────────────────────────────────────────────────────────────────726727func (h *clusterHandlers) GetNode(ctx context.Context, req GetNodeRequestObject) (GetNodeResponseObject, error) {728 acc, err := h.clAccessFor(ctx)729 if err != nil {730 return nil, err731 }732 cat, err := h.clCatalogFor(ctx)733 if err != nil {734 return nil, err735 }736 now := time.Now().UTC()737 var levelsRaw, invRaw, valuesRaw, availRaw []byte738 n, err := h.readableNode(ctx, acc, now, req.Id, `, n.cpu_levels, n.inventory, s.values, s.availability`, &levelsRaw, &invRaw, &valuesRaw, &availRaw)739 if err != nil {740 return nil, err741 }742 view := h.nodeView(acc, &n)743 fresh := h.clFresh(now, n.Seen)744 out := NodeDetail{Node: h.toNode(&n, now, view), OsBuild: clNonEmpty(n.OSBuild), InventoryAt: n.InventoryAt,745 CpuLevels: []CpuPerfLevel{}, Interfaces: []NetworkInterface{}, Volumes: []Volume{}, Latest: map[string]MetricValue{}}746747 var inv protocol.Inventory748 inventory := clObject(invRaw)749 if len(invRaw) > 0 {750 _ = json.Unmarshal(invRaw, &inv) // a manual node holds only {"expected": …}: every field stays empty751 }752 if view.private {753 out.HardwareUuid = clNonEmpty(n.HardwareUUID)754 if sn, ok := inventory["serial_number"].(string); ok && sn != "" {755 out.SerialNumber = &sn // only when an agent reported one; never derived756 }757 }758 levels := inv.CPULevels759 if len(levelsRaw) > 0 {760 var l []protocol.CPULevel761 if json.Unmarshal(levelsRaw, &l) == nil && len(l) > 0 {762 levels = l763 }764 }765 for _, l := range levels {766 out.CpuLevels = append(out.CpuLevels, CpuPerfLevel{Name: l.Name, Cores: l.Cores})767 }768 values, avail := clValues(valuesRaw), clStringMap(availRaw)769 out.Interfaces = clInterfaces(&n, fresh, inv.Interfaces, values, view.private)770771 if out.Volumes, err = h.nodeVolumes(ctx, acc, now, n.ID); err != nil {772 return nil, err773 }774775 // Latest value of every unlabeled catalog metric, or the explicit reason there is none.776 for _, m := range cat.list {777 if m.Labeled {778 continue779 }780 out.Latest[m.Name] = clLatest(m, fresh, n.ObservedAt != nil, values, avail)781 }782783 if out.Agent, err = h.activeAgent(ctx, now, n.ID); err != nil {784 return nil, err785 }786 if n.Maintenance && acc.can(authz.MaintenanceRead) {787 var wid uuid.UUID788 err := h.Pool.QueryRow(ctx, `select id from maintenance_windows where status = 'in_progress'789 and (scope->'node_ids' ? $1 or scope->'all' = 'true'::jsonb) order by starts_at desc limit 1`, n.ID.String()).Scan(&wid)790 if err == nil {791 out.ActiveMaintenanceWindowId = &wid792 } else if !errors.Is(err, pgx.ErrNoRows) {793 return nil, err794 }795 }796 return GetNode200JSONResponse{Body: out}, nil797}798799// clLatest states the latest value of a metric on a node, or why there is none.800// A value is only given while the node is fresh or stale; nothing is ever801// substituted for a missing measurement.802func clLatest(m clMetric, fresh Freshness, reported bool, values map[string]any, avail map[string]string) MetricValue {803 mv := MetricValue{Unit: &m.Unit}804 if !reported {805 mv.Availability = AvailabilityOffline806 mv.Reason = ptr("The node has never reported.")807 return mv808 }809 if a, ok := clDeclared(avail, m.Name, ""); ok {810 mv.Availability, mv.Reason = a, clLimitation(m.Name)811 return mv812 }813 if v, ok := clNumber(values, m.Name); ok {814 mv.Availability = clAvail(fresh)815 if fresh != FreshnessOffline {816 mv.Value = &v817 }818 return mv819 }820 if fresh == FreshnessOffline {821 mv.Availability = AvailabilityOffline822 return mv823 }824 mv.Availability = AvailabilityUnavailable825 mv.Reason = ptr("Not present in the latest report.")826 return mv827}828829// clDeclared returns the availability an agent declared for a metric that830// produced no sample. Unknown words are reported as unavailable rather than831// passed through.832func clDeclared(avail map[string]string, metric, label string) (Availability, bool) {833 a, ok := avail[metric]834 if label != "" {835 if la, lok := avail[clValueKey(metric, label)]; lok {836 a, ok = la, true837 }838 }839 if !ok {840 return "", false841 }842 switch a {843 case protocol.AvailUnsupported:844 return AvailabilityUnsupported, true845 case protocol.AvailPermissionDenied:846 return AvailabilityPermissionDenied, true847 }848 return AvailabilityUnavailable, true849}850851// clValueKey is the node_state.values key of a labeled metric: name{label}.852func clValueKey(metric, label string) string {853 if label == "" {854 return metric855 }856 return metric + "{" + label + "}"857}858859// clLabels lists the labels a labeled metric currently has in node_state.values.860func clLabels(values map[string]any, metric string) []string {861 var out []string862 prefix := metric + "{"863 for k := range values {864 if strings.HasPrefix(k, prefix) && strings.HasSuffix(k, "}") {865 out = append(out, k[len(prefix):len(k)-1])866 }867 }868 slices.Sort(out)869 return out870}871872var clMediaSpeed = regexp.MustCompile(`^(\d+)(G?)base`)873874// clInterfaceKind maps what the agent observed to the contract vocabulary.875// Only the system name is used: a macOS utun interface could be WireGuard,876// Tailscale or something else, so it stays "other" rather than being guessed.877func clInterfaceKind(i protocol.Interface) NetworkInterfaceKind {878 name := strings.ToLower(i.Name)879 switch {880 case strings.HasPrefix(name, "lo") && (len(name) == 2 || (name[2] >= '0' && name[2] <= '9')):881 return NetworkInterfaceKindLoopback882 case strings.HasPrefix(name, "wg"):883 return NetworkInterfaceKindWireguard884 case strings.HasPrefix(name, "tailscale"):885 return NetworkInterfaceKindTailscale886 }887 switch i.Kind {888 case "ethernet":889 return NetworkInterfaceKindEthernet890 case "wifi":891 return NetworkInterfaceKindWifi892 }893 return NetworkInterfaceKindOther894}895896// clInterfaces renders the inventory interfaces of a node with their current897// throughput. Addresses and MAC are private. The catalog has a single898// combined error rate per interface (net.errors, in+out), so the separate899// rx/tx error fields of the contract are never filled.900func clInterfaces(n *clNode, fresh Freshness, in []protocol.Interface, values map[string]any, private bool) []NetworkInterface {901 out := make([]NetworkInterface, 0, len(in))902 for i, itf := range in {903 if i >= protocol.MaxInterfaces {904 break905 }906 ni := NetworkInterface{NodeId: n.ID, NodeAlias: n.Alias, Name: itf.Name, Kind: clInterfaceKind(itf), Up: itf.Up,907 Ipv4: []string{}, Ipv6: []string{}, Freshness: fresh, ObservedAt: n.InventoryAt}908 if private {909 if itf.MAC != "" {910 ni.Mac = &itf.MAC911 }912 for _, a := range itf.Addrs {913 addr := a914 if p, err := netip.ParsePrefix(a); err == nil {915 addr = p.Addr().String()916 }917 ip, err := netip.ParseAddr(strings.SplitN(addr, "%", 2)[0])918 switch {919 case err != nil:920 case ip.Unmap().Is4():921 ni.Ipv4 = append(ni.Ipv4, a)922 default:923 ni.Ipv6 = append(ni.Ipv6, a)924 }925 }926 }927 if m := clMediaSpeed.FindStringSubmatch(itf.Media); m != nil {928 if speed, err := strconv.Atoi(m[1]); err == nil && speed > 0 && speed <= 400000 {929 if m[2] == "G" {930 speed *= 1000931 }932 ni.LinkSpeedMbps = &speed933 }934 }935 if fresh != FreshnessOffline {936 if v, ok := clNumber(values, clValueKey("net.rx", itf.Name)); ok {937 ni.RxBytesPerS = clF32(&v)938 }939 if v, ok := clNumber(values, clValueKey("net.tx", itf.Name)); ok {940 ni.TxBytesPerS = clF32(&v)941 }942 }943 out = append(out, ni)944 }945 return out946}947948// ── Processes, services of a node ──────────────────────────────────────────949950func (h *clusterHandlers) ListNodeProcesses(ctx context.Context, req ListNodeProcessesRequestObject) (ListNodeProcessesResponseObject, error) {951 acc, err := h.clAccessFor(ctx)952 if err != nil {953 return nil, err954 }955 now := time.Now().UTC()956 var procsRaw, availRaw []byte957 var procsAt *time.Time958 n, err := h.readableNode(ctx, acc, now, req.Id, `, s.processes, s.processes_at, s.availability`, &procsRaw, &procsAt, &availRaw)959 if err != nil {960 return nil, err961 }962 fresh := h.clFresh(now, n.Seen)963 out := ProcessList{NodeId: n.ID, Freshness: fresh, Items: []Process{}, ObservedAt: procsAt}964 switch {965 case n.ObservedAt == nil || fresh == FreshnessOffline:966 // An old snapshot of an unreachable node is not what is running now: it is not shown.967 out.Availability = AvailabilityOffline968 return ListNodeProcesses200JSONResponse{Body: out}, nil969 case len(procsRaw) == 0 || string(procsRaw) == "null":970 out.Availability = AvailabilityUnavailable971 if a, ok := clDeclared(clStringMap(availRaw), "processes", ""); ok {972 out.Availability = a973 }974 return ListNodeProcesses200JSONResponse{Body: out}, nil975 }976 var procs []protocol.Process977 if err := json.Unmarshal(procsRaw, &procs); err != nil {978 out.Availability = AvailabilityUnavailable979 return ListNodeProcesses200JSONResponse{Body: out}, nil980 }981 out.Availability = clAvail(fresh)982 for i, p := range procs {983 if i >= protocol.MaxProcesses {984 break985 }986 // The agent never collects command lines (they routinely carry secrets), so `command` is never present.987 item := Process{Pid: int(p.PID), Name: p.Name, CpuPct: ptr(float32(p.CPU)), MemBytes: ptr(p.RSS)}988 if p.User != "" {989 item.User = &p.User990 }991 out.Items = append(out.Items, item)992 }993 return ListNodeProcesses200JSONResponse{Body: out}, nil994}995996func (h *clusterHandlers) ListNodeServices(ctx context.Context, req ListNodeServicesRequestObject) (ListNodeServicesResponseObject, error) {997 acc, err := h.clAccessFor(ctx)998 if err != nil {999 return nil, err1000 }1001 // The node must exist and be visible; the operation itself requires services.read.1002 var site string1003 var tags []string1004 err = h.Pool.QueryRow(ctx, `select site, tags from nodes where id = $1`, req.Id).Scan(&site, &tags)1005 if errors.Is(err, pgx.ErrNoRows) || (err == nil && !acc.can(authz.NodesRead, clNodeFacets(req.Id, site, tags)...)) {1006 return nil, httpx.ErrNotFound1007 } else if err != nil {1008 return nil, err1009 }1010 list, err := h.listServices(ctx, acc, ListServicesParams{Limit: req.Params.Limit, Cursor: req.Params.Cursor, NodeId: &req.Id}, "node-services:"+req.Id.String())1011 if err != nil {1012 return nil, err1013 }1014 return ListNodeServices200JSONResponse{Body: list}, nil1015}1016