Repository Public
1package api23// Shared plumbing of the read side (cluster_*.go) and of administration4// (admin_*.go): validation errors, opaque cursors, LIKE escaping, freshness,5// resource-scoped access decisions and the metric catalog.6//7// Everything here is prefixed "cl" so it cannot collide with helpers of the8// other handler groups living in this package.910import (11 "context"12 "encoding/base64"13 "encoding/json"14 "errors"15 "net/http"16 "strings"17 "sync"18 "time"19 "unicode"20 "unicode/utf8"2122 "github.com/google/uuid"23 "github.com/jackc/pgx/v5"24 "github.com/jackc/pgx/v5/pgconn"25 "github.com/jackc/pgx/v5/pgxpool"2627 "clustr.spboucher.ai/mcc/internal/authz"28 "clustr.spboucher.ai/mcc/internal/httpx"29 "clustr.spboucher.ai/mcc/internal/protocol"30)3132// ── Errors ─────────────────────────────────────────────────────────────────3334// clInvalid is a 400 naming the offending field, in the shape the contract documents.35func clInvalid(field, problem string) *httpx.Error {36 return httpx.Validation("Invalid request.").With("fields", map[string]string{field: problem})37}3839// clUnprocessable is a 422: the request is well-formed but cannot be applied.40func clUnprocessable(reason, message string) *httpx.Error {41 return httpx.Err(http.StatusUnprocessableEntity, "unprocessable", message).With("reason", reason)42}4344func clConflict(message string) *httpx.Error { return httpx.Conflict("conflict", message) }4546func clUniqueViolation(err error) bool {47 var pg *pgconn.PgError48 return errors.As(err, &pg) && pg.Code == "23505"49}5051// ── Pagination ─────────────────────────────────────────────────────────────5253const (54 clDefaultLimit = 5055 clMaxLimit = 20056 clMaxCursor = 102457)5859func clLimit(p *int) (int, error) {60 if p == nil {61 return clDefaultLimit, nil62 }63 if *p < 1 || *p > clMaxLimit {64 return 0, clInvalid("limit", "must be between 1 and 200")65 }66 return *p, nil67}6869// A cursor is the sort position of the last row of a page. It is opaque to70// clients but not secret: its values are only ever bound as query parameters,71// and each list validates their number and types. The kind ties a cursor to72// the list (and sort order) that issued it.73type clCursorDoc struct {74 K string `json:"k"`75 V []string `json:"v"`76}7778func clEncodeCursor(kind string, v ...string) *string {79 b, _ := json.Marshal(clCursorDoc{K: kind, V: v})80 s := base64.RawURLEncoding.EncodeToString(b)81 return &s82}8384var errClCursor = clInvalid("cursor", "is not a cursor issued for this list")8586// clDecodeCursor returns nil when no cursor was given.87func clDecodeCursor(raw *string, kind string, n int) ([]string, error) {88 if raw == nil || *raw == "" {89 return nil, nil90 }91 if len(*raw) > clMaxCursor {92 return nil, errClCursor93 }94 b, err := base64.RawURLEncoding.DecodeString(*raw)95 if err != nil {96 return nil, errClCursor97 }98 var d clCursorDoc99 if err := json.Unmarshal(b, &d); err != nil || d.K != kind || len(d.V) != n {100 return nil, errClCursor101 }102 for _, v := range d.V {103 if !utf8.ValidString(v) || strings.ContainsRune(v, 0) {104 return nil, errClCursor105 }106 }107 return d.V, nil108}109110func clCursorUUID(s string) (uuid.UUID, error) {111 id, err := uuid.Parse(s)112 if err != nil {113 return id, errClCursor114 }115 return id, nil116}117118func clCursorTime(s string) (time.Time, error) {119 t, err := time.Parse(time.RFC3339Nano, s)120 if err != nil {121 return t, errClCursor122 }123 return t, nil124}125126func clTimeKey(t time.Time) string { return t.UTC().Format(time.RFC3339Nano) }127128// ── Text input ─────────────────────────────────────────────────────────────129130var clLikeEscaper = strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`)131132// clLike turns free text into a substring pattern for `ILIKE $n ESCAPE '\'`:133// the wildcards the user typed are matched literally.134func clLike(q string) string { return "%" + clLikeEscaper.Replace(q) + "%" }135136// clQuery normalizes the optional free-text filter of a list.137func clQuery(q *string) (string, error) {138 if q == nil {139 return "", nil140 }141 s := strings.TrimSpace(*q)142 if utf8.RuneCountInString(s) > 120 {143 return "", clInvalid("q", "must be at most 120 characters")144 }145 if !clPrintable(s) {146 return "", clInvalid("q", "contains control characters")147 }148 return s, nil149}150151func clPrintable(s string) bool {152 if !utf8.ValidString(s) {153 return false154 }155 for _, r := range s {156 if unicode.IsControl(r) {157 return false158 }159 }160 return true161}162163// clText validates an optional human-entered string field.164func clText(field string, v *string, min, max int) (string, error) {165 if v == nil {166 return "", nil167 }168 s := strings.TrimSpace(*v)169 n := utf8.RuneCountInString(s)170 if n < min || n > max || !clPrintable(s) {171 if min > 0 {172 return "", clInvalid(field, "must be "+itoaRange(min, max)+" printable characters")173 }174 return "", clInvalid(field, "must be at most "+itoaInt(max)+" printable characters")175 }176 return s, nil177}178179func itoaInt(n int) string {180 b, _ := json.Marshal(n)181 return string(b)182}183184func itoaRange(a, b int) string { return itoaInt(a) + " to " + itoaInt(b) }185186// ── Freshness (DESIGN-BRIEF §6) ────────────────────────────────────────────187188// clFresh classifies the age of the last contact with a node. A node that was189// never seen is offline.190func (c *core) clFresh(now time.Time, seen *time.Time) Freshness {191 if seen == nil {192 return FreshnessOffline193 }194 age := now.Sub(*seen)195 switch {196 case age < c.Cfg.FreshAfter:197 return FreshnessFresh198 case age <= c.Cfg.OfflineAfter:199 return FreshnessStale200 }201 return FreshnessOffline202}203204// clFreshArgs are the three leading parameters ($1 now, $2 fresh-after205// seconds, $3 offline-after seconds) of every query built on clNodeFrom.206func (c *core) clFreshArgs(now time.Time) []any {207 return []any{now, c.Cfg.FreshAfter.Seconds(), c.Cfg.OfflineAfter.Seconds()}208}209210// clAvail is the availability of a value that WAS reported, given how old the211// report is.212func clAvail(f Freshness) Availability {213 switch f {214 case FreshnessFresh:215 return AvailabilityAvailable216 case FreshnessStale:217 return AvailabilityStale218 }219 return AvailabilityOffline220}221222// ── Resource-scoped access ─────────────────────────────────────────────────223224// clAccess answers permission questions for the current session against the225// grants loaded once for the request.226type clAccess struct {227 sub authz.Subject228 grants []authz.Grant229}230231func (c *core) clAccessFor(ctx context.Context) (*clAccess, error) {232 p := principalFrom(ctx)233 if p.Session == nil {234 return nil, httpx.ErrUnauthenticated235 }236 grants, err := c.loadGrants(ctx)237 if err != nil {238 return nil, err239 }240 return &clAccess{sub: p.Session.Subject(), grants: grants}, nil241}242243// can decides perm on a resource described by its facets (none = any resource).244func (a *clAccess) can(perm authz.Permission, facets ...authz.Resource) bool {245 return authz.DecideFacets(a.sub, perm, facets, a.grants)246}247248// scoped reports whether a resource-scoped grant on perm concerns this249// subject: only then do list endpoints have to decide row by row.250func (a *clAccess) scoped(perm authz.Permission) bool {251 for _, g := range a.grants {252 if g.Permission != perm || g.ResourceKind == "" {253 continue254 }255 if (g.SubjectKind == "user" && g.Subject == a.sub.UserID) || (g.SubjectKind == "role" && g.Subject == string(a.sub.Role)) {256 return true257 }258 }259 return false260}261262// clNodeFacets are the ways a grant can designate a node.263func clNodeFacets(id uuid.UUID, site string, tags []string) []authz.Resource {264 out := make([]authz.Resource, 0, 2+len(tags))265 out = append(out, authz.Resource{Kind: "node", ID: id.String()}, authz.Resource{Kind: "site", ID: site})266 for _, t := range tags {267 out = append(out, authz.Resource{Kind: "tag", ID: t})268 }269 return out270}271272// clServiceFacets: a service is designated by its own id or through its node.273func clServiceFacets(id, nodeID uuid.UUID, site string, tags []string) []authz.Resource {274 return append([]authz.Resource{{Kind: "service", ID: id.String()}}, clNodeFacets(nodeID, site, tags)...)275}276277// clAuthorizeWrite refuses (403, audited) a mutation the session may not278// perform on this particular resource.279func (c *core) clAuthorizeWrite(ctx context.Context, acc *clAccess, perm authz.Permission, target authz.Resource, facets []authz.Resource) error {280 if acc.can(perm, facets...) {281 return nil282 }283 c.auditDenied(ctx, principalFrom(ctx), string(perm), target)284 return httpx.ErrForbidden.With("permission", string(perm))285}286287// ── Metric catalog ─────────────────────────────────────────────────────────288289type clMetric struct {290 ID int16291 Name string292 Unit string293 Kind string294 IntervalS int295 Labeled bool296 Source string297 Description string298}299300type clCatalog struct {301 list []clMetric302 byName map[string]clMetric303}304305type clCatalogState struct {306 mu sync.Mutex307 seeded bool308 cat *clCatalog309 at time.Time310}311312// One catalog cache per database (tests run several servers in one process).313var clCatalogs sync.Map // *pgxpool.Pool -> *clCatalogState314315const clCatalogTTL = time.Minute316317// clCatalogFor returns the metric catalog. The table is seeded from318// protocol.Catalog on first use with an idempotent upsert, so the API never319// depends on telemetry-ingest having started first; it is then read from the320// database, which is what ingest keys the samples by.321func (c *core) clCatalogFor(ctx context.Context) (*clCatalog, error) {322 v, _ := clCatalogs.LoadOrStore(c.Pool, &clCatalogState{})323 st := v.(*clCatalogState)324 st.mu.Lock()325 defer st.mu.Unlock()326 if st.cat != nil && time.Since(st.at) < clCatalogTTL {327 return st.cat, nil328 }329 if !st.seeded {330 if err := clSeedCatalog(ctx, c.Pool); err != nil {331 return nil, err332 }333 st.seeded = true334 }335 rows, err := c.Pool.Query(ctx, `select id, name, unit, kind, interval_s, labeled, source, description from metric_catalog order by id`)336 if err != nil {337 return nil, err338 }339 list, err := pgx.CollectRows(rows, func(r pgx.CollectableRow) (clMetric, error) {340 var m clMetric341 err := r.Scan(&m.ID, &m.Name, &m.Unit, &m.Kind, &m.IntervalS, &m.Labeled, &m.Source, &m.Description)342 return m, err343 })344 if err != nil {345 return nil, err346 }347 cat := &clCatalog{list: list, byName: make(map[string]clMetric, len(list))}348 for _, m := range list {349 cat.byName[m.Name] = m350 }351 st.cat, st.at = cat, time.Now()352 return cat, nil353}354355func clSeedCatalog(ctx context.Context, pool *pgxpool.Pool) error {356 n := len(protocol.Catalog)357 ids, names, units, kinds := make([]int16, n), make([]string, n), make([]string, n), make([]string, n)358 intervals, labeled, sources, descs := make([]int32, n), make([]bool, n), make([]string, n), make([]string, n)359 for i, m := range protocol.Catalog {360 ids[i], names[i], units[i], kinds[i] = m.ID, m.Name, m.Unit, m.Kind361 intervals[i], labeled[i], sources[i], descs[i] = int32(m.IntervalS), m.Labeled, m.Source, m.Description362 }363 _, err := pool.Exec(ctx, `insert into metric_catalog(id, name, unit, kind, interval_s, labeled, source, description)364 select * from unnest($1::smallint[], $2::text[], $3::text[], $4::text[], $5::int[], $6::boolean[], $7::text[], $8::text[])365 on conflict (id) do update set name=excluded.name, unit=excluded.unit, kind=excluded.kind, interval_s=excluded.interval_s,366 labeled=excluded.labeled, source=excluded.source, description=excluded.description`,367 ids, names, units, kinds, intervals, labeled, sources, descs)368 return err369}370371// clLimitation is the documented reason a metric may be missing, if any.372func clLimitation(name string) *string {373 if m, ok := protocol.MetricByName(name); ok && m.Limits != "" {374 return &m.Limits375 }376 return nil377}378379// ── Small conversions ──────────────────────────────────────────────────────380381func clF32(v *float64) *float32 {382 if v == nil {383 return nil384 }385 f := float32(*v)386 return &f387}388389func clNonEmpty(s *string) *string {390 if s == nil || *s == "" {391 return nil392 }393 return s394}395396// clNumber reads a numeric member of a JSON object decoded with UseNumber or397// as float64. Anything else is "not reported".398func clNumber(m map[string]any, key string) (float64, bool) {399 switch v := m[key].(type) {400 case float64:401 return v, true402 case json.Number:403 f, err := v.Float64()404 return f, err == nil405 }406 return 0, false407}408409// clValues decodes node_state.values. telemetry-ingest stores a labeled410// metric as a nested object ("net.rx": {"en0": 1.0}); the rest of this411// package addresses labeled values by the flat key name{label}, so nested412// objects are flattened here (flat keys, if ever present, are kept as is).413func clValues(raw []byte) map[string]any {414 in := clObject(raw)415 out := make(map[string]any, len(in))416 for k, v := range in {417 if sub, ok := v.(map[string]any); ok {418 for label, lv := range sub {419 out[k+"{"+label+"}"] = lv420 }421 continue422 }423 out[k] = v424 }425 return out426}427428func clObject(raw []byte) map[string]any {429 m := map[string]any{}430 if len(raw) > 0 {431 _ = json.Unmarshal(raw, &m)432 }433 if m == nil {434 m = map[string]any{}435 }436 return m437}438439func clStringMap(raw []byte) map[string]string {440 out := map[string]string{}441 for k, v := range clObject(raw) {442 if s, ok := v.(string); ok {443 out[k] = s444 }445 }446 return out447}448