@fougere/core 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/dispatch/HandlerFacade.ts

@@ -0,0 +1,231 @@
+import type { Fields } from '@fougere/schema';
+import type { Container } from '@fougere/container';
+import {
+  runMiddlewares,
+  type AppMiddleware,
+  type OperationContext,
+} from '../wire/middleware.js';
+import type { CollectorResolver } from './ArgumentResolver.js';
+import { collectorKeyOf } from '../prefab/collector.js';
+import { inheritsCrud, subjectOf } from '../prefab/crud.js';
+import { presenterKeyOf } from '../prefab/presenter.js';
+import { repositoryKeyOf } from '../prefab/repository.js';
+import type { OperationContract, OperationsMap } from '../wire/operation.js';
+import type { EffectiveOperation, EffectiveOperationsMap } from '../effective-operation.js';
+import { canonicalInvocation, type InvocationContext } from '../wire/Invocation.js';
+import type { HandlerEntry, PresenterEntry } from '../descriptor/frond.js';
+import { ArgumentResolver } from './ArgumentResolver.js';
+import { OutputView } from './OutputView.js';
+import { PresenterExecutor } from './PresenterExecutor.js';
+import { presenterArguments } from './presenterArguments.js';
+import { validateInput } from './validateInput.js';
+
+/** What boot resolved around one handler, beyond the handler and the scope it resolves in. */
+export interface Door {
+  /** The container key this door answers under. */
+  key: string;
+  /** The frond this door belongs to — travels on every OperationContext. */
+  frond: string;
+  /** Handlers in the owning frond, used to realize a resolved implementation override. */
+  handlers: readonly HandlerEntry[];
+  /** The canonical operation table resolved before boot performs any side effect. */
+  operations: EffectiveOperationsMap;
+  /** Entity names this frond has a collector for. */
+  collectors: Set<string>;
+  /** The presenter over this handler's entity, when the frond declares one. */
+  presenter: PresenterEntry | undefined;
+  /** Presenters live in the frond's own scope, whatever sub-scope this door resolves in. */
+  presenterScope: Container;
+  /** The middlewares that apply to this address, read at call time and never at boot. */
+  middlewares: () => AppMiddleware[];
+}
+
+/** Adapts one handler door to executable operations. */
+export class HandlerFacade {
+  /** Rich operation facts shared with check, explain and adapters. */
+  readonly effectiveOperations: EffectiveOperationsMap;
+  /** Contracts served by this door. */
+  readonly contracts: OperationsMap;
+
+  private readonly cachedViews = new Map<string, OutputView>();
+  private instance: any;
+  private readonly implementationKeys = new Map<string, string>();
+  private readonly implementationInstances = new Map<string, any>();
+  private readonly arguments = new ArgumentResolver(
+    (typeName) => this.collectorResolver(typeName),
+  );
+
+  constructor(
+    private readonly handler: HandlerEntry,
+    private readonly scope: Container,
+    private readonly door: Door,
+  ) {
+    this.refuseCrudWithoutRepository(handler);
+
+    scope.register(this.handlerKey, handler.ctor, { deps: this.depsOf(handler) });
+
+    this.effectiveOperations = door.operations;
+    this.contracts = new Map(
+      [...door.operations].map(([name, operation]) => [name, operation as OperationContract] as const),
+    );
+    handler.operations = this.contracts;
+
+    // Register model-selected implementations in the same execution scope.
+    for (const [name, operation] of door.operations) {
+      if (this.isBaseImplementation(operation)) continue;
+      const implementation = this.implementationHandler(name);
+      this.refuseCrudWithoutRepository(implementation);
+      const key = `${this.handlerKey}:implementation:${operation.implementation.className}`;
+      if (!this.implementationKeys.has(operation.implementation.className)) {
+        scope.register(key, implementation.ctor, { deps: this.depsOf(implementation) });
+        this.implementationKeys.set(operation.implementation.className, key);
+      }
+    }
+  }
+
+  /** One operation, through the same ordered boundary steps on every route. */
+  async execute(op: string, input?: Partial<InvocationContext>): Promise<unknown> {
+    const entity = this.handler.address;
+    const contract = this.contracts.get(op);
+    if (!contract) {
+      throw new Error(
+        `${entity} serves no operation '${op}'. `
+        + `It serves ${[...this.contracts.keys()].join(', ')}.`,
+      );
+    }
+
+    const invocation = canonicalInvocation(input);
+    const context: OperationContext = {
+      entity,
+      frond: this.door.frond,
+      operation: op,
+      args: [],
+      state: invocation.state,
+      invocation,
+    };
+
+    return runMiddlewares(this.door.middlewares(), context, async () => {
+      const validated = validateInput(contract.input, invocation, entity, op);
+      context.invocation = validated;
+
+      const args = contract.binding
+        ? await this.arguments.resolve(contract.binding, validated)
+        : [];
+      const { instance, method } = this.resolveImplementation(op);
+      const view = this.viewOf(op);
+      const output = view.project(await instance[method](...args));
+
+      const { presenter } = this.door;
+      return view.closed || !presenter ? output : this.present(op, presenter, output, validated);
+    });
+  }
+
+  /** The computed fields a presenter adds, over the page the façade just projected. */
+  private present(
+    op: string,
+    presenter: PresenterEntry,
+    output: unknown,
+    invocation: InvocationContext,
+  ): Promise<unknown> {
+    const entity = this.handler.address;
+    const executor = new PresenterExecutor(
+      this.door.presenterScope.resolve(presenterKeyOf(entity)),
+      presenter.fields,
+      entity,
+      op,
+    );
+
+    return presenterArguments(presenter, invocation, this.arguments, this.door.collectors)
+      .then((args) => executor.present(output, args));
+  }
+
+  private get handlerKey(): string {
+    return `_handler:${this.door.key}`;
+  }
+
+  private depsOf(handler: HandlerEntry): string[] {
+    const { deps } = handler;
+    if (deps.length > 0) return deps;
+
+    return inheritsCrud(handler.ctor)
+      ? [repositoryKeyOf(subjectOf(handler.ctor, handler.address))]
+      : [];
+  }
+
+  /** A custom Crud constructor must explicitly receive its repository. */
+  private refuseCrudWithoutRepository(handler: HandlerEntry): void {
+    const repoTypeName = repositoryKeyOf(subjectOf(handler.ctor, handler.address));
+    if (!inheritsCrud(handler.ctor) || handler.deps.length === 0 || handler.deps.includes(repoTypeName)) return;
+    throw new Error(
+      `${handler.ctor.name} extends Crud() and declares a constructor, so its storage is no ` +
+      `longer injected for it — but it does not take any.\n` +
+      `  Add it and hand it to super():\n` +
+      `    constructor(repo: ${repoTypeName}, …) { super(repo); }`,
+    );
+  }
+
+  /** Resolve and cache the output view declared for one operation. */
+  private viewOf(op: string): OutputView {
+    const known = this.cachedViews.get(op);
+    if (known) return known;
+
+    const operation = this.effectiveOperations.get(op);
+    const schema = operation?.output as { getFields?: () => Fields } | undefined;
+    const resolved = new OutputView(
+      typeof schema?.getFields === 'function' ? schema.getFields() : {},
+      operation?.outputClosed ?? false,
+    );
+    this.cachedViews.set(op, resolved);
+    return resolved;
+  }
+
+  private collectorResolver = (typeName: string): CollectorResolver | undefined => {
+    try { return this.scope.resolve(collectorKeyOf(typeName)) as CollectorResolver; }
+    catch { return undefined; }
+  };
+
+  /** The handler itself, resolved on first call — never at boot. */
+  private resolveHandler(): any {
+    if (!this.instance) this.instance = this.scope.resolve(this.handlerKey);
+    return this.instance;
+  }
+
+  private isBaseImplementation(operation: EffectiveOperation): boolean {
+    return operation.implementation.className === this.handler.ctor.name
+      && operation.implementation.address === this.handler.address
+      && operation.implementation.filePath === this.handler.filePath;
+  }
+
+  /** The exact handler entry the pure model selected; no name-only retry or fallback. */
+  private implementationHandler(operationName: string): HandlerEntry {
+    const operation = this.effectiveOperations.get(operationName)!;
+    const matches = this.door.handlers.filter((handler) =>
+      handler.ctor.name === operation.implementation.className
+      && handler.address === operation.implementation.address
+      && handler.filePath === operation.implementation.filePath);
+    if (matches.length !== 1) {
+      throw new Error(
+        `EffectiveOperation '${operation.id}' names ${operation.implementation.className}.`
+        + `${operation.implementation.method}, but boot found ${matches.length} matching handlers.`,
+      );
+    }
+    return matches[0]!;
+  }
+
+  private resolveImplementation(operationName: string): { instance: any; method: string } {
+    const operation = this.effectiveOperations.get(operationName)!;
+    if (this.isBaseImplementation(operation)) {
+      return { instance: this.resolveHandler(), method: operation.implementation.method };
+    }
+
+    const className = operation.implementation.className;
+    const key = this.implementationKeys.get(className);
+    if (!key) throw new Error(`No registered implementation for EffectiveOperation '${operation.id}'.`);
+    let instance = this.implementationInstances.get(key);
+    if (!instance) {
+      instance = this.scope.resolve(key);
+      this.implementationInstances.set(key, instance);
+    }
+    return { instance, method: operation.implementation.method };
+  }
+}

package/src/dispatch/LocalRoutePolicy.ts

@@ -1,8 +1,8 @@
-import type { Call } from '../contract/Call.js';
+import type { Call } from '../wire/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';
+import { routeNotFound, servedOperations } from './routeNotFound.js';
 
 /** Incoming calls may execute here but never forward to another host. */
 export class LocalRoutePolicy implements RoutePolicy {
@@ -15,8 +15,8 @@ export class LocalRoutePolicy implements RoutePolicy {
   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 served = servedOperations(call, routes, this);
+    if (served.length > 0) return routeNotFound(call, served);
 
     const hosted = this.hostedNames(call.address.surface);
     const entity = call.address.entity;

package/src/dispatch/OperationRoute.ts

@@ -1,5 +1,5 @@
-import type { Call } from '../contract/Call.js';
-import type { RouteAddress } from '../contract/RouteAddress.js';
+import type { Call } from '../wire/call.js';
+import type { RouteAddress } from '../wire/RouteAddress.js';
 import type { Route } from './Route.js';
 
 export type RouteExecution = (call: Call) => unknown | Promise<unknown>;

package/src/dispatch/OutputView.ts

@@ -1,9 +1,31 @@
-import type { Fields } from '@fougere/schema';
+import { Visibility, type Fields } from '@fougere/schema';
+import { preserveArrayProperties } from './ArrayResult.js';
 
-/** Immutable projection boundary of one operation result. */
+/** What one operation result may show. One of the two exits a validator watches. */
 export class OutputView {
   constructor(
     readonly fields: Fields,
     readonly closed = false,
   ) {}
+
+  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.closed
+      ? Object.fromEntries(
+          Object.keys(this.fields)
+            .filter((key) => key in record)
+            .map((key) => [key, record[key]]),
+        )
+      : record;
+
+    return Visibility.of(this.fields).encode(scoped);
+  }
 }

package/src/dispatch/Route.ts

@@ -1,5 +1,5 @@
-import type { Call } from '../contract/Call.js';
-import type { RouteAddress, RouteKind } from '../contract/RouteAddress.js';
+import type { Call } from '../wire/call.js';
+import type { RouteAddress, RouteKind } from '../wire/RouteAddress.js';
 
 /** Executable destination known by the dispatcher. */
 export interface Route {

package/src/dispatch/RoutePolicy.ts

@@ -1,4 +1,4 @@
-import type { Call } from '../contract/Call.js';
+import type { Call } from '../wire/call.js';
 import type { Route } from './Route.js';
 
 /** Restricts which registered routes one dispatch capability may enter. */

package/src/dispatch/RouteRegistry.ts

@@ -1,4 +1,4 @@
-import { RouteAddress } from '../contract/RouteAddress.js';
+import { RouteAddress } from '../wire/RouteAddress.js';
 import type { Route } from './Route.js';
 import type { RouteResolver } from './RouteResolver.js';
 
@@ -53,7 +53,7 @@ export class RouteRegistry {
 
   private async resolveUnknown(address: RouteAddress): Promise<Route | undefined> {
     for (const resolver of this.resolvers) {
-      const route = await resolver.resolve(address);
+      const route = await resolver(address);
       if (!route) continue;
       this.register(route);
       return route;

package/src/dispatch/RouteResolver.ts

@@ -1,7 +1,5 @@
-import type { RouteAddress } from '../contract/RouteAddress.js';
+import type { RouteAddress } from '../wire/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>;
-}
+export type RouteResolver = (address: RouteAddress) => Route | undefined | Promise<Route | undefined>;

package/src/dispatch/StorageGuard.ts

@@ -1,18 +1,17 @@
-import { ValueJudge, type Fields } from '@fougere/schema';
+import { Boundary, FieldSet, FieldValueValidator, InputRefusal, type Fields } from '@fougere/schema';
 import { assertListOptions } from '../storage.js';
 import { ErrorCode, FougereError } from '../wire/errors.js';
 
+/** The gestures this guard grafts onto. */
 interface Writer {
   create(...args: [Record<string, unknown>, ...unknown[]]): Promise<unknown>;
   update(...args: [unknown, Record<string, unknown>, ...unknown[]]): Promise<unknown>;
+  upsert?(...args: [Record<string, unknown>, ...unknown[]]): Promise<unknown>;
+  upsertAll?(...args: [readonly Record<string, unknown>[], ...unknown[]]): Promise<unknown>;
+  list?(...args: unknown[]): unknown;
 }
 
-/**
- * Judges storage writes and list options without narrowing the storage 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.
- */
+/** Judges storage writes and list options without narrowing the storage interface. */
 export class StorageGuard {
   constructor(
     private readonly fields: Fields,
@@ -27,35 +26,86 @@ export class StorageGuard {
     const guarded = Object.create(storage) as T & Writer;
 
     guarded.create = async function (...args) {
-      validation.judge(args[0], 'create');
+      args[0] = validation.validated(args[0], 'create');
       return writer.create.apply(this, args);
     };
 
     guarded.update = async function (...args) {
-      validation.judge(args[1], 'update');
+      args[1] = validation.validated(args[1], 'update');
       return writer.update.apply(this, args);
     };
 
-    const reader = storage as unknown as { list?: (...args: unknown[]) => unknown };
-    if (typeof reader.list === 'function') {
-      (guarded as unknown as typeof reader).list = async function (...args: unknown[]) {
+    const upsert = writer.upsert;
+    if (typeof upsert === 'function') {
+      guarded.upsert = async function (...args) {
+        args[0] = validation.validated(args[0], 'upsert');
+        return upsert.apply(this, args);
+      };
+    }
+
+    const upsertAll = writer.upsertAll;
+    if (typeof upsertAll === 'function') {
+      // Every row before the first write: a page refused halfway leaves rows behind that
+      // the caller asked for as one, and the refusal is readable from the input alone.
+      guarded.upsertAll = async function (...args) {
+        args[0] = args[0].map((row, index) => validation.validated(row, 'upsertAll', index));
+        return upsertAll.apply(this, args);
+      };
+    }
+
+    const list = writer.list;
+    if (typeof list === 'function') {
+      guarded.list = async function (...args: unknown[]) {
         assertListOptions(args[0] as object | undefined, validation.entity);
-        return (reader.list as Function).apply(this, args);
+        return list.apply(this, args);
       };
     }
 
     return guarded;
   }
 
-  private judge(value: unknown, operation: string): void {
-    if (typeof value !== 'object' || value === null) return;
+  /**
+   * The values this write carries, validated and handed on PARSED — the rule the client door
+   * already holds (`InputValidator`), applied to a write that never passed through it. What a
+   * handler is allowed to write is not asked here: only the value is.
+   */
+  private rowAt(row: unknown, index: number): string {
+    const primary = FieldSet.of(this.fields).primary;
+    const key = primary === undefined ? undefined : (row as Record<string, unknown>)[primary];
+    return key === undefined ? `row ${index} of this page` : `row ${primary} ${JSON.stringify(key)}`;
+  }
+
+  private validated<T>(value: T, operation: string, index?: number): T {
+    if (typeof value !== 'object' || value === null) return value;
 
     const errors: string[] = [];
+    const where = index === undefined ? '' : `${this.rowAt(value, index)} — `;
+    const parsed: Record<string, unknown> = {};
+
     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}`);
+      // A key the entity does not declare has no column to land in and no judge to pass:
+      // on the client door it is a typo, and on this one it is a mapping that went stale.
+      if (!field) {
+        errors.push(`${where}${key}: ${InputRefusal.unknownField}`);
+        continue;
+      }
+      if (item === undefined) {
+        parsed[key] = item;
+        continue;
+      }
+      const checked = FieldValueValidator.of(field).validate(item);
+      if ('error' in checked) {
+        errors.push(`${where}${key}: ${checked.error}`);
+        continue;
+      }
+      if (checked.value === null) {
+        parsed[key] = null;
+        continue;
+      }
+      const decoded = Boundary.of(field).decode(checked.value);
+      if ('error' in decoded) errors.push(`${where}${key}: ${decoded.error}`);
+      else parsed[key] = decoded.value;
     }
 
     if (errors.length > 0) {
@@ -67,5 +117,7 @@ export class StorageGuard {
         details: errors,
       });
     }
+
+    return parsed as T;
   }
 }

package/src/dispatch/presenterArguments.ts

@@ -0,0 +1,25 @@
+import { computeBindingPlan } from '../wire/binding.js';
+import type { InvocationContext } from '../wire/Invocation.js';
+import type { PresenterEntry } from '../descriptor/frond.js';
+import type { ArgumentResolver } from './ArgumentResolver.js';
+import type { PresenterArgs } from './PresenterExecutor.js';
+
+/** The invocation-dependent arguments of every computed presenter field. */
+export async function presenterArguments(
+  meta: PresenterEntry,
+  invocation: InvocationContext,
+  resolver: ArgumentResolver,
+  collectorTypes: Set<string>,
+): Promise<PresenterArgs> {
+  const argumentsByField: PresenterArgs = {};
+
+  for (const field of meta.fieldMeta) {
+    if (!field.params?.length) continue;
+    argumentsByField[field.name] = await resolver.resolve(
+      computeBindingPlan(field.params, collectorTypes),
+      invocation,
+    );
+  }
+
+  return argumentsByField;
+}

package/src/dispatch/{RemoteRouteResolver.ts → remoteRoutes.ts}

@@ -1,21 +1,19 @@
-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 {
+/** Builds a remote route on the first call, once the remote façade can be resolved. */
+export function remoteRoutes(facades: RemoteFacadeResolver): RouteResolver {
+  return (address) => {
     if (address.surface !== undefined) return undefined;
 
-    const facade = this.facades(address.entity);
+    const facade = 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/routeNotFound.ts

@@ -0,0 +1,33 @@
+import type { Call } from '../wire/call.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+import type { Route } from './Route.js';
+import type { RoutePolicy } from './RoutePolicy.js';
+
+/** The operations this dispatcher would have served for the entity the call names. */
+export function servedOperations(
+  call: Call,
+  routes: readonly Route[],
+  policy?: RoutePolicy,
+): readonly string[] {
+  return 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);
+}
+
+/** `Unknown operation 'draft' on 'post'. It serves list, findById.` */
+export function routeNotFound(
+  call: Call,
+  served: readonly string[],
+): FougereError {
+  const { entity, operation } = call.address;
+  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}'`;
+
+  return new FougereError({ code: ErrorCode.NOT_FOUND, message, entity, operation });
+}

package/src/dispatch/validateInput.ts

@@ -0,0 +1,28 @@
+import { InputValidator, type SchemaView } from '@fougere/schema';
+import type { InvocationContext } from '../wire/Invocation.js';
+import { ErrorCode, FougereError } from '../wire/errors.js';
+
+/** Validates and decodes the input declared by one operation contract. */
+export function validateInput(
+  schema: SchemaView | undefined,
+  invocation: InvocationContext,
+  entity: string,
+  operation: string,
+): InvocationContext {
+  if (!schema || invocation.input === undefined || invocation.input === null) return invocation;
+
+  const result = InputValidator.of(schema.getFields(), { patch: schema.getOpts().patch })
+    .validate(invocation.input);
+
+  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, input: result.data };
+}