@fougere/core 0.3.0-alpha.0 → 0.5.0-alpha.0

package/src/dispatch/InFlight.ts

@@ -0,0 +1,45 @@
+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;
+  }
+
+  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;
+}

package/src/dispatch/RouteRegistry.ts

@@ -0,0 +1,73 @@
+import { RouteAddress } from '../contract/RouteAddress.js';
+import type { Route } from './Route.js';
+import type { RouteResolver } from './RouteResolver.js';
+
+/** Exact registry of every operation the application can dispatch. */
+export class RouteRegistry {
+  private readonly byAddress = new Map<string, Route>();
+  private readonly resolvers: RouteResolver[] = [];
+  private readonly pending = new Map<string, Promise<Route | undefined>>();
+
+  get size(): number {
+    return this.byAddress.size;
+  }
+
+  register(route: Route): void {
+    const key = route.address.key();
+    const existing = this.byAddress.get(key);
+    if (existing) {
+      throw new Error(
+        `Route collision at '${route.address}': ${existing.kind} and ${route.kind}`,
+      );
+    }
+    this.byAddress.set(key, route);
+  }
+
+  addResolver(resolver: RouteResolver): void {
+    this.resolvers.push(resolver);
+  }
+
+  find(address: RouteAddress): Route | undefined {
+    const exact = this.byAddress.get(address.key());
+    if (exact || address.surface === undefined) return exact;
+
+    const shared = this.byAddress.get(new RouteAddress({
+      entity: address.entity,
+      operation: address.operation,
+    }).key());
+    return shared?.kind === 'system' ? shared : undefined;
+  }
+
+  async resolve(address: RouteAddress): Promise<Route | undefined> {
+    const known = this.find(address);
+    if (known) return known;
+
+    const key = address.key();
+    const running = this.pending.get(key);
+    if (running) return running;
+
+    const resolution = this.resolveUnknown(address).finally(() => this.pending.delete(key));
+    this.pending.set(key, resolution);
+    return resolution;
+  }
+
+  private async resolveUnknown(address: RouteAddress): Promise<Route | undefined> {
+    for (const resolver of this.resolvers) {
+      const route = await resolver.resolve(address);
+      if (!route) continue;
+      this.register(route);
+      return route;
+    }
+    return undefined;
+  }
+
+  routes(): Route[] {
+    return [...this.byAddress.values()];
+  }
+
+  operationNames(entity: string, surface?: string): string[] {
+    return this.routes()
+      .filter((route) => route.address.entity === entity && route.address.surface === surface)
+      .map((route) => route.address.operation);
+  }
+}

package/src/dispatch/RouteResolver.ts

@@ -0,0 +1,7 @@
+import type { RouteAddress } from '../contract/RouteAddress.js';
+import type { Route } from './Route.js';
+
+/** Resolves routes that cannot be known when the registry is built. */
+export interface RouteResolver {
+  resolve(address: RouteAddress): Route | undefined | Promise<Route | undefined>;
+}

package/src/dispatch/StorageGuard.ts

@@ -0,0 +1,71 @@
+import { ValueJudge, type Fields } from '@fougere/schema';
+import { assertListOptions } from '../orm.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+
+interface Writer {
+  create(...args: [Record<string, unknown>, ...unknown[]]): Promise<unknown>;
+  update(...args: [unknown, Record<string, unknown>, ...unknown[]]): Promise<unknown>;
+}
+
+/**
+ * Judges storage writes and list options without narrowing the ORM interface.
+ *
+ * Storage is a way out like the client surface, so what goes to it is judged too — the
+ * same rule `OutputProjector` applies on the other exit.
+ */
+export class StorageGuard {
+  constructor(
+    private readonly fields: Fields,
+    private readonly entity: string,
+  ) {}
+
+  guard<T extends object>(orm: T): T {
+    const writer = orm as unknown as Writer;
+    if (typeof writer.create !== 'function' || typeof writer.update !== 'function') return orm;
+
+    const validation = this;
+    const guarded = Object.create(orm) as T & Writer;
+
+    guarded.create = async function (...args) {
+      validation.judge(args[0], 'create');
+      return writer.create.apply(this, args);
+    };
+
+    guarded.update = async function (...args) {
+      validation.judge(args[1], 'update');
+      return writer.update.apply(this, args);
+    };
+
+    const reader = orm as unknown as { list?: (...args: unknown[]) => unknown };
+    if (typeof reader.list === 'function') {
+      (guarded as unknown as typeof reader).list = async function (...args: unknown[]) {
+        assertListOptions(args[0] as object | undefined, validation.entity);
+        return (reader.list as Function).apply(this, args);
+      };
+    }
+
+    return guarded;
+  }
+
+  private judge(value: unknown, operation: string): void {
+    if (typeof value !== 'object' || value === null) return;
+
+    const errors: string[] = [];
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      const field = this.fields[key];
+      if (!field || item === undefined) continue;
+      const checked = ValueJudge.of(field).check(item);
+      if ('error' in checked) errors.push(`${key}: ${checked.error}`);
+    }
+
+    if (errors.length > 0) {
+      throw new FougereError({
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `Refused on the way out — ${errors.join(', ')}`,
+        entity: this.entity,
+        operation,
+        details: errors,
+      });
+    }
+  }
+}