jinaga-server 3.5.5 → 3.7.0

package/src/authorization/authorization-keystore.ts

@@ -2,6 +2,7 @@ import {
     Authorization,
     AuthorizationEngine,
     AuthorizationRules,
+    DistributionDenialCode,
     DistributionEngine,
     DistributionRules,
     FactEnvelope,
@@ -17,10 +18,54 @@ import {
     factReferenceEquals
 } from "jinaga";
 
+export interface DistributionIntersectionBranch {
+    start: FactReference[];
+    specification: Specification;
+}
+
+// The engine failure that made a subscription reactive (authorized via
+// intersection) or denied. Carried so POST /feeds can report the structured
+// per-feed decision (issue #168 S1) without recomputing distribution.
+export interface DistributionDenial {
+    reason: string;
+    code: DistributionDenialCode;
+}
+
+export type DistributionBranchesResult =
+    // Pass-through authorized when `denial` is absent; authorized-via-
+    // intersection (reactive) when `denial` carries the engine failure that
+    // triggered the intersection.
+    | { type: "success"; branches: DistributionIntersectionBranch[]; denial?: DistributionDenial }
+    | { type: "denied"; reason: string; code: DistributionDenialCode };
+
+export type FeedResult =
+    | { type: "success"; feed: FactFeed }
+    | { type: "denied"; reason: string };
+
+export interface SubscriptionAuthorizer {
+    verifyDistributionOrIntersect(
+        userIdentity: UserIdentity | null,
+        specification: Specification,
+        namedStart: ReferencesByName
+    ): Promise<DistributionBranchesResult>;
+    feedPreVerified(
+        userIdentity: UserIdentity | null,
+        specification: Specification,
+        start: FactReference[],
+        bookmark: string
+    ): Promise<FactFeed>;
+    feedWithDistribution(
+        userIdentity: UserIdentity | null,
+        specification: Specification,
+        start: FactReference[],
+        bookmark: string
+    ): Promise<FeedResult>;
+}
+
 import { Keystore } from "../keystore";
 import { DistributedFactCache } from "./distributed-fact-cache";
 
-export class AuthorizationKeystore implements Authorization {
+export class AuthorizationKeystore implements Authorization, SubscriptionAuthorizer {
     private authorizationEngine: AuthorizationEngine | null;
     private distributionEngine: DistributionEngine | null;
     private distributedFacts: DistributedFactCache = new DistributedFactCache();
@@ -70,6 +115,14 @@ export class AuthorizationKeystore implements Authorization {
     }
 
     async feed(userIdentity: UserIdentity | null, specification: Specification, start: FactReference[], bookmark: string): Promise<FactFeed> {
+        const result = await this.feedWithDistribution(userIdentity, specification, start, bookmark);
+        if (result.type === "denied") {
+            throw new Forbidden(result.reason);
+        }
+        return result.feed;
+    }
+
+    async feedWithDistribution(userIdentity: UserIdentity | null, specification: Specification, start: FactReference[], bookmark: string): Promise<FeedResult> {
         if (this.distributionEngine) {
             const userReference: FactReference | null = userIdentity
                 ? await this.keystore.getUserFact(userIdentity)
@@ -80,18 +133,35 @@ export class AuthorizationKeystore implements Authorization {
             }), {} as ReferencesByName);
             const canDistribute = await this.distributionEngine.canDistributeToAll([specification], namedStart, userReference);
             if (canDistribute.type === "failure") {
-                throw new Forbidden(canDistribute.reason);
+                return { type: "denied", reason: canDistribute.reason };
             }
             const factFeed = await this.store.feed(specification, start, bookmark);
             const factReferences = factFeed.tuples
                 .flatMap(tuple => tuple.facts)
                 .filter((value, index, self) => self.findIndex(factReferenceEquals(value)) === index);
             this.distributedFacts.add(factReferences, userReference);
-            return factFeed;
+            return { type: "success", feed: factFeed };
         }
-        else {
-            return await this.store.feed(specification, start, bookmark);
+        return { type: "success", feed: await this.store.feed(specification, start, bookmark) };
+    }
+
+    async feedPreVerified(userIdentity: UserIdentity | null, specification: Specification, start: FactReference[], bookmark: string): Promise<FactFeed> {
+        // Caller has already established that this feed is safe to serve
+        // (e.g. produced by intersectForSubscribe — the spec lifts its own
+        // authorization condition into the matches and therefore self-
+        // filters). Skip the redundant per-query distribution check, but
+        // keep tracking the returned references so /load stays consistent.
+        const factFeed = await this.store.feed(specification, start, bookmark);
+        if (this.distributionEngine) {
+            const userReference: FactReference | null = userIdentity
+                ? await this.keystore.getUserFact(userIdentity)
+                : null;
+            const factReferences = factFeed.tuples
+                .flatMap(tuple => tuple.facts)
+                .filter((value, index, self) => self.findIndex(factReferenceEquals(value)) === index);
+            this.distributedFacts.add(factReferences, userReference);
         }
+        return factFeed;
     }
 
     async load(userIdentity: UserIdentity, references: FactReference[]) {
@@ -165,4 +235,35 @@ export class AuthorizationKeystore implements Authorization {
             throw new Forbidden(canDistribute.reason);
         }
     }
+
+    async verifyDistributionOrIntersect(
+        userIdentity: UserIdentity | null,
+        specification: Specification,
+        namedStart: ReferencesByName
+    ): Promise<DistributionBranchesResult> {
+        const start = specification.given.map(g => namedStart[g.label.name]);
+        if (!this.distributionEngine) {
+            return { type: "success", branches: [{ start, specification }] };
+        }
+        const userReference: FactReference | null = userIdentity
+            ? await this.keystore.getUserFact(userIdentity)
+            : null;
+        const targetFeeds = buildFeeds(specification);
+        const canDistribute = await this.distributionEngine.canDistributeToAll(targetFeeds, namedStart, userReference);
+        if (canDistribute.type === "success") {
+            return { type: "success", branches: [{ start, specification }] };
+        }
+        // Preserve the structured engine failure so the caller can classify
+        // the feed (issue #168 S1). `canDistribute` is narrowed to a failure
+        // here, so `code`/`reason` are available.
+        const denial: DistributionDenial = { reason: canDistribute.reason, code: canDistribute.code };
+        const result = await this.distributionEngine.intersectForSubscribe(start, specification, userReference);
+        if (!result.intersected) {
+            return { type: "denied", reason: denial.reason, code: denial.code };
+        }
+        // Authorized via intersection: the spec is denied for this user right
+        // now (denial carries why) but self-heals once the authorizing fact
+        // arrives. The router reports this as `reactive`.
+        return { type: "success", branches: result.branches, denial };
+    }
 }

package/src/feeds/feed-stream-session.ts

@@ -0,0 +1,386 @@
+import {
+    computeTupleSubsetHash,
+    FactManager,
+    FactReference,
+    FeedObject,
+    FeedResponse,
+    invertSpecification,
+    ProjectedResult,
+    Specification,
+    SpecificationListener,
+    Trace
+} from "jinaga";
+import { FeedResult } from "../authorization/authorization-keystore";
+import { Stream } from "../http/stream";
+
+/**
+ * A function that queries the feed for the next page of tuples, starting
+ * from the supplied bookmark. Returns a {@link FeedResult} so the session
+ * can keep the stream alive when distribution is denied at query time.
+ */
+export type FeedQuery = (bookmark: string) => Promise<FeedResult>;
+
+export interface FeedStreamSessionConfig {
+    /** Maximum number of pages to stream before giving up (infinite-loop guard). */
+    maxInitialPages: number;
+    /** Maximum number of references the waitlist may hold before the stream is dropped. */
+    waitlistCap: number;
+    /** Insert a small delay every N pages to avoid overwhelming the database. */
+    pageDelayEvery: number;
+    /** Length of the delay inserted by {@link pageDelayEvery}, in milliseconds. */
+    pageDelayMs: number;
+}
+
+export const defaultFeedStreamSessionConfig: FeedStreamSessionConfig = {
+    maxInitialPages: 1000,
+    waitlistCap: 50000,
+    pageDelayEvery: 10,
+    pageDelayMs: 10
+};
+
+interface FeedStreamSessionTelemetry {
+    initialPages: number;
+    referencesStreamed: number;
+    cycles: number;
+    syncFrames: number;
+    waitlistRestarts: number;
+    waitlistHighWater: number;
+}
+
+function referenceKey(reference: FactReference): string {
+    return `${reference.type}:${reference.hash}`;
+}
+
+function dedupeReferences(references: FactReference[]): FactReference[] {
+    const seen = new Set<string>();
+    const result: FactReference[] = [];
+    for (const reference of references) {
+        const key = referenceKey(reference);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(reference);
+        }
+    }
+    return result;
+}
+
+/**
+ * Per-connection proxy for a streaming feed subscription.
+ *
+ * The session funnels every fetch and stream operation through a single
+ * "query cycle" driven by the current bookmark. Inverse observers never
+ * fetch or stream directly; they only enqueue fact references onto a
+ * waitlist and wake the cycle. This serialization removes the race between
+ * listener callbacks and bookmark mutation, guarantees tuple completeness,
+ * and ensures no update is lost when facts arrive between pages.
+ *
+ * See docs/design/feeds-persistent-proxy-plan.md for the full design.
+ */
+export class FeedStreamSession {
+    private bookmark: string;
+    private readonly config: FeedStreamSessionConfig;
+
+    // Waitlist of fact references surfaced by inverse observers, keyed by
+    // "{type}:{hash}" so duplicates collapse. A reference stays on the
+    // waitlist until the tuple that contains it is streamed, preserving
+    // tuple completeness.
+    private readonly waitlist = new Map<string, FactReference>();
+
+    // Single-cycle execution guard. Only one runCycle() executes at a time;
+    // wake-ups that arrive while a cycle runs set needsCycle so the loop
+    // re-evaluates before returning.
+    private activeCycle = false;
+    private needsCycle = false;
+    private shuttingDown = false;
+
+    private listeners: SpecificationListener[] = [];
+    private readonly telemetry: FeedStreamSessionTelemetry = {
+        initialPages: 0,
+        referencesStreamed: 0,
+        cycles: 0,
+        syncFrames: 0,
+        waitlistRestarts: 0,
+        waitlistHighWater: 0
+    };
+
+    constructor(
+        private readonly query: FeedQuery,
+        private readonly factManager: FactManager,
+        private readonly feedDefinition: FeedObject,
+        private readonly startReferences: FactReference[],
+        private readonly givenHash: string,
+        private readonly stream: Stream<FeedResponse>,
+        initialBookmark: string,
+        private readonly connectionId: string = Math.random().toString(36).substring(2, 10),
+        config: Partial<FeedStreamSessionConfig> = {}
+    ) {
+        this.bookmark = initialBookmark;
+        this.config = { ...defaultFeedStreamSessionConfig, ...config };
+    }
+
+    /** Current number of references on the waitlist (observability/testing). */
+    get waitlistSize(): number {
+        return this.waitlist.size;
+    }
+
+    /**
+     * Register inverse and anchor observers, then kick off the initial
+     * paginated backfill. Resolves once the observers are registered; the
+     * cycle continues to run asynchronously, feeding the stream.
+     */
+    start(): void {
+        this.registerInverseListeners();
+        this.registerAnchorListeners();
+        // Kick off the initial backfill. Errors are isolated so a failed
+        // cycle never rejects the caller's setup path.
+        this.wake();
+    }
+
+    /**
+     * Tear down all observers and prevent any further cycles. Idempotent.
+     */
+    dispose(): void {
+        if (this.shuttingDown) {
+            return;
+        }
+        this.shuttingDown = true;
+        for (const listener of this.listeners) {
+            try {
+                this.factManager.removeSpecificationListener(listener);
+            } catch (error) {
+                Trace.error(error);
+            }
+        }
+        this.listeners = [];
+        // Use a stable metric name so a metrics backend does not see
+        // unbounded cardinality from per-connection IDs. The connection ID
+        // is logged separately for correlation.
+        Trace.info(`Feed stream session ${this.connectionId} closed`);
+        Trace.metric("Feed stream session closed", {
+            initialPages: this.telemetry.initialPages,
+            referencesStreamed: this.telemetry.referencesStreamed,
+            cycles: this.telemetry.cycles,
+            syncFrames: this.telemetry.syncFrames,
+            waitlistRestarts: this.telemetry.waitlistRestarts,
+            waitlistHighWater: this.telemetry.waitlistHighWater
+        });
+    }
+
+    /**
+     * Add fact references to the waitlist and wake the cycle. Called by the
+     * inverse observers; never fetches or streams directly.
+     */
+    onInverseMatch(references: FactReference[]): void {
+        if (this.shuttingDown) {
+            return;
+        }
+        for (const reference of references) {
+            this.waitlist.set(referenceKey(reference), reference);
+        }
+        if (this.waitlist.size > this.telemetry.waitlistHighWater) {
+            this.telemetry.waitlistHighWater = this.waitlist.size;
+        }
+        if (this.waitlist.size > this.config.waitlistCap) {
+            Trace.warn(`Feed stream session ${this.connectionId} waitlist exceeded cap ` +
+                `(${this.waitlist.size} > ${this.config.waitlistCap}); closing stream.`);
+            this.dispose();
+            this.stream.close();
+            return;
+        }
+        this.wake();
+    }
+
+    /**
+     * Start a cycle if one is not already running. If a cycle is active,
+     * mark that another pass is needed once it completes.
+     */
+    private wake(): void {
+        if (this.shuttingDown) {
+            return;
+        }
+        if (this.activeCycle) {
+            this.needsCycle = true;
+            return;
+        }
+        // Run the cycle without awaiting; isolate failures.
+        void this.runCycle().catch(error => Trace.error(error));
+    }
+
+    /**
+     * The single serialized query cycle. Pages through the feed until both
+     * the query returns no tuples and the waitlist is empty, then emits a
+     * SYNC frame. Guarded by activeCycle so no two cycles run concurrently.
+     */
+    private async runCycle(): Promise<void> {
+        if (this.activeCycle) {
+            this.needsCycle = true;
+            return;
+        }
+        this.activeCycle = true;
+        this.telemetry.cycles++;
+        try {
+            let pagesThisCycle = 0;
+            let keepGoing = true;
+            while (keepGoing && !this.shuttingDown) {
+                this.needsCycle = false;
+
+                const result = await this.query(this.bookmark);
+                if (this.shuttingDown) {
+                    break;
+                }
+                if (result.type === "denied") {
+                    // Distribution denied at query time. Keep the stream
+                    // alive (an authorizing fact may arrive later and wake a
+                    // new cycle) but stop the loop without emitting SYNC,
+                    // since we are not actually caught up.
+                    Trace.info(`Feed stream session ${this.connectionId} query denied: ${result.reason}`);
+                    break;
+                }
+
+                const feed = result.feed;
+                if (feed.tuples.length > 0) {
+                    const references = dedupeReferences(feed.tuples.flatMap(t => t.facts));
+                    this.streamPage(references, feed.bookmark);
+                    this.removeFromWaitlist(references);
+                    pagesThisCycle++;
+                    this.telemetry.initialPages++;
+
+                    if (feed.bookmark === this.bookmark) {
+                        // The store returned results but the bookmark did not
+                        // advance, meaning it cannot paginate further (e.g.
+                        // MemoryStore returns the full result set on every
+                        // call). Everything available has been delivered, so
+                        // treat this as caught-up: drop any waitlist entries
+                        // that the full page did not satisfy and emit SYNC.
+                        // Re-querying with the same bookmark would loop
+                        // forever re-delivering identical tuples.
+                        this.waitlist.clear();
+                        this.streamSync();
+                        keepGoing = false;
+                    }
+                    else {
+                        this.bookmark = feed.bookmark;
+                        if (pagesThisCycle >= this.config.maxInitialPages) {
+                            Trace.warn(`Feed stream session ${this.connectionId} hit max page limit ` +
+                                `(${this.config.maxInitialPages}); ending cycle.`);
+                            break;
+                        }
+                        if (this.config.pageDelayEvery > 0 &&
+                            pagesThisCycle % this.config.pageDelayEvery === 0) {
+                            await this.delay(this.config.pageDelayMs);
+                        }
+                        // Continue paging.
+                    }
+                }
+                else {
+                    // No tuples this query.
+                    if (this.waitlist.size === 0) {
+                        this.streamSync();
+                        keepGoing = false;
+                    }
+                    else if (this.needsCycle) {
+                        // A wake arrived during this query; re-run so the
+                        // just-arrived facts get a chance to produce tuples.
+                        this.telemetry.waitlistRestarts++;
+                    }
+                    else {
+                        // The waitlist holds references whose tuples are not
+                        // completable at the current bookmark (e.g. a missing
+                        // predecessor). They cannot produce a tuple now, so
+                        // drop them to avoid spinning and emit SYNC. A later
+                        // trigger will re-add them once they are completable.
+                        this.waitlist.clear();
+                        this.streamSync();
+                        keepGoing = false;
+                    }
+                }
+            }
+        } finally {
+            this.activeCycle = false;
+            // A wake that arrived as the loop exited must start a fresh
+            // cycle, since this one already cleared activeCycle.
+            if (this.needsCycle && !this.shuttingDown) {
+                this.needsCycle = false;
+                this.wake();
+            }
+        }
+    }
+
+    private streamPage(references: FactReference[], bookmark: string): void {
+        const response: FeedResponse = { references, bookmark };
+        this.telemetry.referencesStreamed += references.length;
+        this.stream.feed(response);
+    }
+
+    private streamSync(): void {
+        const response: FeedResponse = { references: [], bookmark: this.bookmark };
+        this.telemetry.syncFrames++;
+        this.stream.feed(response);
+    }
+
+    private removeFromWaitlist(references: FactReference[]): void {
+        for (const reference of references) {
+            this.waitlist.delete(referenceKey(reference));
+        }
+    }
+
+    private delay(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+
+    private registerInverseListeners(): void {
+        const inverses = invertSpecification(this.feedDefinition.feed);
+        for (const inverse of inverses) {
+            const listener = this.factManager.addSpecificationListener(
+                inverse.inverseSpecification,
+                async (results: ProjectedResult[]) => {
+                    if (this.shuttingDown) {
+                        return;
+                    }
+                    // Only enqueue results whose given subset matches this
+                    // subscription's given.
+                    const matching = results.filter(pr =>
+                        this.givenHash === computeTupleSubsetHash(pr.tuple, inverse.givenSubset));
+                    if (matching.length === 0) {
+                        return;
+                    }
+                    const references = dedupeReferences(
+                        matching.flatMap(pr => Object.values(pr.tuple)));
+                    this.onInverseMatch(references);
+                });
+            this.listeners.push(listener);
+        }
+    }
+
+    private registerAnchorListeners(): void {
+        // Anchor listeners (jinaga.js#129): the inverse-listener path only
+        // fires when a descendant of the given arrives. If the given fact
+        // itself isn't yet in the store when the client subscribes, no
+        // inverse can deliver results until the given is recorded. Register
+        // a listener per unique anchor that wakes the cycle the moment a
+        // saved fact matches the anchor's (type, hash). The anchor itself is
+        // not added to the waitlist; the query will surface its descendants.
+        const uniqueAnchors = this.startReferences.filter((s, i, arr) =>
+            arr.findIndex(other => other.type === s.type && other.hash === s.hash) === i);
+        for (const anchor of uniqueAnchors) {
+            const anchorSpec: Specification = {
+                given: [{ label: { name: "x", type: anchor.type }, conditions: [] }],
+                matches: [],
+                projection: { type: "fact", label: "x" }
+            };
+            const listener = this.factManager.addSpecificationListener(anchorSpec, async (results: ProjectedResult[]) => {
+                if (this.shuttingDown) {
+                    return;
+                }
+                const matched = results.some(pr => {
+                    const ref = pr.tuple && (pr.tuple as any).x;
+                    return ref && ref.type === anchor.type && ref.hash === anchor.hash;
+                });
+                if (matched) {
+                    this.wake();
+                }
+            });
+            this.listeners.push(listener);
+        }
+    }
+}