@portalshq/capability-queue-broadcast 0.1.7 → 0.1.9

package/README.md

@@ -2,6 +2,12 @@
 
 Server-only producer API for one isolated Queue Broadcast Server endpoint.
 
+`ContentQueuePipeline` is the reusable producer preparation boundary. It
+deduplicates channel/run/content identities, bounds concurrent preparation and
+measured duration/bytes/count, accounts for shared visuals once, commits
+results in enqueue order, and exposes staging/release/completion acknowledgments.
+Applications provide content preparation and persistence callbacks.
+
 The queue is deliberately separate from playback: a trusted application backend
 uses this package to enqueue and observe jobs; its browser player gets only the
 public HLS manifest returned by `getPlayback()`. Use

package/dist/content-pipeline.d.ts

@@ -0,0 +1,66 @@
+export type ContentQueueState = "queued" | "preparing" | "prepared" | "staged" | "released" | "completed" | "terminal-failed" | "cancelled";
+export interface ContentQueueIdentity {
+    channelId: string;
+    runEpoch: string;
+    contentKey: string;
+    ordinal: number;
+}
+export interface ContentCapacity {
+    durationMs: number;
+    bytes: number;
+    contentCount: number;
+    visualKey?: string;
+}
+export interface ContentQueueLimits {
+    maxInFlight: number;
+    maxDurationMs?: number;
+    maxBytes?: number;
+    maxContentCount?: number;
+}
+export interface ContentQueueObservation {
+    identity: ContentQueueIdentity;
+    state: ContentQueueState;
+    sequence: number;
+    error?: unknown;
+}
+export interface ContentQueuePipelineOptions<TRequest, TPrepared> {
+    limits: ContentQueueLimits;
+    identity(request: TRequest): ContentQueueIdentity;
+    estimate(request: TRequest): ContentCapacity;
+    measure(prepared: TPrepared, request: TRequest): ContentCapacity;
+    prepare(request: TRequest, signal: AbortSignal): Promise<TPrepared>;
+    /** Commits completions in enqueue order, even when preparation finishes out of order. */
+    commit(observation: ContentQueueObservation, prepared: TPrepared | undefined, request: TRequest): Promise<void>;
+    onObservation?: (observation: ContentQueueObservation) => void;
+}
+export interface ContentQueueTicket<TPrepared> {
+    identity: ContentQueueIdentity;
+    completion: Promise<TPrepared>;
+}
+/** Bounded, ordered preparation for queue-broadcast producers. */
+export declare class ContentQueuePipeline<TRequest, TPrepared> {
+    private readonly options;
+    private readonly work;
+    private readonly pending;
+    private nextSequence;
+    private nextCommitSequence;
+    private active;
+    private committing;
+    private stopped;
+    constructor(options: ContentQueuePipelineOptions<TRequest, TPrepared>);
+    enqueue(request: TRequest): ContentQueueTicket<TPrepared>;
+    /** Update queue lifecycle after preparation without creating another state owner. */
+    acknowledge(identity: ContentQueueIdentity, state: Extract<ContentQueueState, "staged" | "released" | "completed">): void;
+    snapshot(): readonly ContentQueueObservation[];
+    capacity(): ContentCapacity;
+    private capacityExcluding;
+    private assertMeasuredCapacity;
+    private assertCapacityAgainst;
+    stop(reason?: unknown): Promise<void>;
+    private assertCapacity;
+    private drain;
+    private run;
+    private commitReady;
+    private observe;
+    private toObservation;
+}

package/dist/content-pipeline.js

@@ -0,0 +1,231 @@
+/** Bounded, ordered preparation for queue-broadcast producers. */
+export class ContentQueuePipeline {
+    options;
+    work = new Map();
+    pending = [];
+    nextSequence = 1;
+    nextCommitSequence = 1;
+    active = 0;
+    committing = false;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+        const { limits } = options;
+        assertPositiveInteger("maxInFlight", limits.maxInFlight);
+        assertOptionalLimit("maxDurationMs", limits.maxDurationMs);
+        assertOptionalLimit("maxBytes", limits.maxBytes);
+        assertOptionalLimit("maxContentCount", limits.maxContentCount);
+    }
+    enqueue(request) {
+        if (this.stopped)
+            throw new Error("ContentQueuePipeline is stopped");
+        const identity = normalizeIdentity(this.options.identity(request));
+        const key = identityKey(identity);
+        const existing = this.work.get(key);
+        if (existing)
+            return { identity: existing.identity, completion: itemCompletion(existing) };
+        const estimate = normalizeCapacity(this.options.estimate(request));
+        this.assertCapacity(estimate);
+        let resolve;
+        let reject;
+        const completion = new Promise((res, rej) => { resolve = res; reject = rej; });
+        const item = {
+            sequence: this.nextSequence++, key, identity, request, estimate, state: "queued",
+            controller: new AbortController(), resolve, reject,
+        };
+        Object.defineProperty(item, "completion", { value: completion });
+        this.work.set(key, item);
+        this.pending.push(item);
+        this.observe(item);
+        this.drain();
+        return { identity, completion };
+    }
+    /** Update queue lifecycle after preparation without creating another state owner. */
+    acknowledge(identity, state) {
+        const item = this.work.get(identityKey(normalizeIdentity(identity)));
+        if (!item)
+            throw new Error("Unknown content queue identity");
+        const allowed = item.state === "prepared"
+            ? state === "staged"
+            : item.state === "staged"
+                ? state === "released"
+                : item.state === "released" && state === "completed";
+        if (!allowed)
+            throw new Error(`Invalid content queue transition ${item.state} -> ${state}`);
+        item.state = state;
+        this.observe(item);
+    }
+    snapshot() {
+        return [...this.work.values()].sort((a, b) => a.sequence - b.sequence).map((item) => this.toObservation(item));
+    }
+    capacity() {
+        return capacityOf([...this.work.values()].filter((item) => !isTerminal(item.state)));
+    }
+    capacityExcluding(excluded) {
+        return capacityOf([...this.work.values()].filter((item) => item !== excluded && !isTerminal(item.state)));
+    }
+    assertMeasuredCapacity(item, candidate) {
+        this.assertCapacityAgainst(this.capacityExcluding(item), candidate, item);
+    }
+    assertCapacityAgainst(current, candidate, excluded) {
+        const sharesVisual = candidate.visualKey && [...this.work.values()].some((item) => {
+            if (item === excluded || isTerminal(item.state))
+                return false;
+            return (item.actual ?? item.estimate).visualKey === candidate.visualKey;
+        });
+        const bytes = current.bytes + (sharesVisual ? 0 : candidate.bytes);
+        const { limits } = this.options;
+        if (limits.maxDurationMs !== undefined && current.durationMs + candidate.durationMs > limits.maxDurationMs)
+            throw capacityError("duration");
+        if (limits.maxBytes !== undefined && bytes > limits.maxBytes)
+            throw capacityError("bytes");
+        if (limits.maxContentCount !== undefined && current.contentCount + candidate.contentCount > limits.maxContentCount)
+            throw capacityError("content count");
+    }
+    async stop(reason = new Error("ContentQueuePipeline stopped")) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        for (const item of this.work.values()) {
+            if (isTerminal(item.state))
+                continue;
+            item.controller.abort(reason);
+            if (item.state !== "preparing") {
+                item.state = "cancelled";
+                item.error = reason;
+                this.observe(item);
+            }
+        }
+        this.pending.length = 0;
+        await this.commitReady();
+        await Promise.allSettled([...this.work.values()].map((item) => itemCompletion(item)));
+    }
+    assertCapacity(candidate) {
+        this.assertCapacityAgainst(this.capacity(), candidate);
+    }
+    drain() {
+        while (!this.stopped && this.active < this.options.limits.maxInFlight) {
+            const item = this.pending.shift();
+            if (!item)
+                return;
+            this.active += 1;
+            item.state = "preparing";
+            this.observe(item);
+            void this.run(item);
+        }
+    }
+    async run(item) {
+        try {
+            const prepared = await this.options.prepare(item.request, item.controller.signal);
+            if (item.controller.signal.aborted || this.stopped)
+                throw item.controller.signal.reason ?? new Error("cancelled");
+            const actual = normalizeCapacity(this.options.measure(prepared, item.request));
+            this.assertMeasuredCapacity(item, actual);
+            item.prepared = prepared;
+            item.actual = actual;
+            item.state = "prepared";
+        }
+        catch (error) {
+            item.error = error;
+            item.state = item.controller.signal.aborted || this.stopped ? "cancelled" : "terminal-failed";
+        }
+        finally {
+            this.active -= 1;
+            this.observe(item);
+            await this.commitReady();
+            this.drain();
+        }
+    }
+    async commitReady() {
+        if (this.committing)
+            return;
+        this.committing = true;
+        try {
+            while (true) {
+                const item = [...this.work.values()].find((candidate) => candidate.sequence === this.nextCommitSequence);
+                if (!item || !["prepared", "terminal-failed", "cancelled"].includes(item.state))
+                    return;
+                const observation = this.toObservation(item);
+                try {
+                    await this.options.commit(observation, item.prepared, item.request);
+                    if (item.state === "prepared")
+                        item.resolve(item.prepared);
+                    else
+                        item.reject(item.error);
+                    this.nextCommitSequence += 1;
+                }
+                catch (error) {
+                    item.error = error;
+                    item.state = "terminal-failed";
+                    this.observe(item);
+                    item.reject(error);
+                    this.nextCommitSequence += 1;
+                }
+            }
+        }
+        finally {
+            this.committing = false;
+            const next = [...this.work.values()].find((candidate) => candidate.sequence === this.nextCommitSequence);
+            if (next && ["prepared", "terminal-failed", "cancelled"].includes(next.state))
+                void this.commitReady();
+        }
+    }
+    observe(item) {
+        this.options.onObservation?.(this.toObservation(item));
+    }
+    toObservation(item) {
+        return { identity: item.identity, state: item.state, sequence: item.sequence, ...(item.error === undefined ? {} : { error: item.error }) };
+    }
+}
+function capacityOf(current) {
+    const visualKeys = new Set();
+    return current.reduce((total, item) => {
+        const measure = item.actual ?? item.estimate;
+        const countVisual = !measure.visualKey || !visualKeys.has(measure.visualKey);
+        if (measure.visualKey)
+            visualKeys.add(measure.visualKey);
+        total.durationMs += measure.durationMs;
+        total.bytes += countVisual ? measure.bytes : 0;
+        total.contentCount += measure.contentCount;
+        return total;
+    }, { durationMs: 0, bytes: 0, contentCount: 0 });
+}
+function itemCompletion(item) {
+    return item.completion;
+}
+function normalizeIdentity(identity) {
+    const result = { ...identity, channelId: identity.channelId.trim(), runEpoch: identity.runEpoch.trim(), contentKey: identity.contentKey.trim() };
+    if (!result.channelId || !result.runEpoch || !result.contentKey)
+        throw new TypeError("content identity fields are required");
+    if (!Number.isInteger(result.ordinal) || result.ordinal < 0)
+        throw new TypeError("ordinal must be a non-negative integer");
+    return result;
+}
+function identityKey(identity) {
+    return JSON.stringify([identity.channelId, identity.runEpoch, identity.contentKey, identity.ordinal]);
+}
+function normalizeCapacity(value) {
+    for (const [name, amount] of Object.entries({ durationMs: value.durationMs, bytes: value.bytes, contentCount: value.contentCount })) {
+        if (!Number.isFinite(amount) || amount < 0)
+            throw new TypeError(`${name} must be non-negative`);
+    }
+    if (!Number.isInteger(value.contentCount))
+        throw new TypeError("contentCount must be an integer");
+    return { ...value, visualKey: value.visualKey?.trim() || undefined };
+}
+function isTerminal(state) {
+    return state === "completed" || state === "terminal-failed" || state === "cancelled";
+}
+function capacityError(kind) {
+    const error = new Error(`Content queue ${kind} capacity exceeded`);
+    error.name = "ContentQueueCapacityError";
+    return error;
+}
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1)
+        throw new TypeError(`${name} must be a positive integer`);
+}
+function assertOptionalLimit(name, value) {
+    if (value !== undefined && (!Number.isFinite(value) || value < 0))
+        throw new TypeError(`${name} must be non-negative`);
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./client.js";
+export * from "./content-pipeline.js";
 export * from "./generated/api.js";
 export * from "./streaming/index.js";
 export * from "./monitoring/metrics.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./client.js";
+export * from "./content-pipeline.js";
 // Low-level OpenAPI client. Prefer QueueBroadcastClient for application code.
 export * from "./generated/api.js";
 // Streaming infrastructure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portalshq/capability-queue-broadcast",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/portalshq/portals-cloud.git",
@@ -22,8 +22,8 @@
     "generate:check": "npm run generate && npm run typecheck"
   },
   "dependencies": {
-    "@portalshq/capability-realtime-fanout": "^0.1.6",
-    "@portalshq/capability-video-delivery": "^0.1.6"
+    "@portalshq/capability-realtime-fanout": "^0.1.8",
+    "@portalshq/capability-video-delivery": "^0.1.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",