@vxil/feature-configs 0.1.0

package/src/readmodels.ts

@@ -0,0 +1,248 @@
+// cms-rel B5/E config-write gates (docs/cms-relational-depth-options.md §3/§4)
+// — the hooks.ts sibling: PURE structural validation of the `readModels` and
+// `cdc` bags at config-write time (the anti-malice-gate pattern). The grammar
+// (fn/rank allow-lists, arity caps, window bounds, dotted-term shape) is
+// closed HERE, before a spec can ever be published to KV; collection/field/
+// slot EXISTENCE is checked at runtime by cms-v1 (the field list is
+// per-collection DB data, not known here) — the same split the hooks gate
+// documents. This package is typebox-only, so the checks are a pure mirror of
+// workers/cms-v1/src/relational.ts (the publicHttpsUrlError precedent).
+
+const NAME_RE = /^[a-z][a-z0-9_]{0,62}$/;
+/** own-field or ONE-hop dotted key (`channel.visibility`, `channel.$status`) */
+const TERM_KEY_RE = /^[$]?[a-z][a-z0-9_]{0,62}(\.\$?[a-z][a-z0-9_]{0,62})?$/;
+const AGG_FNS = new Set(['count', 'sum', 'min', 'max', 'avg']);
+const RANK_FNS = new Set(['row_number', 'rank', 'percent_rank']);
+const CDC_EVENTS = new Set(['created', 'updated', 'deleted', 'published']);
+
+export const READ_MODEL_LIMITS = {
+  maxReadModels: 20,
+  maxAggregates: 4,
+  maxGroupBy: 2,
+  maxWindowDays: 366,
+  maxSpecBytes: 4096,
+  maxCdcRules: 25,
+} as const;
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Structural (grammar-only) check of ONE aggregate expression. */
+function aggExprErrors(where: string, raw: unknown): string[] {
+  if (!isObj(raw)) return [`${where}: must be { fn, field?, as? }`];
+  const errs: string[] = [];
+  if (typeof raw.fn !== 'string' || !AGG_FNS.has(raw.fn)) {
+    errs.push(`${where}/fn: must be one of ${[...AGG_FNS].join('|')}`);
+  }
+  if (raw.fn === 'count' && raw.field !== undefined) errs.push(`${where}: count takes no field`);
+  if (raw.fn !== 'count' && raw.fn !== undefined && typeof raw.field !== 'string') {
+    errs.push(`${where}/field: required for ${String(raw.fn)}`);
+  }
+  if (raw.field !== undefined && (typeof raw.field !== 'string' || !NAME_RE.test(raw.field))) {
+    errs.push(`${where}/field: must match ${NAME_RE.source}`);
+  }
+  if (raw.as !== undefined && (typeof raw.as !== 'string' || !NAME_RE.test(raw.as))) {
+    errs.push(`${where}/as: must match ${NAME_RE.source}`);
+  }
+  return errs;
+}
+
+function windowErrors(where: string, raw: unknown): string[] {
+  if (raw === undefined) return [];
+  if (!isObj(raw)) return [`${where}: must be { field, sinceDays } or { field, since, until? }`];
+  const errs: string[] = [];
+  if (typeof raw.field !== 'string' || !NAME_RE.test(raw.field)) {
+    errs.push(`${where}/field: required (a datetime field or created_at/updated_at/published_at)`);
+  }
+  if (raw.sinceDays !== undefined) {
+    if (!Number.isInteger(raw.sinceDays) || (raw.sinceDays as number) < 1
+      || (raw.sinceDays as number) > READ_MODEL_LIMITS.maxWindowDays) {
+      errs.push(`${where}/sinceDays: must be 1–${READ_MODEL_LIMITS.maxWindowDays}`);
+    }
+  } else if (raw.since !== undefined) {
+    if (typeof raw.since !== 'string' || Number.isNaN(Date.parse(raw.since))) {
+      errs.push(`${where}/since: must be an ISO datetime`);
+    }
+    if (raw.until !== undefined
+      && (typeof raw.until !== 'string' || Number.isNaN(Date.parse(raw.until)))) {
+      errs.push(`${where}/until: must be an ISO datetime`);
+    }
+  } else {
+    errs.push(`${where}: needs sinceDays or since`);
+  }
+  return errs;
+}
+
+function filterErrors(where: string, raw: unknown): string[] {
+  if (raw === undefined) return [];
+  if (!isObj(raw)) return [`${where}: must be a JSON object`];
+  const errs: string[] = [];
+  let dotted = 0;
+  const dottedPrefixes = new Set<string>();
+  for (const key of Object.keys(raw)) {
+    if (!TERM_KEY_RE.test(key)) {
+      errs.push(`${where}/${key}: not a valid field or one-hop dotted key`);
+      continue;
+    }
+    const dot = key.indexOf('.');
+    if (dot > 0) {
+      dotted += 1;
+      dottedPrefixes.add(key.slice(0, dot));
+    }
+  }
+  if (dotted > 4) errs.push(`${where}: at most 4 dotted (joined) terms`);
+  if (dottedPrefixes.size > 1) {
+    errs.push(`${where}: dotted terms must reference ONE relation (got ${[...dottedPrefixes].join(', ')})`);
+  }
+  return errs;
+}
+
+/**
+ * Structural validation of a declared read-model `spec` — shared by the
+ * config-write gate here and re-exported for anyone needing the pure check.
+ * `kind` selects the §3.1 (aggregate) or §4.1 (rank) grammar.
+ */
+export function validateReadModelSpecShape(
+  where: string,
+  kind: 'aggregate' | 'rank',
+  spec: unknown,
+): string[] {
+  if (!isObj(spec)) return [`${where}: spec must be an object`];
+  if (JSON.stringify(spec).length > READ_MODEL_LIMITS.maxSpecBytes) {
+    return [`${where}: serialized spec exceeds ${READ_MODEL_LIMITS.maxSpecBytes} bytes`];
+  }
+  const errs: string[] = [];
+  if (spec.limit !== undefined) {
+    errs.push(`${where}/limit: a declared read-model carries no limit (materialization uses the platform cap)`);
+  }
+  errs.push(...filterErrors(`${where}/filter`, spec.filter));
+  errs.push(...windowErrors(`${where}/window`, spec.window));
+  if (kind === 'aggregate') {
+    if (!Array.isArray(spec.aggregates) || spec.aggregates.length === 0
+      || spec.aggregates.length > READ_MODEL_LIMITS.maxAggregates) {
+      errs.push(`${where}/aggregates: must be 1–${READ_MODEL_LIMITS.maxAggregates} expressions`);
+    } else {
+      spec.aggregates.forEach((a, i) => errs.push(...aggExprErrors(`${where}/aggregates/${i}`, a)));
+    }
+    if (spec.groupBy !== undefined) {
+      if (!Array.isArray(spec.groupBy) || spec.groupBy.length > READ_MODEL_LIMITS.maxGroupBy
+        || !spec.groupBy.every((g) => typeof g === 'string' && NAME_RE.test(g))) {
+        errs.push(`${where}/groupBy: must be ≤${READ_MODEL_LIMITS.maxGroupBy} field names`);
+      }
+    }
+    if (spec.sort !== undefined && typeof spec.sort !== 'string') {
+      errs.push(`${where}/sort: must be a string`);
+    }
+  } else {
+    if (typeof spec.groupBy !== 'string' || !NAME_RE.test(spec.groupBy)) {
+      errs.push(`${where}/groupBy: required (the ranked entity's field name)`);
+    }
+    if (spec.metric !== undefined) errs.push(...aggExprErrors(`${where}/metric`, spec.metric));
+    if (typeof spec.rank !== 'string' || !RANK_FNS.has(spec.rank)) {
+      errs.push(`${where}/rank: must be one of ${[...RANK_FNS].join('|')}`);
+    }
+    if (spec.partitionBy !== undefined
+      && (typeof spec.partitionBy !== 'string' || !NAME_RE.test(spec.partitionBy))) {
+      errs.push(`${where}/partitionBy: must be a field name`);
+    }
+    if (spec.direction !== undefined && spec.direction !== 'asc' && spec.direction !== 'desc') {
+      errs.push(`${where}/direction: must be 'asc' or 'desc'`);
+    }
+  }
+  return errs;
+}
+
+/** Shape of one declared read-model (mirrors the CmsConfigSchema Record). */
+interface ReadModelDefLike {
+  collection?: string;
+  kind?: string;
+  spec?: unknown;
+  materialize?: { cron?: string; to?: string };
+  enabled?: boolean;
+}
+
+/** 5-field cron shape (jobs-v1 owns real parsing; this rejects garbage early). */
+const CRON_RE = /^\s*\S+\s+\S+\s+\S+\s+\S+\s+\S+\s*$/;
+
+/** Cross-field rule for CmsConfig.readModels (called from validateFeatureConfig). */
+export function validateReadModelsConfig(
+  readModels: Record<string, ReadModelDefLike> | undefined,
+): string[] {
+  if (!readModels) return [];
+  const errs: string[] = [];
+  const names = Object.keys(readModels);
+  if (names.length > READ_MODEL_LIMITS.maxReadModels) {
+    errs.push(`/readModels: at most ${READ_MODEL_LIMITS.maxReadModels} read-models (got ${names.length})`);
+  }
+  for (const name of names) {
+    const where = `/readModels/${name}`;
+    if (!NAME_RE.test(name)) errs.push(`${where}: name must match ${NAME_RE.source}`);
+    const rm = readModels[name]!;
+    if (typeof rm.collection !== 'string' || !NAME_RE.test(rm.collection)) {
+      errs.push(`${where}/collection: must be a collection slug`);
+    }
+    if (rm.kind !== 'aggregate' && rm.kind !== 'rank') {
+      errs.push(`${where}/kind: must be 'aggregate' or 'rank'`);
+      continue;
+    }
+    errs.push(...validateReadModelSpecShape(`${where}/spec`, rm.kind, rm.spec));
+    if (rm.materialize !== undefined) {
+      if (!isObj(rm.materialize)) {
+        errs.push(`${where}/materialize: must be { cron, to }`);
+      } else {
+        if (typeof rm.materialize.to !== 'string' || !NAME_RE.test(rm.materialize.to)) {
+          errs.push(`${where}/materialize/to: must be a collection slug`);
+        }
+        if (typeof rm.materialize.cron !== 'string' || !CRON_RE.test(rm.materialize.cron)) {
+          errs.push(`${where}/materialize/cron: must be a 5-field cron expression`);
+        }
+      }
+    }
+  }
+  return errs;
+}
+
+/** Shape of one CDC rule (mirrors the CmsConfigSchema Record). */
+interface CdcRuleLike {
+  collection?: string;
+  channel?: string;
+  events?: unknown;
+  payload?: unknown;
+  enabled?: boolean;
+}
+
+const CHANNEL_RE = /^[a-zA-Z0-9:_.-]{1,128}$/;
+
+/** Cross-field rule for CmsConfig.cdc (called from validateFeatureConfig). */
+export function validateCdcConfig(
+  cdc: Record<string, CdcRuleLike> | undefined,
+): string[] {
+  if (!cdc) return [];
+  const errs: string[] = [];
+  const names = Object.keys(cdc);
+  if (names.length > READ_MODEL_LIMITS.maxCdcRules) {
+    errs.push(`/cdc: at most ${READ_MODEL_LIMITS.maxCdcRules} rules (got ${names.length})`);
+  }
+  for (const name of names) {
+    const where = `/cdc/${name}`;
+    if (!NAME_RE.test(name)) errs.push(`${where}: name must match ${NAME_RE.source}`);
+    const r = cdc[name]!;
+    if (typeof r.collection !== 'string' || !NAME_RE.test(r.collection)) {
+      errs.push(`${where}/collection: must be a collection slug`);
+    }
+    if (typeof r.channel !== 'string' || !CHANNEL_RE.test(r.channel)) {
+      errs.push(`${where}/channel: must match ${CHANNEL_RE.source}`);
+    }
+    if (r.events !== undefined) {
+      if (!Array.isArray(r.events) || r.events.length === 0
+        || !r.events.every((e) => typeof e === 'string' && CDC_EVENTS.has(e))) {
+        errs.push(`${where}/events: must be a non-empty subset of ${[...CDC_EVENTS].join('|')}`);
+      }
+    }
+    if (r.payload !== undefined && r.payload !== 'ids' && r.payload !== 'full') {
+      errs.push(`${where}/payload: must be 'ids' or 'full'`);
+    }
+  }
+  return errs;
+}