@fougere/core 0.12.4-alpha.0 → 0.12.6-alpha.0

package/src/dispatch/HandlerFacade.ts

@@ -88,7 +88,10 @@ export class HandlerFacade {
       );
     }
 
-    const invocation = Invocation.from(input);
+    const received = Invocation.from(input);
+    const state = received.crossed ? { ...received.state } : this.facade.state.judge(received.state, entity, op);
+    const invocation = received.withState(state);
+    const entered = { ...state };
     const context: OperationContext = {
       entity,
       frond: this.facade.frond,
@@ -98,7 +101,7 @@ export class HandlerFacade {
       invocation,
     };
 
-    return runMiddlewares(this.facade.middlewares(), context, () => this.answer(op, contract, context, invocation));
+    return runMiddlewares(this.facade.middlewares(), context, () => this.answer(op, contract, context, invocation, entered));
   }
 
   /**
@@ -110,8 +113,10 @@ export class HandlerFacade {
     contract: OperationContract,
     context: OperationContext,
     invocation: Invocation,
+    entered: Record<string, unknown>,
   ): Promise<unknown> {
-    const validated = validateInput(contract.input, invocation, this.handler.address, op);
+    const state = this.facade.state.judge(context.state, this.handler.address, op, entered);
+    const validated = validateInput(contract.input, { ...invocation, state }, this.handler.address, op);
     context.invocation = validated;
 
     const args = contract.binding ? await this.arguments.resolve(contract.binding, validated) : [];

package/src/index.ts

@@ -62,7 +62,7 @@ export { FougereError, ErrorCode, validationErrorsOf } from './contract.js';
 export type { AppMiddleware } from './wire/AppMiddleware.js';
 export type { AppNext } from './wire/AppNext.js';
 export type { OperationContext } from './wire/OperationContext.js';
-export { assertIdentityCard, RPC_ENTITY, MAX_BODY_BYTES } from './contract.js';
+export { assertIdentityCard, RPC_ENTITY, ENVELOPE_BYTES, maxBodyBytes, maxFrameBytes, setMaxBodyBytes } from './contract.js';
 export { createLocalRunner, createAppRunner } from './boot/runner.js';
 
 // A frond an app STATES, for a boot that will not scan. No disk, no `typescript` — which

package/src/prefab/collector.ts

@@ -4,7 +4,9 @@
  * Documented: [collectors](https://fougere.dev/docs/business/collectors).
  */
 
-import { upperFirst } from '@fougere/schema';
+import { FieldValueValidator, dotted, json, upperFirst, type Field, type SchemaView } from '@fougere/schema';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 
 export function Collector<T extends abstract new (...args: any[]) => any>(target: T) {
   class CollectorBase {
@@ -18,3 +20,29 @@ export function Collector<T extends abstract new (...args: any[]) => any>(target
 export function collectorKeyOf(type: string): string {
   return `${upperFirst(type)}Collector`;
 }
+
+const readers = new WeakMap<object, Field>();
+
+/**
+ * What a collector answered, read by the entity it names — judged and rebuilt, so a `User` that
+ * crossed a process as JSON reaches the handler with its dates. A collector naming no entity
+ * answers what it built.
+ */
+export function collectedAs(collector: object, value: unknown): unknown {
+  const target = (collector.constructor as { __entity?: Partial<SchemaView> }).__entity;
+  if (value === null || value === undefined || typeof target?.getFields !== 'function') return value;
+
+  let reader = readers.get(target);
+  if (!reader) {
+    reader = json(target as SchemaView & (new () => unknown));
+    readers.set(target, reader);
+  }
+
+  const verdict = FieldValueValidator.of(reader).parse(value);
+  if ('value' in verdict) return verdict.value;
+
+  throw new FougereError({
+    code: ErrorCode.VALIDATION_FAILED,
+    message: `${collector.constructor.name}: ${verdict.path?.length ? `${dotted(verdict.path)}: ` : ''}${verdict.message}`,
+  });
+}

package/src/storage/Storage.ts

@@ -2,15 +2,21 @@ import { upperFirst, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { ListOptions } from './ListOptions.js';
 import type { ListResult } from './ListResult.js';
 import type { SelectOption } from './SelectOption.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 
-/** The keys `list()` answers to. */
-const LIST_OPTION_KEYS = [
-  'limit', 'offset', 'page', 'after', 'orderBy', 'order', 'count', 'where', 'select',
-] as const;
+/** The keys `list()` answers to, checked against `ListOptions` so neither can drift. */
+const LIST_OPTION_KEYS = Object.keys({
+  limit: true, offset: true, page: true, after: true, orderBy: true, order: true, count: true, where: true, select: true,
+} satisfies Record<keyof (ListOptions & SelectOption), true>);
+
+/** What a count must be — a text that did not read as a number arrives as `NaN`. */
+const COUNTS = ['limit', 'offset', 'page'] as const;
 
 /**
- * Refuse an option the port does not answer to, and an order by a field the entity does not
- * declare — an unhonoured `orderBy` returns the page in whatever order the engine chose.
+ * Refuse an option the port does not answer to, a count that is not one, and an order by a
+ * field the entity does not declare — an unhonoured `orderBy` returns the page in whatever order
+ * the engine chose. Refused as BAD_REQUEST: a plain Error left as INTERNAL_ERROR, its message hidden.
  */
 export function assertListOptions(
   options: object | undefined,
@@ -18,21 +24,29 @@ export function assertListOptions(
   declared: readonly string[],
 ): void {
   if (!options) return;
-  const legal = new Set<string>(LIST_OPTION_KEYS);
-  const strangers = Object.keys(options).filter((key) => !legal.has(key));
+  const strangers = Object.keys(options).filter((key) => !LIST_OPTION_KEYS.includes(key));
   if (strangers.length > 0) {
-    throw new Error(
+    refuse(
       `${entity}.list(): unknown option ${strangers.map((s) => `\`${s}\``).join(', ')}. ` +
       `Known options are ${LIST_OPTION_KEYS.join(', ')} — to filter, pass \`where: { ${strangers[0]}: … }\`.`,
     );
   }
 
+  for (const count of COUNTS) {
+    const value = (options as ListOptions)[count];
+    if (value !== undefined && !(Number.isInteger(value) && value >= 0)) {
+      refuse(`${entity}.list(): \`${count}\` is ${typeof value === 'number' ? value : JSON.stringify(value)}, not a whole number.`);
+    }
+  }
+
   const { orderBy } = options as ListOptions;
   if (orderBy === undefined || declared.includes(orderBy)) return;
 
-  throw new Error(
-    `${entity}.list(): unknown orderBy \`${orderBy}\`. ${entity} declares ${declared.join(', ')}.`,
-  );
+  refuse(`${entity}.list(): unknown orderBy \`${orderBy}\`. ${entity} declares ${declared.join(', ')}.`);
+}
+
+function refuse(message: string): never {
+  throw new FougereError({ code: ErrorCode.BAD_REQUEST, message });
 }
 
 /** Per-entity storage — scoped CRUD operations on a single entity type. */

package/src/storage/Store.ts

@@ -1,6 +1,8 @@
 import { applyCreate, applyUpdate, Role, type SchemaView } from '@fougere/schema';
 import { comparisonOf, comparisonsIn, type Comparison } from './Comparison.js';
 import type { Storage } from './Storage.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
 import type { StorageFactory } from './StorageFactory.js';
 import type { Values } from './Values.js';
 import type { ListResult } from './ListResult.js';
@@ -128,7 +130,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
           // constraint violation, and a store that loses data silently is worse than one
           // that fails.
           if (await store.has(keyOf(id))) {
-            throw new Error(`${name}.create: '${pk}' ${JSON.stringify(id)} already exists.`);
+            throw new FougereError({ code: ErrorCode.CONFLICT, message: `${name}.create: '${pk}' ${JSON.stringify(id)} already exists.` });
           }
           await store.set(keyOf(id), values);
 
@@ -136,7 +138,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
         },
         async update(id: string, input: Partial<Record<string, unknown>>) {
           const existing = await store.get(keyOf(id));
-          if (!existing) throw new Error(`Not found: ${id}`);
+          if (!existing) throw new FougereError({ code: ErrorCode.NOT_FOUND, message: `No row in ${name} for ${JSON.stringify(id)}.` });
           const updated = { ...existing, ...applyUpdate(fields, input), [pk]: existing[pk] };
           await store.set(keyOf(id), updated);
 

package/src/wire/BodyLimit.ts

@@ -0,0 +1,28 @@
+/** How much a caller may send — held ONCE for the process and CONSULTED at every door, like the log level. */
+let limit = 2 * 1024 * 1024;
+
+/** The room a hop keeps for what it adds around a call — trace, identity, state — which never counts against the caller. */
+export const ENVELOPE_BYTES = 64 * 1024;
+
+export function maxBodyBytes(): number {
+  return limit;
+}
+
+/** Set by `applyConfig` from `maxBodyBytes:`. */
+export function setMaxBodyBytes(bytes: number): void {
+  if (!Number.isInteger(bytes) || bytes <= 0) {
+    throw new Error(`maxBodyBytes: a positive whole number of bytes — got ${String(bytes)}.`);
+  }
+  limit = bytes;
+}
+
+/**
+ * What a process forwarding a call may frame and a receiver may read: the caller's limit, and the
+ * envelope's room. Measured against the caller's limit alone, a body just under it passed in
+ * process and was refused a hop away.
+ *
+ * Documented: [gradient](https://fougere.dev/docs/infra/gradient).
+ */
+export function maxFrameBytes(): number {
+  return limit + ENVELOPE_BYTES;
+}

package/src/wire/Invocation.ts

@@ -36,8 +36,9 @@ export class Invocation implements InvocationContext {
   readonly identity?: string;
   readonly caller?: string;
   readonly runAt?: number;
+  readonly crossed?: true;
 
-  /** Gives every entry and every transport the same eight-member value, frozen. */
+  /** Gives every entry and every transport the same nine-member value, frozen. */
   private constructor(context: PartialInvocation) {
     this.params = canonicalRecord(context.params);
     this.query = canonicalRecord(context.query);
@@ -49,6 +50,7 @@ export class Invocation implements InvocationContext {
     if (context.identity !== undefined) this.identity = context.identity;
     if (context.caller !== undefined) this.caller = context.caller;
     if (context.runAt !== undefined) this.runAt = context.runAt;
+    if (context.crossed) this.crossed = true;
     Object.freeze(this);
   }
 

package/src/wire/InvocationContext.ts

@@ -8,4 +8,6 @@ export interface InvocationContext {
   caller?: string;
   /** Epoch milliseconds before which this call is not to run. */
   runAt?: number;
+  /** Written by the receiver of a call from another process, whose state was judged where it entered. */
+  crossed?: true;
 }

package/src/wire/OperationContext.ts

@@ -15,4 +15,6 @@ export interface OperationContext {
   state: Record<string, unknown>;
   /** Transport-agnostic invocation context (params, query, input, state). */
   invocation?: import('./InvocationContext.js').InvocationContext;
+  /** Set by the facade that hands the call to a transport — the dual of `invocation.crossed`. */
+  crosses?: true;
 }

package/src/wire/SignedCall.ts

@@ -1,6 +1,3 @@
-/** What a receiver accepts before it stops reading an input. */
-export const MAX_BODY_BYTES = 1024 * 1024;
-
 /** Everything a caller's envelope covers — the call as the sender meant it. */
 export interface SignedCall {
   entity: string;

package/src/wire/StateShape.ts

@@ -0,0 +1,76 @@
+import { InputValidator, dotted, optional, type Field, type Fields } from '@fougere/schema';
+import { ErrorCode } from './ErrorCode.js';
+import { FougereError } from './FougereError.js';
+
+/** An extension and the members it puts on a call's `state`. */
+export interface StateDeclaration {
+  name: string;
+  state?: Readonly<Record<string, Field>>;
+}
+
+/**
+ * What a call's `state` may hold in this process: the members its extensions declare, each one
+ * absent until a host fills it. Judged at the facade, so a member arriving over the wire is
+ * rebuilt by its field exactly as it would have been handed over in-process.
+ *
+ * Documented: [collectors](https://fougere.dev/docs/business/collectors).
+ */
+export class StateShape {
+  static readonly empty = new StateShape({});
+
+  private readonly validator: InputValidator;
+
+  private constructor(private readonly fields: Fields) {
+    this.validator = InputValidator.of(fields);
+  }
+
+  /** Two extensions declaring one member refuse: the field that judges it would depend on wiring order. */
+  static of(declarations: readonly StateDeclaration[]): StateShape {
+    const fields: Fields = {};
+    const owners = new Map<string, string>();
+    for (const { name, state } of declarations) {
+      for (const [member, field] of Object.entries(state ?? {})) {
+        const owner = owners.get(member);
+        if (owner) {
+          throw new Error(
+            `[state] '${member}' is declared by two extensions, '${owner}' and '${name}'.\n`
+            + '  A member has one owner — keep one of them out of `extensions:`.',
+          );
+        }
+        owners.set(member, name);
+        fields[member] = optional(field);
+      }
+    }
+
+    return new StateShape(fields);
+  }
+
+  /**
+   * The members written since `entered` rebuilt by their fields, or a refusal naming the member
+   * and what this process declares. What `entered` already held was judged where it entered.
+   */
+  judge(
+    state: Record<string, unknown>,
+    entity: string,
+    operation: string,
+    entered: Record<string, unknown> = {},
+  ): Record<string, unknown> {
+    const written = Object.fromEntries(Object.entries(state).filter(([member, value]) => entered[member] !== value));
+    if (Object.keys(written).length === 0) return state;
+
+    const result = this.validator.validate(written);
+    if (result.success) return { ...state, ...result.data };
+
+    const declared = Object.keys(this.fields);
+    const errors = result.errors.map((error) => ({ ...error, path: ['state', ...error.path] }));
+
+    throw new FougereError({
+      code: ErrorCode.VALIDATION_FAILED,
+      message: errors.map((error) => `${dotted(error.path)}: ${error.message}`).join(', ')
+        + (declared.length ? ` — this process declares ${declared.join(', ')}` : ' — this process declares no state member'),
+      details: errors,
+      entity,
+      operation,
+    });
+  }
+}