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

package/src/boot/HandlerFacade.ts

@@ -1,242 +0,0 @@
-import { lowerFirst, type Fields } from '@fougere/schema';
-import type { Container } from '@fougere/container';
-import type { AppMiddleware } from '../wire/middleware.js';
-import type { CollectorResolver } from '../dispatch/ArgumentResolver.js';
-import { collectorKeyOf } from '../prefab/collector.js';
-import { presenterKeyOf } from '../prefab/presenter.js';
-import { repositoryKeyOf } from '../prefab/repository.js';
-import { targetOf } from '../prefab/prefab.js';
-import type { OperationContract, OperationsMap } from '../wire/operation.js';
-import type { EffectiveOperation, EffectiveOperationsMap } from '../effective-operation.js';
-import type { InvocationContext } from '../contract/Invocation.js';
-import type { Emissions } from './Emissions.js';
-import type { Logger } from '../builtins/logger.js';
-import type { EntityEntry, HandlerEntry, PresenterEntry } from '../descriptor/frond.js';
-import { InputValidator } from '../dispatch/InputValidator.js';
-import { ArgumentResolver } from '../dispatch/ArgumentResolver.js';
-import { OperationExecutor } from '../dispatch/OperationExecutor.js';
-import { OutputProjector } from '../dispatch/OutputProjector.js';
-import { OutputView } from '../dispatch/OutputView.js';
-import { PresenterExecutor } from '../dispatch/PresenterExecutor.js';
-import { PresenterArgumentResolver } from '../dispatch/PresenterArgumentResolver.js';
-
-/** What this door is about: a handler, the entity behind it when there is one, and where it resolves. */
-export interface Doorway {
-  handler: HandlerEntry;
-  /** 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;
-  /** The subject — absent is ordinary: a health check owns no row. */
-  entity: EntityEntry | undefined;
-  /** The scope the handler and its collectors resolve in — a surface gets its own. */
-  scope: Container;
-  /** The container key this door answers under. */
-  key: string;
-}
-
-/** What the frond and the boot supply to every door alike. */
-export interface Wiring {
-  /** The frond this door belongs to — travels on every OperationContext. */
-  frond: string;
-  /** The frond's own scope — where presenters live, whatever sub-scope the door uses. */
-  frondScope: Container;
-  log: Logger;
-  /** Entity names this frond has a collector for. */
-  collectors: Set<string>;
-  presenters: Map<string, PresenterEntry>;
-  /** The middlewares that apply to an address, read at call time and never at boot. */
-  middlewaresFor: (address: string) => AppMiddleware[];
-  emissions: Emissions;
-}
-
-/** 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;
-
-  /** The callable surface: op name → the function a caller reaches. */
-  readonly ops: Record<string, Function> = {};
-
-  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 inputValidator = new InputValidator();
-  private readonly argumentResolver = new ArgumentResolver(
-    (typeName) => this.collectorResolver(typeName),
-  );
-  private readonly presenterArguments: PresenterArgumentResolver;
-
-  constructor(private readonly door: Doorway, private readonly wiring: Wiring) {
-    const { handler, entity } = door;
-    this.presenterArguments = new PresenterArgumentResolver(
-      this.argumentResolver,
-      wiring.collectors,
-    );
-    this.refuseCrudWithoutRepository(handler);
-
-    door.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)) {
-        door.scope.register(key, implementation.ctor, { deps: this.depsOf(implementation) });
-        this.implementationKeys.set(operation.implementation.className, key);
-      }
-    }
-
-    // Emissions use the same contracts and execution path as direct calls.
-    wiring.emissions.note(this.contracts, door.key);
-    // Only declared operations become callable façade members.
-    for (const op of this.contracts.keys()) this.ops[op] = this.wrap(op);
-
-    if (this.inheritsCrud(handler) && !entity) {
-      // An installed Crud subject may be absent from the local scan.
-      wiring.log.debug(`${handler.ctor.name} extends Crud() and no scanned entity is named `
-        + `'${this.subjectOf(handler)}' — installed entity, or a missing one: no storage will be injected`);
-    }
-  }
-
-  /** Storage follows the Crud subject, which may differ from the door address. */
-  private subjectOf(handler: HandlerEntry): string {
-    const target = targetOf(handler.ctor);
-    return target?.name ? lowerFirst(target.name) : handler.address;
-  }
-
-  private inheritsCrud(handler: HandlerEntry): boolean {
-    const proto = handler.ctor.prototype;
-    return typeof proto?.list === 'function' && typeof proto?.findById === 'function';
-  }
-
-  private get handlerKey(): string {
-    return `_handler:${this.door.key}`;
-  }
-
-  private depsOf(handler: HandlerEntry): string[] {
-    const { deps } = handler;
-    if (deps.length > 0) return deps;
-    return this.inheritsCrud(handler) ? [repositoryKeyOf(this.subjectOf(handler))] : [];
-  }
-
-  /** A custom Crud constructor must explicitly receive its repository. */
-  private refuseCrudWithoutRepository(handler: HandlerEntry): void {
-    const repoTypeName = repositoryKeyOf(this.subjectOf(handler));
-    if (!this.inheritsCrud(handler) || 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.door.scope.resolve(collectorKeyOf(typeName)) as CollectorResolver; }
-    catch { return undefined; }
-  };
-
-  /** The handler itself, resolved on first call — never at boot. */
-  private resolvedHandler(): any {
-    if (!this.instance) this.instance = this.door.scope.resolve(this.handlerKey);
-    return this.instance;
-  }
-
-  private isBaseImplementation(operation: EffectiveOperation): boolean {
-    return operation.implementation.className === this.door.handler.ctor.name
-      && operation.implementation.address === this.door.handler.address
-      && operation.implementation.filePath === this.door.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 resolvedImplementation(operationName: string): { instance: any; method: string } {
-    const operation = this.effectiveOperations.get(operationName)!;
-    if (this.isBaseImplementation(operation)) {
-      return { instance: this.resolvedHandler(), 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.door.scope.resolve(key);
-      this.implementationInstances.set(key, instance);
-    }
-    return { instance, method: operation.implementation.method };
-  }
-
-  private wrap(op: string): (invocation?: InvocationContext) => Promise<unknown> {
-    const address = this.door.handler.address;
-    const contract = this.contracts.get(op);
-    const view = this.viewOf(op);
-    const presenter = this.wiring.presenters.get(address);
-    const executor = new OperationExecutor({
-      entity: address,
-      frond: this.wiring.frond,
-      operation: op,
-      contract,
-      middlewares: () => this.wiring.middlewaresFor(address),
-      validator: this.inputValidator,
-      arguments: this.argumentResolver,
-      invoke: async (args) => {
-        const implementation = this.resolvedImplementation(op);
-        return implementation.instance[implementation.method](...args);
-      },
-      projector: new OutputProjector(view),
-      ...(view.closed || !presenter ? {} : {
-        present: async (result: unknown, effective: InvocationContext) =>
-          new PresenterExecutor(
-            this.wiring.frondScope.resolve(presenterKeyOf(address)),
-            presenter.fields,
-            address,
-            op,
-          ).present(result, await this.presenterArguments.resolve(presenter, effective)),
-      }),
-    });
-
-    return (invocation) => executor.execute(invocation);
-  }
-}

package/src/contract/Call.ts

@@ -1,18 +0,0 @@
-import { Invocation, type InvocationInput } from './Invocation.js';
-import type { RouteAddress } from './RouteAddress.js';
-
-/** One normalized request: where it goes and what the caller supplied. */
-export class Call {
-  readonly address: RouteAddress;
-  readonly invocation: Invocation;
-
-  constructor(address: RouteAddress, invocation?: InvocationInput) {
-    this.address = address;
-    this.invocation = Invocation.from(invocation);
-    Object.freeze(this);
-  }
-
-  withInvocation(invocation: Invocation): Call {
-    return new Call(this.address, invocation);
-  }
-}

package/src/contract/CallLog.ts

@@ -1,55 +0,0 @@
-import type { RouteKind } from './RouteAddress.js';
-
-/**
- * What crosses the door: the address, the route it took, and the verdict.
- *
- * It lives here rather than beside its producer for the reason `TopologyReport` does: it
- * crosses a process boundary, so a reader that never installed `@fougere/calls` — the CLI
- * — needs its shape, and putting it there is what produces a hand-copied duplicate.
- *
- * Never the body. Same rule the topology report states — a remote destination is named,
- * not disclosed — and it holds here for the same reason: this answer leaves the process.
- */
-export interface CallRecord {
-  /** Monotonic, and the whole cursor protocol: a reader asks for what is above its own. */
-  seq: number;
-  frond?: string;
-  entity: string;
-  operation: string;
-  surface?: string;
-  /** Known at `resolved`, so absent on a call that never found a route. */
-  route?: RouteKind;
-  /**
-   * The traceparent the invocation carried, when one did.
-   *
-   * One panel reads one process, so this is what lets two of them be sewn: the process
-   * that sent and the process that executed share it, and the gap between their two
-   * durations IS the cost of the wire rather than a deduction.
-   */
-  trace?: string;
-  /**
-   * The peer that established this call, when one did.
-   *
-   * A hosted frond serves several consumers, so its own ring mixes them: this is what
-   * separates them. Absent on a call nobody signed — a loopback dev boot has no identity.
-   */
-  caller?: string;
-  startedAt: number;
-  /** Known at `settled`. */
-  ms?: number;
-  verdict: 'running' | 'ok' | 'failed';
-  refusal?: { code?: string; message: string };
-}
-
-/**
- * One page of the ring.
- *
- * `dropped` is what the ring could not keep — an absence is named rather than left to
- * look like a quiet period.
- */
-export interface CallPage {
-  calls: CallRecord[];
-  cursor: number;
-  inFlight: number;
-  dropped: number;
-}

package/src/dispatch/InputValidator.ts

@@ -1,28 +0,0 @@
-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/OperationExecutor.ts

@@ -1,60 +0,0 @@
-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/OutputProjector.ts

@@ -1,32 +0,0 @@
-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/PresenterArgumentResolver.ts

@@ -1,25 +0,0 @@
-import { computeBindingPlan } from '../wire/binding.js';
-import type { InvocationContext } from '../contract/Invocation.js';
-import type { PresenterEntry } from '../descriptor/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/RouteNotFoundError.ts

@@ -1,29 +0,0 @@
-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/entry/DynamicFacade.ts

@@ -1,28 +0,0 @@
-type Operation = (...args: any[]) => unknown;
-
-/** Facade for a remote contract whose operation names are not known before discovery. */
-export class DynamicFacade {
-  readonly operations: Record<string, Operation>;
-
-  constructor(private readonly operation: (name: string) => Operation) {
-    this.operations = new Proxy({}, {
-      get: (_target, name) => this.isOperationName(name) ? this.operation(name) : undefined,
-      has: (_target, name) => this.isOperationName(name),
-      getOwnPropertyDescriptor: (_target, name) => this.isOperationName(name)
-        ? {
-            value: this.operation(name),
-            writable: false,
-            enumerable: true,
-            configurable: true,
-          }
-        : undefined,
-    });
-  }
-
-  private isOperationName(name: string | symbol): name is string {
-    return typeof name === 'string'
-      && name !== 'then'
-      && name !== 'toJSON'
-      && !Object.hasOwn(Object.prototype, name);
-  }
-}

package/src/entry/FacadeEntry.ts

@@ -1,32 +0,0 @@
-import { Call } from '../contract/Call.js';
-import type { InvocationInput } from '../contract/Invocation.js';
-import { RouteAddress } from '../contract/RouteAddress.js';
-import type { DispatchPort } from '../dispatch/DispatchPort.js';
-import { DynamicFacade } from './DynamicFacade.js';
-
-/** Object-shaped entry that turns facade method calls into canonical dispatches. */
-export class FacadeEntry {
-  readonly operations: Record<string, Function>;
-
-  constructor(
-    private readonly dispatcher: DispatchPort,
-    private readonly entity: string,
-    operationNames?: Iterable<string>,
-    private readonly surface?: string,
-  ) {
-    this.operations = operationNames
-      ? Object.fromEntries([...operationNames].map((name) => [name, this.operation(name)]))
-      : new DynamicFacade((name) => this.operation(name)).operations;
-  }
-
-  private operation(name: string): (invocation?: InvocationInput) => Promise<unknown> {
-    return (invocation) => this.dispatcher.dispatch(new Call(
-      new RouteAddress({
-        entity: this.entity,
-        operation: name,
-        ...(this.surface !== undefined ? { surface: this.surface } : {}),
-      }),
-      invocation,
-    ));
-  }
-}

package/src/entry/TransportEntry.ts

@@ -1,30 +0,0 @@
-import { Call } from '../contract/Call.js';
-import { RouteAddress } from '../contract/RouteAddress.js';
-import type { DispatchPort } from '../dispatch/DispatchPort.js';
-import type { FrondCall, Transport } from '../wire/call.js';
-import type { InvocationContext } from '../contract/Invocation.js';
-
-/** Object entry for the historical transport contract. */
-export class TransportEntry {
-  constructor(
-    private readonly dispatcher: DispatchPort,
-    private readonly surface?: string,
-  ) {}
-
-  receive(legacy: FrondCall, invocation: InvocationContext): Promise<unknown> {
-    return this.dispatcher.dispatch(new Call(
-      new RouteAddress({
-        entity: legacy.entity,
-        operation: legacy.op,
-        ...(this.surface !== undefined ? { surface: this.surface } : {}),
-      }),
-      invocation,
-    ));
-  }
-}
-
-/** Adapt the historical transport signature to the canonical dispatch port. */
-export function createTransportEntry(dispatcher: DispatchPort, surface?: string): Transport {
-  const entry = new TransportEntry(dispatcher, surface);
-  return entry.receive.bind(entry);
-}