SPB Git

Repository Public

cluster_common.go 13.6 KB 448 lines go

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
Files main
Menu

Theme