@fougere/core 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/crypto/webcrypto.ts

@@ -0,0 +1,55 @@
+/**
+ * Ed25519 through WebCrypto — what a runtime with no `node:` builtin has.
+ *
+ * Verified in real workerd with no compatibility flag (2026-08-23): sign, verify, a JWK
+ * import, an SPKI import and SHA-256 all answer. `Ed25519` is the algorithm name; the
+ * older `NODE-ED25519` spelling is not used, and a runtime that only knows that one will
+ * refuse at `importKey` rather than silently signing with something else.
+ *
+ * The four gestures are declared here rather than pulled from `lib.dom`: this package
+ * compiles with `lib: ["ESNext"]` and naming DOM would make every consumer carry a
+ * browser's globals to read a server type. What the file needs IS the declaration.
+ */
+import { derOf } from './encoding.js';
+import type { CryptoPort, PublicJwk, Signer, Verifier } from './port.js';
+
+interface WebSubtle {
+  digest(algorithm: string, data: Uint8Array): Promise<ArrayBuffer>;
+  importKey(
+    format: 'pkcs8' | 'spki' | 'jwk',
+    key: Uint8Array | PublicJwk,
+    algorithm: { name: string },
+    extractable: boolean,
+    usages: string[],
+  ): Promise<unknown>;
+  sign(algorithm: { name: string }, key: unknown, data: Uint8Array): Promise<ArrayBuffer>;
+  verify(algorithm: { name: string }, key: unknown, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+}
+
+const ED25519 = { name: 'Ed25519' } as const;
+
+/** Read at call time — a Worker has the global, and reading it at module load does not. */
+const subtle = (): WebSubtle =>
+  (globalThis as unknown as { crypto: { subtle: WebSubtle } }).crypto.subtle;
+
+export const crypto: CryptoPort = {
+  async sha256(data) {
+    return new Uint8Array(await subtle().digest('SHA-256', data));
+  },
+
+  async signerOf(privateKeyPem): Promise<Signer> {
+    // Imported once, at boot. Doing it per call would put an async key parse inside
+    // every outgoing request — the reason the port hands back a signer at all.
+    const key = await subtle().importKey('pkcs8', derOf(privateKeyPem), ED25519, false, ['sign']);
+    return { async sign(data) { return new Uint8Array(await subtle().sign(ED25519, key, data)); } };
+  },
+
+  async verifierOf(key): Promise<Verifier> {
+    const imported = typeof key === 'string'
+      ? await subtle().importKey('spki', derOf(key), ED25519, false, ['verify'])
+      : await subtle().importKey('jwk', key, ED25519, false, ['verify']);
+    return { verify: (data, signature) => subtle().verify(ED25519, imported, signature, data) };
+  },
+};
+
+export type { CryptoPort, PublicJwk, Signer, Verifier };

package/src/define.ts

@@ -0,0 +1,10 @@
+import type { FougereConfig } from './config-loader.js';
+
+/**
+ * Identity helper for fougere.config.ts — preserves literal types for autocomplete
+ * while validating against FougereConfig. Equivalent to `satisfies FougereConfig`
+ * but more explicit and aligned with defineFrond().
+ */
+export function defineFougere<T extends FougereConfig>(config: T): T {
+  return config;
+}

package/src/dispatch/ArgumentResolver.ts

@@ -0,0 +1,17 @@
+import {
+  resolveArgs,
+  type BindingPlan,
+  type CollectorResolver,
+} from '../boot/binding.js';
+import type { InvocationContext } from '../contract/Invocation.js';
+
+export type CollectorLookup = (typeName: string) => CollectorResolver | undefined;
+
+/** Resolves an operation's declared binding plan against one invocation. */
+export class ArgumentResolver {
+  constructor(private readonly collectors?: CollectorLookup) {}
+
+  resolve(plan: BindingPlan, invocation: InvocationContext): Promise<unknown[]> {
+    return resolveArgs(plan, invocation, this.collectors);
+  }
+}

package/src/dispatch/ArrayResult.ts

@@ -0,0 +1,10 @@
+/** Preserve the named properties carried by a list result when its rows are replaced. */
+export function preserveArrayProperties<T extends unknown[]>(source: unknown[], target: T): T {
+  for (const key of Object.keys(source)) {
+    if (!/^\d+$/.test(key)) {
+      (target as unknown as Record<string, unknown>)[key] =
+        (source as unknown as Record<string, unknown>)[key];
+    }
+  }
+  return target;
+}

package/src/dispatch/DispatchEvent.ts

@@ -0,0 +1,38 @@
+import type { Call } from '../contract/Call.js';
+import type { RouteKind } from './Route.js';
+
+export type DispatchStage = 'received' | 'resolved' | 'completed' | 'failed' | 'settled';
+
+/** Immutable transition observed across one dispatch lifecycle. */
+export class DispatchEvent {
+  private constructor(
+    readonly stage: DispatchStage,
+    readonly call: Call,
+    readonly routeKind?: RouteKind,
+    readonly error?: unknown,
+  ) {
+    Object.freeze(this);
+  }
+
+  static received(call: Call): DispatchEvent {
+    return new DispatchEvent('received', call);
+  }
+
+  static resolved(call: Call, routeKind: RouteKind): DispatchEvent {
+    return new DispatchEvent('resolved', call, routeKind);
+  }
+
+  static completed(call: Call, routeKind: RouteKind): DispatchEvent {
+    return new DispatchEvent('completed', call, routeKind);
+  }
+
+  static failed(call: Call, error: unknown, routeKind?: RouteKind): DispatchEvent {
+    return new DispatchEvent('failed', call, routeKind, error);
+  }
+
+  static settled(call: Call, routeKind?: RouteKind): DispatchEvent {
+    return new DispatchEvent('settled', call, routeKind);
+  }
+}
+
+export type DispatchObserver = (event: DispatchEvent) => void;

package/src/dispatch/DispatchLifecycle.ts

@@ -0,0 +1,23 @@
+import type { DispatchEvent, DispatchObserver } from './DispatchEvent.js';
+
+/** Publishes dispatch transitions without participating in dispatch decisions. */
+export class DispatchLifecycle {
+  constructor(
+    private readonly observers: readonly DispatchObserver[] = [],
+    private readonly diagnose: (error: unknown, event: DispatchEvent) => void = () => {},
+  ) {}
+
+  publish(event: DispatchEvent): void {
+    for (const observer of this.observers) {
+      try {
+        observer(event);
+      } catch (error) {
+        try {
+          this.diagnose(error, event);
+        } catch {
+          // Diagnostics remain observational too.
+        }
+      }
+    }
+  }
+}

package/src/dispatch/DispatchPort.ts

@@ -0,0 +1,6 @@
+import type { Call } from '../contract/Call.js';
+
+/** The only capability an entry needs. */
+export interface DispatchPort {
+  dispatch(call: Call): Promise<unknown>;
+}

package/src/dispatch/Dispatcher.ts

@@ -0,0 +1,48 @@
+import type { Call } from '../contract/Call.js';
+import { DispatchEvent } from './DispatchEvent.js';
+import { DispatchLifecycle } from './DispatchLifecycle.js';
+import type { DispatchPort } from './DispatchPort.js';
+import type { Route } from './Route.js';
+import type { RoutePolicy } from './RoutePolicy.js';
+import { RouteRegistry } from './RouteRegistry.js';
+import { RouteNotFoundError } from './RouteNotFoundError.js';
+import type { InFlight } from './InFlight.js';
+
+/** Resolves and executes every call through the same transverse lifecycle. */
+export class Dispatcher implements DispatchPort {
+  constructor(
+    private readonly routes: RouteRegistry,
+    private readonly inFlight: InFlight,
+    private readonly lifecycle = new DispatchLifecycle(),
+    private readonly policy?: RoutePolicy,
+  ) {}
+
+  async dispatch(call: Call): Promise<unknown> {
+    let route: Route | undefined;
+    let release: (() => void) | undefined;
+    this.lifecycle.publish(DispatchEvent.received(call));
+
+    try {
+      release = this.inFlight.enter(call.address.entity, call.address.operation);
+      const known = this.routes.find(call.address);
+      const resolved = known ?? await this.routes.resolve(call.address);
+      route = resolved && (!this.policy || this.policy.accepts(resolved)) ? resolved : undefined;
+      if (!route) {
+        throw this.policy?.notFound?.(call, this.routes.routes())
+          ?? new RouteNotFoundError(call, this.routes.routes(), this.policy);
+      }
+
+      this.lifecycle.publish(DispatchEvent.resolved(call, route.kind));
+      const result = await route.execute(call);
+      this.lifecycle.publish(DispatchEvent.completed(call, route.kind));
+      return result;
+    } catch (error) {
+      this.lifecycle.publish(DispatchEvent.failed(call, error, route?.kind));
+      throw error;
+    } finally {
+      this.lifecycle.publish(DispatchEvent.settled(call, route?.kind));
+      release?.();
+    }
+  }
+
+}

package/src/dispatch/InFlight.ts

@@ -0,0 +1,49 @@
+import { FougereError, ErrorCode } from '../wire/errors.js';
+
+/** Controls dispatch admission and signals when every accepted call has settled. */
+export class InFlight {
+  private running = 0;
+  private accepting = true;
+  private idle: (() => void)[] = [];
+
+  get count(): number {
+    return this.running;
+  }
+
+  get open(): boolean {
+    return this.accepting;
+  }
+
+  enter(entity: string, operation: string): () => void {
+    if (!this.accepting) {
+      throw new FougereError({
+        code: ErrorCode.SERVICE_UNAVAILABLE,
+        message: 'This app is being released and takes no new call — reach the current one through its handle.',
+        entity,
+        operation,
+      });
+    }
+
+    this.running++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.running--;
+      if (this.running !== 0) return;
+
+      const waiting = this.idle;
+      this.idle = [];
+      for (const wake of waiting) wake();
+    };
+  }
+
+  close(): void {
+    this.accepting = false;
+  }
+
+  whenIdle(): Promise<void> {
+    if (this.running === 0) return Promise.resolve();
+    return new Promise((resolve) => this.idle.push(resolve));
+  }
+}

package/src/dispatch/InputValidator.ts

@@ -0,0 +1,28 @@
+import { RowJudge, type SchemaView } from '@fougere/schema';
+import type { InvocationContext } from '../contract/Invocation.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+
+/** Validates and decodes the input body declared by one operation contract. */
+export class InputValidator {
+  validate(
+    schema: SchemaView | undefined,
+    invocation: InvocationContext,
+    entity: string,
+    operation: string,
+  ): InvocationContext {
+    if (!schema || invocation.body === undefined || invocation.body === null) return invocation;
+
+    const result = RowJudge.of(schema.getFields(), { patch: schema.getOpts().patch })
+      .check(invocation.body);
+    if (!result.success) {
+      throw new FougereError({
+        code: ErrorCode.VALIDATION_FAILED,
+        message: result.errors.map((error) => `${error.path}: ${error.message}`).join(', '),
+        details: result.errors,
+        entity,
+        operation,
+      });
+    }
+    return { ...invocation, body: result.data };
+  }
+}

package/src/dispatch/LocalRoutePolicy.ts

@@ -0,0 +1,34 @@
+import type { Call } from '../contract/Call.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+import type { Route } from './Route.js';
+import type { RoutePolicy } from './RoutePolicy.js';
+import { RouteNotFoundError } from './RouteNotFoundError.js';
+
+/** Incoming calls may execute here but never forward to another host. */
+export class LocalRoutePolicy implements RoutePolicy {
+  constructor(private readonly hostedNames: (surface?: string) => string[]) {}
+
+  accepts(route: Route): boolean {
+    return route.kind !== 'remote';
+  }
+
+  notFound(call: Call, routes: readonly Route[]): Error | undefined {
+    if (call.address.entity === 'rpc') return undefined;
+
+    const unknownRoute = new RouteNotFoundError(call, routes, this);
+    if (unknownRoute.servedOperations.length > 0) return unknownRoute;
+
+    const hosted = this.hostedNames(call.address.surface);
+    const entity = call.address.entity;
+    const surface = call.address.surface;
+    return new FougereError({
+      code: ErrorCode.NOT_FOUND,
+      message: (surface
+        ? `Entity '${entity}' is not served on surface '${surface}'`
+        : `Entity '${entity}' is not hosted here`)
+        + (hosted.length ? `. Hosted here: ${hosted.join(', ')}.` : '. This app hosts no entity.'),
+      entity,
+      operation: call.address.operation,
+    });
+  }
+}

package/src/dispatch/OperationExecutor.ts

@@ -0,0 +1,60 @@
+import type { InvocationContext } from '../contract/Invocation.js';
+import { canonicalInvocation } from '../contract/Invocation.js';
+import type { OperationContract } from '../wire/operation.js';
+import {
+  runMiddlewares,
+  type AppMiddleware,
+  type OperationContext,
+} from '../wire/middleware.js';
+import type { ArgumentResolver } from './ArgumentResolver.js';
+import type { InputValidator } from './InputValidator.js';
+import type { OutputProjector } from './OutputProjector.js';
+
+export interface OperationExecution {
+  entity: string;
+  frond: string;
+  operation: string;
+  contract: OperationContract | undefined;
+  middlewares: () => AppMiddleware[];
+  validator: InputValidator;
+  arguments: ArgumentResolver;
+  invoke: (args: unknown[]) => unknown | Promise<unknown>;
+  projector: OutputProjector;
+  present?: (result: unknown, invocation: InvocationContext) => Promise<unknown>;
+}
+
+/** Executes one operation through the same ordered boundary steps on every route. */
+export class OperationExecutor {
+  constructor(private readonly execution: OperationExecution) {}
+
+  async execute(input?: Partial<InvocationContext>): Promise<unknown> {
+    const invocation = canonicalInvocation(input);
+    const context: OperationContext = {
+      entity: this.execution.entity,
+      frond: this.execution.frond,
+      operation: this.execution.operation,
+      args: [],
+      state: invocation.state,
+      invocation,
+    };
+    return runMiddlewares(this.execution.middlewares(), context, async () => {
+      const effective = this.execution.validator.validate(
+        this.execution.contract?.input,
+        invocation,
+        context.entity,
+        context.operation,
+      );
+      context.invocation = effective;
+
+      const args = this.execution.contract?.binding
+        ? await this.execution.arguments.resolve(this.execution.contract.binding, effective)
+        : [];
+      const projected = this.execution.projector.project(
+        await this.execution.invoke(args),
+      );
+      return this.execution.present
+        ? this.execution.present(projected, effective)
+        : projected;
+    });
+  }
+}

package/src/dispatch/OperationRoute.ts

@@ -0,0 +1,18 @@
+import type { Call } from '../contract/Call.js';
+import type { RouteAddress } from '../contract/RouteAddress.js';
+import type { Route } from './Route.js';
+
+export type RouteExecution = (call: Call) => unknown | Promise<unknown>;
+
+/** One executable route, distinguished by its routing kind. */
+export class OperationRoute implements Route {
+  constructor(
+    readonly kind: Route['kind'],
+    readonly address: RouteAddress,
+    private readonly execution: RouteExecution,
+  ) {}
+
+  async execute(call: Call): Promise<unknown> {
+    return (await this.execution(call)) ?? null;
+  }
+}

package/src/dispatch/OutputProjector.ts

@@ -0,0 +1,32 @@
+import { Visibility } from '@fougere/schema';
+import { preserveArrayProperties } from './ArrayResult.js';
+import type { OutputView } from './OutputView.js';
+
+/**
+ * Projects one operation result onto the fields its audience may read.
+ *
+ * One of the two exits a judge watches; `StorageGuard` is the other.
+ */
+export class OutputProjector {
+  constructor(private readonly view: OutputView) {}
+
+  project(result: unknown): unknown {
+    if (result === null || result === undefined) return result;
+
+    if (Array.isArray(result)) {
+      return preserveArrayProperties(result, result.map((item) => this.project(item)));
+    }
+
+    if (typeof result !== 'object') return result;
+
+    const record = result as Record<string, unknown>;
+    const scoped = this.view.closed
+      ? Object.fromEntries(
+          Object.keys(this.view.fields)
+            .filter((key) => key in record)
+            .map((key) => [key, record[key]]),
+        )
+      : record;
+    return Visibility.of(this.view.fields).encode(scoped);
+  }
+}

package/src/dispatch/OutputView.ts

@@ -0,0 +1,9 @@
+import type { Fields } from '@fougere/schema';
+
+/** Immutable projection boundary of one operation result. */
+export class OutputView {
+  constructor(
+    readonly fields: Fields,
+    readonly closed = false,
+  ) {}
+}

package/src/dispatch/PresenterArgumentResolver.ts

@@ -0,0 +1,25 @@
+import { computeBindingPlan } from '../boot/binding.js';
+import type { InvocationContext } from '../contract/Invocation.js';
+import type { PresenterEntry } from '../scan/frond.js';
+import type { ArgumentResolver } from './ArgumentResolver.js';
+import type { PresenterArgs } from './PresenterExecutor.js';
+
+/** Resolves the invocation-dependent arguments of every computed presenter field. */
+export class PresenterArgumentResolver {
+  constructor(
+    private readonly argumentsResolver: ArgumentResolver,
+    private readonly collectorTypes: Set<string>,
+  ) {}
+
+  async resolve(meta: PresenterEntry, invocation: InvocationContext): Promise<PresenterArgs> {
+    const argumentsByField: PresenterArgs = {};
+    for (const field of meta.fieldMeta) {
+      if (!field.params?.length) continue;
+      argumentsByField[field.name] = await this.argumentsResolver.resolve(
+        computeBindingPlan(field.params, this.collectorTypes),
+        invocation,
+      );
+    }
+    return argumentsByField;
+  }
+}

package/src/dispatch/PresenterExecutor.ts

@@ -0,0 +1,55 @@
+import { ErrorCode, FougereError } from '../wire/errors.js';
+import { preserveArrayProperties } from './ArrayResult.js';
+
+export type PresenterArgs = Record<string, unknown[]>;
+
+/** Adds a presenter's computed fields after output projection. */
+export class PresenterExecutor {
+  constructor(
+    private readonly presenter: Record<string, unknown> | undefined,
+    private readonly fieldNames: readonly string[] | undefined,
+    private readonly entity = 'unknown',
+    private readonly operation = 'unknown',
+  ) {}
+
+  async present(result: unknown, args: PresenterArgs = {}): Promise<unknown> {
+    if (!this.presenter || !this.fieldNames?.length || result === null || typeof result !== 'object') {
+      return result;
+    }
+
+    const rows = Array.isArray(result) ? result : [result];
+    const values = new Map<string, unknown[]>();
+
+    for (const name of this.fieldNames) {
+      const field = this.presenter[name];
+      if (typeof field !== 'function') continue;
+      try {
+        const answered = await field.call(this.presenter, rows, ...(args[name] ?? []));
+        if (!Array.isArray(answered) || answered.length !== rows.length) {
+          const actual = Array.isArray(answered) ? answered.length : typeof answered;
+          throw new Error(`expected ${rows.length} value(s) for ${rows.length} row(s), got ${actual}`);
+        }
+        values.set(name, answered);
+      } catch (cause) {
+        throw new FougereError({
+          code: ErrorCode.INTERNAL_ERROR,
+          message: `Computed field '${name}' failed: ${(cause as Error)?.message ?? cause}`,
+          entity: this.entity,
+          operation: this.operation,
+          cause,
+        });
+      }
+    }
+
+    const enriched = rows.map((item, index) => {
+      if (item === null || typeof item !== 'object') return item;
+      const output = { ...(item as Record<string, unknown>) };
+      for (const [name, answered] of values) output[name] = answered[index];
+      return output;
+    });
+
+    return Array.isArray(result)
+      ? preserveArrayProperties(result, enriched)
+      : enriched[0];
+  }
+}

package/src/dispatch/RemoteRouteResolver.ts

@@ -0,0 +1,21 @@
+import type { RouteAddress } from '../contract/RouteAddress.js';
+import { OperationRoute } from './OperationRoute.js';
+import type { Route } from './Route.js';
+import type { RouteResolver } from './RouteResolver.js';
+
+type RemoteFacade = Record<string, Function>;
+export type RemoteFacadeResolver = (entity: string) => RemoteFacade | undefined;
+
+/** Builds a remote route on the first call, after the remote façade can be resolved. */
+export class RemoteRouteResolver implements RouteResolver {
+  constructor(private readonly facades: RemoteFacadeResolver) {}
+
+  resolve(address: RouteAddress): Route | undefined {
+    if (address.surface !== undefined) return undefined;
+
+    const facade = this.facades(address.entity);
+    const operation = facade?.[address.operation];
+    if (typeof operation !== 'function') return undefined;
+    return new OperationRoute('remote', address, (call) => operation(call.invocation));
+  }
+}

package/src/dispatch/Route.ts

@@ -0,0 +1,11 @@
+import type { Call } from '../contract/Call.js';
+import type { RouteAddress } from '../contract/RouteAddress.js';
+
+export type RouteKind = 'local' | 'remote' | 'system';
+
+/** Executable destination known by the dispatcher. */
+export interface Route {
+  readonly kind: RouteKind;
+  readonly address: RouteAddress;
+  execute(call: Call): Promise<unknown>;
+}

package/src/dispatch/RouteNotFoundError.ts

@@ -0,0 +1,29 @@
+import type { Call } from '../contract/Call.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+import type { Route } from './Route.js';
+import type { RoutePolicy } from './RoutePolicy.js';
+
+/** Describes an unresolved route from the destinations visible to one dispatcher. */
+export class RouteNotFoundError extends FougereError {
+  readonly servedOperations: readonly string[];
+
+  constructor(call: Call, routes: readonly Route[], policy?: RoutePolicy) {
+    const served = routes
+      .filter((route) => !policy || policy.accepts(route))
+      .filter((route) => route.address.entity === call.address.entity)
+      .filter((route) => route.kind === 'system'
+        || route.address.surface === call.address.surface)
+      .map((route) => route.address.operation);
+    const operation = call.address.operation;
+    const entity = call.address.entity;
+    const message = entity === 'rpc'
+      ? `Unknown rpc operation '${operation}'. `
+        + (served.length ? `It serves ${served.join(', ')}.` : 'It serves nothing.')
+      : served.length
+        ? `Unknown operation '${operation}' on '${entity}'. It serves ${served.join(', ')}.`
+        : `No route serves '${call.address}'`;
+
+    super({ code: ErrorCode.NOT_FOUND, message, entity, operation });
+    this.servedOperations = served;
+  }
+}

package/src/dispatch/RoutePolicy.ts

@@ -0,0 +1,8 @@
+import type { Call } from '../contract/Call.js';
+import type { Route } from './Route.js';
+
+/** Restricts which registered routes one dispatch capability may enter. */
+export interface RoutePolicy {
+  accepts(route: Route): boolean;
+  notFound?(call: Call, routes: readonly Route[]): Error | undefined;
+}