@spfn/core 0.3.0-beta.25 → 0.3.0-beta.27

package/dist/state/index.d.ts

@@ -21,6 +21,8 @@ interface StateShape {
     data: TSchema | undefined;
     input: TSchema | undefined;
     read: boolean;
+    /** Who the callbacks' `principal` is, from `.principal<P>()`; `unknown` until declared. */
+    principal: unknown;
 }
 /** The shape of `defineState(id)` before any call. */
 interface EmptyStateShape extends StateShape {
@@ -30,6 +32,7 @@ interface EmptyStateShape extends StateShape {
     data: undefined;
     input: undefined;
     read: false;
+    principal: unknown;
 }
 /** `T` with the fields of `U` replaced. */
 type WithShape<T extends StateShape, U extends Partial<StateShape>> = {
@@ -57,22 +60,38 @@ type StateResult<T extends StateShape> = T['data'] extends TSchema ? {
 type StateSnapshot<T extends StateShape> = Simplify<{
     at: string;
 } & StateResult<T>>;
-/** What `.canRead()` / `.canWrite()` decide on. */
+/**
+ * What `.canRead()` decides on. `principal` may be `undefined`: at SSE connect
+ * it is what `resolvePrincipal` returned.
+ */
 type PermissionContext<T extends StateShape> = T['key'] extends TObject ? {
     subject: string;
-    principal: unknown;
+    principal: T['principal'] | undefined;
     key: Static<T['key']>;
 } : {
     subject: string;
-    principal: unknown;
+    principal: T['principal'] | undefined;
 };
-/** What `read()` receives. A shared state's value does not depend on the subject, so it gets none. */
+/**
+ * What `.canWrite()` decides on. Only the write route asks it, and with
+ * `.principal()` declared that route refuses a request whose `auth` is
+ * `undefined` or `null` (401).
+ */
+type WritePermissionContext<T extends StateShape> = Simplify<Omit<PermissionContext<T>, 'principal'> & {
+    principal: T['principal'];
+}>;
+/**
+ * What `read()` receives. A shared state's value does not depend on the
+ * subject, so it gets none. `principal` may be `undefined`: the change
+ * signal's re-read has no request.
+ */
 type ReadContext<T extends StateShape> = T['key'] extends TObject ? T['shared'] extends true ? {
-    principal: unknown;
+    principal: T['principal'] | undefined;
     key: Static<T['key']>;
 } : PermissionContext<T> : PermissionContext<T>;
-/** What `write()` receives: the read context plus the validated input. */
-type WriteContext<T extends StateShape, I extends TSchema> = Simplify<ReadContext<T> & {
+/** What `write()` receives: the read context, the write route's principal and the validated input. */
+type WriteContext<T extends StateShape, I extends TSchema> = Simplify<Omit<ReadContext<T>, 'principal'> & {
+    principal: T['principal'];
     input: Static<I>;
 }>;
 /** The payload of `state.changed.emit()`: exactly what names the value to re-read. */
@@ -137,6 +156,8 @@ interface StateDefinition {
     id: string;
     key?: TObject;
     shared: boolean;
+    /** Whether `.principal()` was declared: the write route then refuses a request whose `auth` is `undefined` or `null`. */
+    principal: boolean;
     value?: TSchema;
     data?: TSchema;
     middlewares: (MiddlewareHandler | NamedMiddleware<string>)[];
@@ -204,6 +225,15 @@ declare class StateBuilder<TId extends string, T extends StateShape> {
     data<D extends TSchema>(schema: D): StateBuilder<TId, WithShape<T, {
         data: D;
     }>>;
+    /**
+     * Declare who the callbacks' `principal` is — what the app's auth
+     * middleware sets as `c.get('auth')`. Type-only, but for one rule: the write
+     * route refuses a request without a principal (401), so `.canWrite()` and
+     * `.write()` receive `P`; `.read()` and `.canRead()` receive `P | undefined`.
+     */
+    principal<P>(): StateBuilder<TId, WithShape<T, {
+        principal: P;
+    }>>;
     /**
      * 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
@@ -217,7 +247,7 @@ declare class StateBuilder<TId extends string, T extends StateShape> {
     /** Who may read. Required on a keyed state; checked on HTTP and at SSE connect. */
     canRead(predicate: (ctx: PermissionContext<T>) => boolean | Promise<boolean>): StateBuilder<TId, T>;
     /** Who may write. Absent → `canRead` decides. */
-    canWrite(predicate: (ctx: PermissionContext<T>) => boolean | Promise<boolean>): StateBuilder<TId, T>;
+    canWrite(predicate: (ctx: WritePermissionContext<T>) => boolean | Promise<boolean>): StateBuilder<TId, T>;
     /** The only source of a value. Required. */
     read(fn: (ctx: ReadContext<T>) => StateResult<T> | Promise<StateResult<T>>): StateBuilder<TId, WithShape<T, {
         read: true;
@@ -294,6 +324,24 @@ declare function defineState<TId extends string>(id: TId): StateBuilder<TId, Emp
 
 /** Who a request is for. `null` answers 401. */
 type SubjectResolver = (c: Context) => string | null;
+/**
+ * What the router gives the snapshot route `GET <path>` alone. A per-state
+ * route keeps its own state's `.use()` / `.skip()` / `.contract()`, and the
+ * SSE stream runs none of them.
+ */
+interface SnapshotRouteOptions {
+    /** Middleware for the snapshot route only. Not authorization: the stream never runs it (see README). */
+    use?: (MiddlewareHandler | NamedMiddleware<string>)[];
+    /** Server-level named middlewares the snapshot route skips; `'*'` skips every one. */
+    skip?: string[] | '*';
+    /** Publishes the snapshot route in the contract; the response schema is derived. */
+    contract?: StateContract;
+}
+/** What the browser cannot read from a type: every state, in declaration order, its key fields and whether it has a write. */
+type StatesManifest = Record<string, {
+    key: string[];
+    write: boolean;
+}>;
 
 /**
  * State Router
@@ -303,7 +351,12 @@ type SubjectResolver = (c: Context) => string | null;
  * subscribes each state's change signal — once, here.
  */
 
-interface StateRouterOptions {
+/**
+ * Where the router mounts, whom a request is for, and the snapshot route's own
+ * `use` / `skip` / `contract` (`SnapshotRouteOptions`) — those reach `GET <path>`
+ * only, never a per-state route or the SSE stream.
+ */
+interface StateRouterOptions extends SnapshotRouteOptions {
     /**
      * Where the routes are mounted: `GET <path>`, `GET|PUT <path>/<id>`.
      * @default '/state'
@@ -328,12 +381,22 @@ type WriteInput<S extends RoutableState> = KeyQuery<S> & {
 type WriteRoutes<S extends Record<string, RoutableState>> = {
     [K in keyof S as Shape<S[K]>['input'] extends TSchema ? `put${Capitalize<S[K]['id']>}State` : never]: RouteDef<WriteInput<S[K]>, {}, StateSnapshot<Shape<S[K]>>>;
 };
-/** What `GET <path>` answers: every state the subject may read and whose key the query carries. */
+/**
+ * What `GET <path>` answers: every state the subject may read and whose key
+ * the query carries, and the manifest of every state — its key fields and
+ * whether it has a write — in declaration order.
+ */
 type StatesSnapshot<S extends Record<string, RoutableState>> = {
     at: string;
     states: {
         [K in keyof S as S[K]['id']]?: StateResult<Shape<S[K]>>;
     };
+    manifest: {
+        [K in keyof S as S[K]['id']]: {
+            key: string[];
+            write: boolean;
+        };
+    };
 };
 /** The routes one state router derives, typed for `createApi` and the route map. */
 type StateRoutes<S extends Record<string, RoutableState>> = ReadRoutes<S> & WriteRoutes<S> & {
@@ -377,4 +440,4 @@ type InferStateInput<R extends StateRouter<any>, TId extends string> = Shape<Sta
  */
 declare function defineStateRouter<S extends Record<string, RoutableState>>(states: S, options?: StateRouterOptions): StateRouter<S>;
 
-export { type ChangedPayload, type GrantTarget, type InferStateInput, type InferStateKey, type InferStateValue, type PermissionContext, type ReadContext, type RevokeTarget, type RoutableState, StateBuilder, type StateContract, type StateEvents, type StateFrame, type StateKey, type StateResult, type StateRouter, type StateRouterOptions, type StateRoutes, type StateShape, type StateSnapshot, type StateValue, type StateWriteOptions, type StatesSnapshot, type SubjectResolver, type WriteContext, defineState, defineStateRouter };
+export { type ChangedPayload, type GrantTarget, type InferStateInput, type InferStateKey, type InferStateValue, type PermissionContext, type ReadContext, type RevokeTarget, type RoutableState, type SnapshotRouteOptions, StateBuilder, type StateContract, type StateEvents, type StateFrame, type StateKey, type StateResult, type StateRouter, type StateRouterOptions, type StateRoutes, type StateShape, type StateSnapshot, type StateValue, type StateWriteOptions, type StatesManifest, type StatesSnapshot, type SubjectResolver, type WriteContext, type WritePermissionContext, defineState, defineStateRouter };

package/dist/state/index.js

@@ -1,5 +1,6 @@
 import { Type, Kind } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
+import { getTransactionContext, onAfterCommit } from '@spfn/core/db';
 import { defineEvent } from '@spfn/core/event';
 import { logger } from '@spfn/core/logger';
 import { defineRouter, route } from '@spfn/core/route';
@@ -83,7 +84,12 @@ function toFrame(def, snapshot, subject, key) {
 }
 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));
+  const frame = toFrame(def, snapshot, subject, key);
+  if (getTransactionContext()) {
+    onAfterCommit(() => event.emit(frame));
+  } else {
+    await event.emit(frame);
+  }
   return snapshot;
 }
 function framePayloadSchema(def) {
@@ -154,7 +160,7 @@ async function onSignal(state, 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`, {
+    stateLogger.warn(`State "${state.id}" could not be re-read or published on its change signal; no frame was sent`, {
       state: state.id,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -207,6 +213,16 @@ var StateBuilder = class _StateBuilder {
     this.assertOnce("data", !!this._definition.data);
     return this.with({ data: schema });
   }
+  /**
+   * Declare who the callbacks' `principal` is — what the app's auth
+   * middleware sets as `c.get('auth')`. Type-only, but for one rule: the write
+   * route refuses a request without a principal (401), so `.canWrite()` and
+   * `.write()` receive `P`; `.read()` and `.canRead()` receive `P | undefined`.
+   */
+  principal() {
+    this.assertOnce("principal", this._definition.principal);
+    return this.with({ principal: true });
+  }
   /**
    * 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
@@ -371,7 +387,7 @@ function defineState(id) {
       `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: [] });
+  return new StateBuilder(id, { id, shared: false, principal: false, middlewares: [] });
 }
 var defaultSubject = (c) => c.get("auth")?.userId ?? null;
 function stateRouteName(method, id) {
@@ -384,19 +400,30 @@ function requireSubject(c, resolveSubject) {
   }
   return subject;
 }
+function writePrincipal(def, c) {
+  const principal = c.get("auth");
+  if (def.principal && principal == null) {
+    throw new UnauthorizedError({
+      message: `State "${def.id}" declares .principal(), and this request carries none`
+    });
+  }
+  return principal;
+}
 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) {
+function resultSchema2(def) {
   return Type.Object({
-    at: Type.String(),
     value: def.value,
     ...def.data ? { data: def.data } : {}
   });
 }
+function responseSchema(def) {
+  return Type.Object({ at: Type.String(), ...resultSchema2(def).properties });
+}
 function routeContract(def, write) {
   if (!def.contract) {
     return void 0;
@@ -431,7 +458,7 @@ function writeRoute(state, path, resolveSubject) {
   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 principal = writePrincipal(def, c.raw);
     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));
@@ -459,8 +486,28 @@ async function snapshotEntry(def, subject, principal, query, at) {
   const { value, data } = await readSnapshot(def, readContext(def, subject, principal, key), at);
   return def.data ? { value, data } : { value };
 }
-function snapshotRoute(states, path, resolveSubject) {
-  return route.get(path).input({ query: snapshotQuery(states) }).handler(async (c) => {
+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 snapshotResponseSchema(states) {
+  const manifestEntry = Type.Object({ key: Type.Array(Type.String()), write: Type.Boolean() });
+  return Type.Object({
+    at: Type.String(),
+    states: Type.Object(Object.fromEntries(states.map((state) => [state.id, Type.Optional(resultSchema2(state._definition))]))),
+    manifest: Type.Object(Object.fromEntries(states.map((state) => [state.id, manifestEntry])))
+  });
+}
+function snapshotBuilder(states, path, options) {
+  const builder = route.get(path).input({ query: snapshotQuery(states) });
+  const used = options.use?.length ? builder.use(options.use) : builder;
+  const skipped = options.skip ? used.skip(options.skip) : used;
+  return options.contract ? skipped.contract(stripUndefined({ ...options.contract, response: snapshotResponseSchema(states) })) : skipped;
+}
+function snapshotRoute(states, manifest, path, resolveSubject, options = {}) {
+  return snapshotBuilder(states, path, options).handler(async (c) => {
     const subject = requireSubject(c.raw, resolveSubject);
     const principal = c.raw.get("auth");
     const { query } = await c.data();
@@ -468,7 +515,8 @@ function snapshotRoute(states, path, resolveSubject) {
     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))
+      states: Object.fromEntries(states.map((state, index) => [state.id, entries[index]]).filter(([, entry]) => entry !== void 0)),
+      manifest
     };
   });
 }
@@ -479,17 +527,19 @@ function defineStateRouter(states, options = {}) {
   const list = Object.values(states);
   assertPath(path);
   list.forEach(assertRoutable);
+  assertSnapshotMiddlewareIsNotAuthorization(list, options);
   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)),
+    router: defineRouter(deriveRoutes(list, path, options)),
     events: Object.fromEntries(list.map((state) => [stateEventName(state.id), state._event])),
     states
   };
 }
-function deriveRoutes(states, path, resolveSubject) {
+function deriveRoutes(states, path, options) {
+  const resolveSubject = options.subject ?? defaultSubject;
   const routes = {};
   for (const state of states) {
     routes[stateRouteName("get", state.id)] = readRoute(state, path, resolveSubject);
@@ -497,7 +547,7 @@ function deriveRoutes(states, path, resolveSubject) {
       routes[stateRouteName("put", state.id)] = writeRoute(state, path, resolveSubject);
     }
   }
-  routes.getStates = snapshotRoute(states, path, resolveSubject);
+  routes.getStates = snapshotRoute(states, stateManifest(states), path, resolveSubject, options);
   return routes;
 }
 function assertPath(path) {
@@ -536,6 +586,14 @@ function assertMiddlewareIsNotAuthorization(state) {
     );
   }
 }
+function assertSnapshotMiddlewareIsNotAuthorization(states, options) {
+  const unguarded = states.find((state) => !state._definition.canRead);
+  if (((options.use?.length ?? 0) > 0 || options.skip) && unguarded) {
+    throw new Error(
+      `defineStateRouter: the router gives the snapshot route use or skip, but state "${unguarded.id}" declares no .canRead(). The snapshot's middleware never reaches the SSE stream, which serves the same state, so it cannot authorize. Authorization belongs in .canRead(); a state readable by every subject declares .canRead(() => true) to say so.`
+    );
+  }
+}
 function assertChangedBy(state, event) {
   const payload = event.schema;
   const signal = changedPayloadSchema(state._definition);