@spfn/core 0.3.0-beta.24 → 0.3.0-beta.26

package/dist/state/index.js

@@ -0,0 +1,578 @@
+import { Type, Kind } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { defineEvent } from '@spfn/core/event';
+import { logger } from '@spfn/core/logger';
+import { defineRouter, route } from '@spfn/core/route';
+import { UnauthorizedError, ForbiddenError } from '@spfn/core/errors';
+
+// src/state/state-builder.ts
+var bindings = /* @__PURE__ */ new WeakMap();
+function resultSchema(def) {
+  return Type.Object(
+    {
+      value: def.value,
+      ...def.data ? { data: def.data } : {}
+    },
+    { additionalProperties: false }
+  );
+}
+function bindState(def, path) {
+  bindings.set(def, { path, resultSchema: resultSchema(def) });
+}
+function stateBinding(def) {
+  return bindings.get(def);
+}
+
+// src/state/state-event.ts
+var stateLogger = logger.child("@spfn/core:state");
+function stateEventName(id) {
+  return `state.${id}.changed`;
+}
+function pickKey(keySchema, source) {
+  const key = {};
+  for (const field of Object.keys(keySchema.properties)) {
+    const value = source[field];
+    if (typeof value !== "string") {
+      return void 0;
+    }
+    key[field] = value;
+  }
+  return key;
+}
+function readContext(def, subject, principal, key) {
+  if (!def.key) {
+    return { subject, principal };
+  }
+  return def.shared ? { principal, key } : { subject, principal, key };
+}
+function permissionContext(def, subject, principal, key) {
+  return def.key ? { subject, principal, key } : { subject, principal };
+}
+function requireBinding(def, what) {
+  const binding = stateBinding(def);
+  if (!binding) {
+    throw new Error(
+      `State "${def.id}" is in no defineStateRouter, so ${what} reaches nothing. The router subscribes the change signal and checks every read, and every builder call returns a new builder \u2014 an earlier one is never routed. Group the state with defineStateRouter and export the builder instance you grouped.`
+    );
+  }
+  return binding;
+}
+function assertResult(def, binding, result) {
+  const error = Value.Errors(binding.resultSchema, result).First();
+  if (error) {
+    throw new Error(
+      `State "${def.id}" read() returned a result its declaration does not allow: ${error.path || "(root)"} ${error.message}. Every response and frame is checked against .value() and .data(), so a client never receives a value the contract does not describe. Return { value${def.data ? ", data" : ""} } as declared.`
+    );
+  }
+}
+async function readSnapshot(def, ctx, at = (/* @__PURE__ */ new Date()).toISOString()) {
+  const binding = requireBinding(def, "a read");
+  const result = await def.read(ctx);
+  assertResult(def, binding, result);
+  return { at, ...result };
+}
+function toFrame(def, snapshot, subject, key) {
+  const frame = structuredClone(snapshot);
+  if (def.key) {
+    frame.key = { ...key };
+  }
+  if (!(def.key && def.shared)) {
+    frame.subject = subject;
+  }
+  return frame;
+}
+async function readAndPublish(def, event, subject, key, principal) {
+  const snapshot = await readSnapshot(def, readContext(def, subject, principal, key));
+  await event.emit(toFrame(def, snapshot, subject, key));
+  return snapshot;
+}
+function framePayloadSchema(def) {
+  return Type.Object({
+    at: Type.String(),
+    value: def.value ?? Type.Unknown(),
+    ...def.data ? { data: def.data } : {},
+    ...def.key ? { key: def.key } : {},
+    ...def.key && def.shared ? {} : { subject: Type.String() }
+  });
+}
+function subscribePredicate(def) {
+  return async ({ subject, principal, request }) => {
+    if (!def.key) {
+      return def.canRead ? def.canRead({ subject, principal }) : true;
+    }
+    const key = pickKey(def.key, request.query);
+    return key !== void 0 && def.canRead !== void 0 && def.canRead({ subject, principal, key });
+  };
+}
+function framePredicate(def) {
+  const fields = def.key ? Object.keys(def.key.properties) : [];
+  return (payload, { subject, request }) => subject !== void 0 && fields.every((field) => payload.key?.[field] === request.query[field]) && (payload.subject === void 0 || payload.subject === subject);
+}
+function createStateEvent(def) {
+  const event = defineEvent(stateEventName(def.id), framePayloadSchema(def)).canSubscribe(subscribePredicate(def)).filter(framePredicate(def));
+  if (def.contract) {
+    const { since, deprecatedIn, removedIn } = def.contract;
+    event.contract({
+      since,
+      ...deprecatedIn ? { deprecatedIn } : {},
+      ...removedIn ? { removedIn } : {}
+    });
+  }
+  return event;
+}
+function changedPayloadSchema(def) {
+  return Type.Object({
+    ...def.key?.properties,
+    ...def.key && def.shared ? {} : { subject: Type.String() }
+  });
+}
+function assertChangedPayload(def, schema, payload) {
+  const error = Value.Errors(schema, payload).First();
+  if (error) {
+    throw new Error(
+      `${def.id}.changed.emit() refused its payload: ${error.path || "(root)"} ${error.message}. The module re-reads exactly the subject and key the payload names, so a missing field cannot be guessed. Pass ${def.key ? "every key field" : "the subject"}${def.key && !def.shared ? " and the subject" : ""}.`
+    );
+  }
+}
+function createChangedSignal(def) {
+  const schema = changedPayloadSchema(def);
+  const event = defineEvent(`state.${def.id}.signal`, schema);
+  const emit = event.emit;
+  event.emit = (async (payload) => {
+    requireBinding(def, `${def.id}.changed.emit()`);
+    assertChangedPayload(def, schema, payload);
+    await emit(payload);
+  });
+  return event;
+}
+function signalTarget(def, payload) {
+  const subject = def.key && def.shared ? void 0 : payload.subject;
+  return { subject, key: def.key ? pickKey(def.key, payload) : void 0 };
+}
+async function onSignal(state, payload) {
+  const { subject, key } = signalTarget(state._definition, payload);
+  try {
+    await readAndPublish(state._definition, state._event, subject, key, void 0);
+  } catch (error) {
+    stateLogger.warn(`State "${state.id}" could not be re-read on its change signal; no frame was sent`, {
+      state: state.id,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+async function onChangedBy(state, event, schema, payload) {
+  const error = Value.Errors(schema, payload).First();
+  if (error) {
+    stateLogger.warn(`State "${state.id}" skipped an "${event.name}" payload that names no value to re-read`, {
+      state: state.id,
+      event: event.name,
+      error: `${error.path || "(root)"} ${error.message}`
+    });
+    return;
+  }
+  await onSignal(state, payload);
+}
+function subscribeChangeSignals(state) {
+  const schema = changedPayloadSchema(state._definition);
+  state.changed.subscribe((payload) => onSignal(state, payload));
+  state._definition.changedBy?.forEach((event) => event.subscribe((payload) => onChangedBy(state, event, schema, payload), { localOnly: true }));
+}
+
+// src/state/state-builder.ts
+var STATE_ID = /^[a-z][a-zA-Z0-9]*$/;
+var RESERVED_KEY_FIELDS = ["events", "token"];
+var StateBuilder = class _StateBuilder {
+  constructor(id, _definition) {
+    this.id = id;
+    this._definition = _definition;
+  }
+  changedSignal;
+  stateEvent;
+  /**
+   * Declare the key: one value per key (and per subject, unless `shared`).
+   * Fields are required strings: they travel as query parameters.
+   */
+  key(schema, options = {}) {
+    this.assertOnce("key", !!this._definition.key);
+    assertKeySchema(this.id, schema);
+    return this.with({ key: schema, shared: options.shared === true });
+  }
+  /** Declare the value schema. Required. */
+  value(schema) {
+    this.assertOnce("value", !!this._definition.value);
+    return this.with({ value: schema });
+  }
+  /** Declare data attached to the value. Optional. */
+  data(schema) {
+    this.assertOnce("data", !!this._definition.data);
+    return this.with({ data: schema });
+  }
+  /**
+   * Middleware for the two per-state routes, `get<Id>State` / `put<Id>State`.
+   * Not authorization: the snapshot and the SSE stream cannot run it, so a
+   * state with `.use()` must declare `.canRead()`. Calls add up.
+   */
+  use(middlewares) {
+    return this.with({ middlewares: [...this._definition.middlewares, ...middlewares] });
+  }
+  /** Server-level named middlewares the two per-state routes skip. Calls add up; `'*'` wins. Needs `.canRead()`, as `.use()`. */
+  skip(middlewareNames) {
+    const current = this._definition.skipMiddlewares ?? [];
+    const skipMiddlewares = current === "*" || middlewareNames === "*" ? "*" : [...current, ...middlewareNames];
+    return this.with({ skipMiddlewares });
+  }
+  /** Publish the read route, the write route and the event in the contract. */
+  contract(contract) {
+    this.assertOnce("contract", !!this._definition.contract);
+    return this.with({ contract });
+  }
+  /** Who may read. Required on a keyed state; checked on HTTP and at SSE connect. */
+  canRead(predicate) {
+    this.assertOnce("canRead", !!this._definition.canRead);
+    return this.with({ canRead: predicate });
+  }
+  /** Who may write. Absent → `canRead` decides. */
+  canWrite(predicate) {
+    this.assertOnce("canWrite", !!this._definition.canWrite);
+    return this.with({ canWrite: predicate });
+  }
+  /** The only source of a value. Required. */
+  read(fn) {
+    this.assertOnce("read", !!this._definition.read);
+    return this.with({ read: fn });
+  }
+  /**
+   * Derive `PUT <path>/<id>`. `fn` runs the command; the value the route
+   * answers and broadcasts is re-read afterwards, never taken from `input`.
+   */
+  write(input, fn, options = {}) {
+    this.assertOnce("write", !!this._definition.write);
+    return this.with({ write: { input, fn, options } });
+  }
+  /**
+   * Domain events whose payload names a changed value of this state, treated
+   * like `changed.emit` with that payload: keyless `subject`, keyed the key
+   * fields and `subject`, shared the key fields. The router subscribes them
+   * and refuses one whose payload schema lacks a field.
+   */
+  changedBy(events) {
+    this.assertOnce("changedBy", !!this._definition.changedBy);
+    return this.with({ changedBy: [...events] });
+  }
+  /**
+   * The change signal. Emit it after the change is committed; the module
+   * re-reads the value and sends the frame. Refused on a builder no router
+   * grouped — export the instance you passed to `defineStateRouter`.
+   */
+  get changed() {
+    this.changedSignal ??= createChangedSignal(this._definition);
+    return this.changedSignal;
+  }
+  /** Internal: the SSE event `state.<id>.changed` (`defineStateRouter(...).events`). */
+  get _event() {
+    this.stateEvent ??= createStateEvent(this._definition);
+    return this.stateEvent;
+  }
+  /**
+   * Activate the state's event on `subject`'s open connections and send it
+   * the current value at once. On a keyed state only the connections that
+   * declared `key` are opened. Does not consult `canRead`.
+   */
+  async grant(target) {
+    const { subject, key } = target;
+    requireBinding(this._definition, `${this.id}.grant()`);
+    this.assertGrantKey(key);
+    const declared = this.declaredKey("grant", key);
+    await this._event.grant(subject, declared && { query: declared });
+    await readAndPublish(this._definition, this._event, subject, declared, void 0);
+  }
+  /**
+   * Deactivate the state's event on `subject`'s open connections: on a keyed
+   * state those that declared `key`, or every one when no key is given.
+   */
+  async revoke(target) {
+    const { subject, key } = target;
+    const declared = this.declaredKey("revoke", key);
+    await this._event.revoke(subject, declared && { query: declared });
+  }
+  /** A keyed grant opens one key: without it there is no key to open and no value to send. */
+  assertGrantKey(key) {
+    if (this._definition.key && !key) {
+      throw new Error(
+        `State "${this.id}" .grant() was called without a key. A keyed grant opens exactly one key \u2014 every connection of the subject on any key would otherwise be opened, including keys canRead refused. Pass { subject, key }.`
+      );
+    }
+  }
+  /**
+   * The declared key fields of `key`, checked against `.key()`: an empty or
+   * partial key would match every connection of the subject. A field the
+   * declaration does not name is dropped, never matched on — so the check
+   * runs on a fresh object of the declared fields, never `.key()` itself: a
+   * key declared `additionalProperties: false` would otherwise refuse it.
+   * The fresh object keeps `.key()`'s `required`, and a key that still picks
+   * to nothing is refused: `undefined` here would mean every connection.
+   */
+  declaredKey(method, key) {
+    const schema = this._definition.key;
+    if (!schema || key === void 0) {
+      return void 0;
+    }
+    const error = Value.Errors({ ...Type.Object(schema.properties), required: schema.required }, key).First();
+    if (error) {
+      this.refuseKey(method, `${error.path || "(root)"} ${error.message}`);
+    }
+    return pickKey(schema, key) ?? this.refuseKey(method, "(root) a declared key field is missing or not a string");
+  }
+  refuseKey(method, reason) {
+    throw new Error(
+      `State "${this.id}" .${method}() refused its key: ${reason}. A keyed ${method} reaches exactly the connections on one key, so every key field must be named.`
+    );
+  }
+  with(changes) {
+    return new _StateBuilder(this.id, { ...this._definition, ...changes });
+  }
+  assertOnce(method, declared) {
+    if (declared) {
+      throw new Error(
+        `State "${this.id}" already declares .${method}(). A state is declared once, so a second declaration would silently replace the first. Declare .${method}() once.`
+      );
+    }
+  }
+};
+function assertKeySchema(id, schema) {
+  if (schema[Kind] !== "Object") {
+    throw new Error(
+      `State "${id}" .key() takes an object schema, got ${String(schema[Kind])}. Each key field becomes a named query parameter and a field of the frame's key. Wrap the field: .key(Type.Object({ workspaceId: Type.String() })).`
+    );
+  }
+  const fields = Object.entries(schema.properties);
+  if (fields.length === 0) {
+    throw new Error(
+      `State "${id}" .key() declares no field. A key with no field names nothing to read by. Drop .key() for one value per subject.`
+    );
+  }
+  fields.forEach(([field, fieldSchema]) => assertKeyField(id, schema, field, fieldSchema));
+}
+function assertKeyField(id, schema, field, fieldSchema) {
+  if (RESERVED_KEY_FIELDS.includes(field)) {
+    throw new Error(
+      `State "${id}" key field "${field}" is reserved. The SSE stream reads ${RESERVED_KEY_FIELDS.map((name) => `"${name}"`).join(" and ")} from the connect query that also carries the key, so the field would be read as both. Rename the field.`
+    );
+  }
+  if (fieldSchema.type !== "string" || !(schema.required ?? []).includes(field)) {
+    throw new Error(
+      `State "${id}" key field "${field}" is not a required string. A key travels as a query parameter, which is always a string, and the SSE filter compares it with the connect query as one \u2014 a number would never match, and a missing field names no value. Declare it ${field}: Type.String().`
+    );
+  }
+}
+function defineState(id) {
+  if (!STATE_ID.test(id)) {
+    throw new Error(
+      `defineState("${id}"): a state id must match ${STATE_ID}. It becomes part of the route names get<Id>State / put<Id>State and of the event name state.<id>.changed. Use a lowerCamel identifier, e.g. "myState".`
+    );
+  }
+  return new StateBuilder(id, { id, shared: false, middlewares: [] });
+}
+var defaultSubject = (c) => c.get("auth")?.userId ?? null;
+function stateRouteName(method, id) {
+  return `${method}${id[0].toUpperCase()}${id.slice(1)}State`;
+}
+function requireSubject(c, resolveSubject) {
+  const subject = resolveSubject(c);
+  if (!subject) {
+    throw new UnauthorizedError({ message: "A state is read for a subject, and this request carries none" });
+  }
+  return subject;
+}
+async function assertPermitted(def, can, ctx) {
+  const predicate = can === "canWrite" ? def.canWrite ?? def.canRead : def.canRead;
+  if (predicate && !await predicate(ctx)) {
+    throw new ForbiddenError({ message: `${can === "canWrite" ? "Writing" : "Reading"} state "${def.id}" is not permitted` });
+  }
+}
+function responseSchema(def) {
+  return Type.Object({
+    at: Type.String(),
+    value: def.value,
+    ...def.data ? { data: def.data } : {}
+  });
+}
+function routeContract(def, write) {
+  if (!def.contract) {
+    return void 0;
+  }
+  const own = write ? stripUndefined(def.write.options) : {};
+  return stripUndefined({ ...def.contract, ...own, response: responseSchema(def) });
+}
+function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
+}
+function stateRoute(def, method, path, input) {
+  const contract = routeContract(def, method === "put");
+  const builder = route[method](path).input(input).use(def.middlewares);
+  const skipped = def.skipMiddlewares ? builder.skip(def.skipMiddlewares) : builder;
+  return contract ? skipped.contract(contract) : skipped;
+}
+function keyInput(def) {
+  return def.key ? { query: def.key } : {};
+}
+function readRoute(state, path, resolveSubject) {
+  const def = state._definition;
+  return stateRoute(def, "get", `${path}/${def.id}`, keyInput(def)).handler(async (c) => {
+    const subject = requireSubject(c.raw, resolveSubject);
+    const principal = c.raw.get("auth");
+    const key = def.key ? pickKey(def.key, (await c.data()).query) : void 0;
+    await assertPermitted(def, "canRead", permissionContext(def, subject, principal, key));
+    return readSnapshot(def, readContext(def, subject, principal, key));
+  });
+}
+function writeRoute(state, path, resolveSubject) {
+  const def = state._definition;
+  const write = def.write;
+  return stateRoute(def, "put", `${path}/${def.id}`, { body: write.input, ...keyInput(def) }).handler(async (c) => {
+    const subject = requireSubject(c.raw, resolveSubject);
+    const principal = c.raw.get("auth");
+    const { body, query } = await c.data();
+    const key = def.key ? pickKey(def.key, query) : void 0;
+    await assertPermitted(def, "canWrite", permissionContext(def, subject, principal, key));
+    await write.fn({ ...readContext(def, subject, principal, key), input: body });
+    return readAndPublish(def, state._event, subject, key, principal);
+  });
+}
+function snapshotQuery(states) {
+  const fields = {};
+  for (const state of states) {
+    for (const [field, schema] of Object.entries(state._definition.key?.properties ?? {})) {
+      fields[field] = Type.Optional(schema);
+    }
+  }
+  return Type.Object(fields);
+}
+async function snapshotEntry(def, subject, principal, query, at) {
+  const key = def.key ? pickKey(def.key, query) : void 0;
+  if (def.key && !key) {
+    return void 0;
+  }
+  if (def.canRead && !await def.canRead(permissionContext(def, subject, principal, key))) {
+    return void 0;
+  }
+  const { value, data } = await readSnapshot(def, readContext(def, subject, principal, key), at);
+  return def.data ? { value, data } : { value };
+}
+function stateManifest(states) {
+  return Object.fromEntries(states.map((state) => [state.id, {
+    key: Object.keys(state._definition.key?.properties ?? {}),
+    write: state._definition.write !== void 0
+  }]));
+}
+function snapshotRoute(states, manifest, path, resolveSubject) {
+  return route.get(path).input({ query: snapshotQuery(states) }).handler(async (c) => {
+    const subject = requireSubject(c.raw, resolveSubject);
+    const principal = c.raw.get("auth");
+    const { query } = await c.data();
+    const at = (/* @__PURE__ */ new Date()).toISOString();
+    const entries = await Promise.all(states.map((state) => snapshotEntry(state._definition, subject, principal, query, at)));
+    return {
+      at,
+      states: Object.fromEntries(states.map((state, index) => [state.id, entries[index]]).filter(([, entry]) => entry !== void 0)),
+      manifest
+    };
+  });
+}
+
+// src/state/state-router.ts
+function defineStateRouter(states, options = {}) {
+  const path = options.path ?? "/state";
+  const list = Object.values(states);
+  assertPath(path);
+  list.forEach(assertRoutable);
+  assertDistinctIds(list);
+  list.forEach((state) => assertNotRouted(state, path));
+  list.forEach((state) => bindState(state._definition, path));
+  list.forEach(subscribeChangeSignals);
+  return {
+    router: defineRouter(deriveRoutes(list, path, options.subject ?? defaultSubject)),
+    events: Object.fromEntries(list.map((state) => [stateEventName(state.id), state._event])),
+    states
+  };
+}
+function deriveRoutes(states, path, resolveSubject) {
+  const routes = {};
+  for (const state of states) {
+    routes[stateRouteName("get", state.id)] = readRoute(state, path, resolveSubject);
+    if (state._definition.write) {
+      routes[stateRouteName("put", state.id)] = writeRoute(state, path, resolveSubject);
+    }
+  }
+  routes.getStates = snapshotRoute(states, stateManifest(states), path, resolveSubject);
+  return routes;
+}
+function assertPath(path) {
+  if (!path.startsWith("/") || path.length > 1 && path.endsWith("/")) {
+    throw new Error(
+      `defineStateRouter(..., { path: "${path}" }) is not an absolute path without a trailing slash. The routes are mounted at <path> and <path>/<id>. Write it as "/state".`
+    );
+  }
+}
+function assertRoutable(state) {
+  const def = state._definition;
+  const missing = !def.value ? ".value()" : !def.read ? ".read()" : void 0;
+  if (missing) {
+    throw new Error(
+      `defineStateRouter: state "${state.id}" declares no ${missing}. A state answers with the value its read returns, so both are required. Add ${missing} to defineState('${state.id}').`
+    );
+  }
+  if (def.key && !def.canRead) {
+    throw new Error(
+      `defineStateRouter: keyed state "${state.id}" declares no .canRead(). The key comes from the request, so without it any subject could read any key. Add .canRead(({ subject, key }) => ...).`
+    );
+  }
+  assertMiddlewareIsNotAuthorization(state);
+  def.changedBy?.forEach((event) => assertChangedBy(state, event));
+  if (def.write && !def.contract && def.write.options.since) {
+    throw new Error(
+      `defineStateRouter: state "${state.id}" gives .write(..., { since: '${def.write.options.since}' }) but declares no .contract(), so there is nothing to fall back from: the write route would have a version but no auth profile, and the read route and the event would not be contracted at all. Add .contract({ since, ... }) to the state, or drop since from the write.`
+    );
+  }
+}
+function assertMiddlewareIsNotAuthorization(state) {
+  const def = state._definition;
+  if ((def.middlewares.length > 0 || def.skipMiddlewares) && !def.canRead) {
+    throw new Error(
+      `defineStateRouter: state "${state.id}" declares .use() or .skip() but no .canRead(). Middleware reaches only ${stateRouteName("get", state.id)} / ${stateRouteName("put", state.id)} \u2014 never the snapshot route or the SSE stream \u2014 so it cannot authorize. Authorization belongs in .canRead(), which is enforced on the read route, the snapshot and the stream. A state that needs middleware only for, say, rate limiting declares .canRead(() => true) to say so.`
+    );
+  }
+}
+function assertChangedBy(state, event) {
+  const payload = event.schema;
+  const signal = changedPayloadSchema(state._definition);
+  const missing = Object.keys(signal.properties).find((field) => !payload?.properties?.[field] || !(payload.required ?? []).includes(field));
+  if (missing) {
+    throw new Error(
+      `defineStateRouter: state "${state.id}" lists event "${event.name}" in .changedBy(), but its payload schema has no required field "${missing}". Its payload is read like ${state.id}.changed.emit(), which names ${Object.keys(signal.properties).join(", ")}. Add the field to the event, or emit ${state.id}.changed instead.`
+    );
+  }
+}
+function assertDistinctIds(states) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const state of states) {
+    if (seen.has(state.id)) {
+      throw new Error(
+        `defineStateRouter: two states have the id "${state.id}". Both would derive the routes ${stateRouteName("get", state.id)} and the event ${stateEventName(state.id)}, and one would shadow the other. Rename one.`
+      );
+    }
+    seen.add(state.id);
+  }
+}
+function assertNotRouted(state, path) {
+  const other = stateBinding(state._definition)?.path;
+  if (other !== void 0) {
+    throw new Error(
+      `defineStateRouter: state "${state.id}" is already in another state router (path ${other}, this one ${path}). Each router subscribes the state's change signal, so every change would be read and sent twice. Group each state in one router.`
+    );
+  }
+}
+
+export { StateBuilder, defineState, defineStateRouter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map