@fougere/core 0.8.3-alpha.0 → 0.9.0-alpha.0

package/src/boot/Emissions.ts

@@ -1,9 +1,9 @@
-import { applyCreate, type SchemaView } from '@fougere/schema';
+import { applyCreate, dotted, lowerFirst, type SchemaView } from '@fougere/schema';
 import type { Container } from '@fougere/container';
 import { validationErrorsOf } from '../wire/errors.js';
-import { emitKeyOf, factsAnnouncedBy } from '../emit.js';
+import { awaitKeyOf, emitKeyOf, factsAnnouncedBy, factsAwaitedBy } from '../wire/emit.js';
 import { ambient } from '#ambient';
-import { EMPTY_INVOCATION } from '../wire/Invocation.js';
+import { Invocation } from '../wire/Invocation.js';
 import type { Logger } from '../builtin/logger.js';
 import type { Fronds } from '../descriptor/Fronds.js';
 import type { OperationsMap } from '../wire/operation.js';
@@ -22,6 +22,12 @@ export class Emissions {
   /** Who listens to what. Filled as each door's contracts are resolved. */
   private readonly subscribers = new Map<string, Listener[]>();
 
+  /** Who FINISHES a fact, in the order they run — see `orderPipes`. */
+  private readonly pipes = new Map<string, Listener[]>();
+
+  /** The order its OWNER declared, by fact — `pipes:` in `frond.config.ts`. */
+  private readonly ordered: Map<string, string[]>;
+
   /**
    * What is announced here, read from the DEPS and not from the subscribers: a handler declaring
    * `Emit<PostPublished>` must resolve it whether or not anybody listens, and announcing to nobody
@@ -29,6 +35,9 @@ export class Emissions {
    */
   private readonly announced: Set<string>;
 
+  /** What is announced AND waited for — `Emit<T, A>`, where the second type says so. */
+  private readonly awaited: Set<string>;
+
   constructor(
     fronds: Fronds,
     private readonly shapes: Map<string, SchemaView>,
@@ -37,6 +46,23 @@ export class Emissions {
     private readonly carry?: Carrier,
   ) {
     this.announced = new Set(fronds.flatMap((frond) => factsAnnouncedBy(frond.handlers)));
+    this.awaited = new Set(fronds.flatMap((frond) => factsAwaitedBy(frond.handlers)));
+    // Read from the frond that OWNS the fact: ordering is a decision about the fact, and
+    // a decision has one owner. A frond ordering a neighbour's fact is refused below.
+    this.ordered = new Map(fronds.flatMap((frond) => {
+      const owned = new Set(frond.entities.map((entity) => entity.name));
+
+      return Object.entries(frond.pipes ?? {}).map(([fact, order]) => {
+        if (!owned.has(lowerFirst(fact))) {
+          throw new Error(
+            `Frond '${frond.name}' orders the links of '${fact}', which it does not own.\n`
+            + '  The order belongs to the frond that declares the entity — state `pipes:` there.',
+          );
+        }
+
+        return [lowerFirst(fact), order] as const;
+      });
+    }));
   }
 
   /**
@@ -46,6 +72,10 @@ export class Emissions {
   note(contracts: OperationsMap, door: string): void {
     for (const [op, contract] of contracts) {
       for (const bound of contract.binding ?? []) {
+        if (bound.source.kind === 'pipe') {
+          this.claimPipe(bound.source.factName, { door, op });
+          continue;
+        }
         if (bound.source.kind !== 'fact') continue;
         const listeners = this.subscribers.get(bound.source.factName) ?? [];
         listeners.push({ door, op });
@@ -54,6 +84,51 @@ export class Emissions {
     }
   }
 
+  /** One more op that finishes this fact. What ORDER they run in is settled at `register`. */
+  private claimPipe(fact: string, taking: Listener): void {
+    const held = this.pipes.get(fact) ?? [];
+    if (held.some((one) => `${one.door}.${one.op}` === `${taking.door}.${taking.op}`)) return;
+    held.push(taking);
+    this.pipes.set(fact, held);
+  }
+
+  /**
+   * Put the links in the order their fact's owner declared, and refuse what it did not.
+   *
+   * Two links with no order refuse: nothing would say which finished the fact, and scan
+   * order is not an answer — the same reason two implementations of a port refuse. One
+   * link needs no declaration, because there is nothing to order.
+   */
+  private orderPipes(): void {
+    for (const [fact, links] of this.pipes) {
+      const declared = this.ordered.get(fact);
+      const named = (one: Listener) => `${one.door}.${one.op}`;
+
+      if (!declared) {
+        if (links.length < 2) continue;
+        throw new Error(
+          `${links.length} ops finish the fact '${fact}': ${links.map(named).join(', ')}.\n`
+          + '  They run one after another and nothing says in which order. State it on the '
+          + `frond that owns '${fact}':\n`
+          + `    export default { pipes: { ${fact}: ['FirstHandler', 'SecondHandler'] } };\n`
+          + '  Or make all but one accept `Fact<…>`, which changes nothing and reads it.',
+        );
+      }
+
+      const at = (one: Listener) => declared.findIndex((name) => doorOf(name) === one.door);
+      const unlisted = links.filter((one) => at(one) < 0);
+      if (unlisted.length > 0) {
+        throw new Error(
+          `${unlisted.map(named).join(', ')} finish${unlisted.length > 1 ? '' : 'es'} the fact `
+          + `'${fact}', and '${fact}' orders ${declared.join(', ')} — so where it runs is not said.\n`
+          + '  Add it to `pipes:`, or make it accept `Fact<…>`.',
+        );
+      }
+
+      this.pipes.set(fact, [...links].sort((one, other) => at(one) - at(other)));
+    }
+  }
+
   /** The shape a fact is validated by, when the fact is a declared entity. */
   shapeOf(fact: string): SchemaView | undefined {
     return this.shapes.get(fact);
@@ -64,18 +139,39 @@ export class Emissions {
     return [...this.subscribers.keys()];
   }
 
+  /** The doors that accept one fact — the addresses a middleware must leave alone. */
+  doorsFor(fact: string): string[] {
+    return (this.subscribers.get(fact) ?? []).map(({ door }) => door);
+  }
+
   /** Register one emission value per fact — announced here, or merely listened to. */
   register(): void {
+    this.orderPipes();
     for (const fact of new Set([...this.announced, ...this.subscribers.keys()])) {
       this.container.registerValue(emitKeyOf(fact), (raw: unknown) => this.announce(fact, raw));
     }
+    for (const fact of this.awaited) {
+      // Waiting means knowing WHO, and a carrier publishes to whoever subscribed elsewhere
+      // without bringing anything back — so the answers would hold this process's
+      // subscribers only, and say nothing about it. Refused here rather than half-answered
+      // at the first call: the second type is in a signature, so a boot can read it.
+      if (this.carry) {
+        throw new Error(
+          `'${fact}' is announced with an answer type, and this app has a carrier (\`onEmit\`).\n`
+          + '  Waiting means knowing who answers; a carrier reaches whoever subscribed '
+          + 'elsewhere and brings nothing back.\n'
+          + `  Name the subscribers in \`remotes:\`, or drop the second type of \`Emit<${fact}, …>\`.`,
+        );
+      }
+      this.container.registerValue(awaitKeyOf(fact), (raw: unknown) => this.announce(fact, raw, true));
+    }
     if (ambient.degraded && this.subscribers.size > 0) {
       this.log.warn('no async context on this runtime — an emission ring is not detected');
     }
   }
 
   /** Announcing. */
-  private async announce(fact: string, raw: unknown): Promise<void> {
+  private async announce(fact: string, raw: unknown, waiting = false): Promise<unknown[]> {
     /**
      * A fact announced inside a frame that then rolls back is a lie, and nothing can take it back:
      * announcing is DISPATCH — every subscriber has been handed the fact and the carrier has
@@ -83,15 +179,45 @@ export class Emissions {
      */
     await ambient.beforeAnnounce(fact);
 
-    const payload = this.stamped(fact, raw);
+    const payload = await this.finished(fact, this.stamped(fact, raw));
 
     /** Whoever is not in this process — and it is the ONLY way to reach them. */
     const delivery = this.carry?.(fact, payload);
     if (delivery) void Promise.resolve(delivery).catch((cause) => this.log.error(`${fact} — carrier refused it`, cause));
 
-    for (const { door, op, done } of this.handToListeners(fact, payload)) {
-      void done.catch((cause) => this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, cause) ?? cause));
+    const handed = this.handToListeners(fact, payload);
+    if (!waiting) {
+      for (const { door, op, done } of handed) {
+        void done.catch((cause) => this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, cause) ?? cause));
+      }
+
+      return [];
+    }
+
+    const settled = await Promise.allSettled(handed.map((one) => one.done));
+
+    // A subscriber that did not answer REFUSES the announcement, it does not shrink it: an
+    // announcer handed the survivors cannot tell three answers from two, and its own law
+    // then reads silence as consent — the room one would have refused gets booked.
+    const missing = settled.flatMap((result, at) =>
+      (result.status === 'rejected' ? [{ ...handed[at]!, reason: result.reason as unknown }] : []));
+    if (missing.length > 0) {
+      for (const { door, op, reason } of missing) {
+        this.log.error(`${fact} → ${door}.${op}`, this.describeRefusal(fact, reason) ?? reason);
+      }
+      throw new AggregateError(
+        missing.map((one) => one.reason),
+        `${fact} — ${missing.length} of ${handed.length} subscriber(s) did not answer`
+        + ` (${missing.map((one) => `${one.door}.${one.op}`).join(', ')}).`
+        + ' An announcement with an answer type waits for everyone: a partial answer would'
+        + ' look like a complete one.',
+      );
     }
+
+    // What answers NOTHING contributes nothing — a subscriber is free to have no opinion,
+    // and `Promise<void>` is how it says so.
+    return settled.flatMap((result) =>
+      (result.status === 'fulfilled' && result.value != null ? [result.value] : []));
   }
 
   /** Receiving. */
@@ -114,6 +240,38 @@ export class Emissions {
     }
   }
 
+  /**
+   * What the declared link answers, or the value as it stands when nothing declared one.
+   *
+   * Before anyone is handed anything, and once: every subscriber reads the same fact, which
+   * is the whole reason a fact can be said to be what happened. A link that refuses stops
+   * the announcement — it was finishing the fact, and half a fact is not one.
+   */
+  private async finished(fact: string, payload: unknown): Promise<unknown> {
+    let carried = payload;
+    for (const link of this.pipes.get(fact) ?? []) {
+      const facade = this.container.resolve<Record<string, Function>>(link.door);
+      const answered = await facade[link.op]({ ...Invocation.empty, input: carried });
+
+      // A link that answers nothing SUPPRESSES the fact — every subscriber was then handed
+      // `null` and crashed reading it, one message each. It is refused rather than named,
+      // because a fact is what HAPPENED: the announcer already said so and cannot be told
+      // otherwise, `Emit` returning void. Filtering belongs to whoever announces, or to
+      // each reader; it is not a link's to decide for everyone.
+      if (answered === null || answered === undefined) {
+        throw new Error(
+          `${link.door}.${link.op} finishes the fact '${fact}' and answered nothing.\n`
+          + '  A link says what the fact IS, it does not take it back — the announcer has '
+          + 'already said it happened, and nothing can tell it otherwise.\n'
+          + '  Return the fact, amended or as it stands.',
+        );
+      }
+      carried = answered;
+    }
+
+    return carried;
+  }
+
   /**
    * The announcement realizes the fact's own `lifecycle.create` — a `created()` stamped, an id
    * generated, a default applied.
@@ -151,7 +309,7 @@ export class Emissions {
         } catch (cause) {
           throw new Error(`${fact} → ${door} could not be reached`, { cause });
         }
-        return facade[op]({ ...EMPTY_INVOCATION, input: payload });
+        return facade[op]({ ...Invocation.empty, input: payload });
       }),
     }));
   }
@@ -160,7 +318,17 @@ export class Emissions {
   private describeRefusal(fact: string, cause: unknown): string | undefined {
     const refusals = validationErrorsOf(cause);
     if (!refusals?.length) return undefined;
-    return `refused the shape — ${refusals.map((d) => `${d.path}: ${d.message}`).join(', ')}.`
+    return `refused the shape — ${refusals.map((d) => `${dotted(d.path)}: ${d.message}`).join(', ')}.`
       + ` If '${fact}' gained a field, this copy is older than the sender's: re-run \`fougere sync\`.`;
   }
 }
+
+/**
+ * The container key a declared CLASS NAME answers under — `RedactHandler` → `redactHandler`,
+ * the same key `facadeKeyOf` builds from an address.
+ */
+function doorOf(declared: string): string {
+  const key = lowerFirst(declared);
+
+  return key.endsWith('Handler') ? key : `${key}Handler`;
+}

package/src/boot/auth.ts

@@ -3,7 +3,7 @@
  * the contract between core and an `@fougere/auth-*` package.
  */
 import type { SchemaView } from '@fougere/schema';
-import type { Storage, StorageFactory } from '../storage.js';
+import type { Storage, StorageFactory } from '../storage/port.js';
 
 /** Lazy auth declaration written in fougere.config.ts. */
 export interface AuthConfig {