@beignet/core 0.0.53 → 0.0.55

package/src/broadcasting/index.ts

@@ -0,0 +1,175 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  eventTransportValuesEqual,
+  toEventTransportValue,
+} from "../events/transport.js";
+
+/** Browser-visible channel contract. Authorization belongs in a server binding. */
+export interface ChannelDefinition<
+  Name extends string = string,
+  Params extends StandardSchemaV1<
+    unknown,
+    Record<string, string>
+  > = StandardSchemaV1<unknown, Record<string, string>>,
+  Events extends Record<string, StandardSchemaV1> = Record<
+    string,
+    StandardSchemaV1
+  >,
+> {
+  readonly kind: "channel";
+  readonly name: Name;
+  readonly params: Params;
+  readonly events: Events;
+}
+
+export type InferChannelParams<C extends ChannelDefinition> =
+  StandardSchemaV1.InferOutput<C["params"]>;
+export type InferChannelEvent<C extends ChannelDefinition> = {
+  [Event in keyof C["events"] & string]: {
+    event: Event;
+    data: StandardSchemaV1.InferOutput<C["events"][Event]>;
+  };
+}[keyof C["events"] & string];
+
+/** Protocol defaults and safety limits shared by clients, endpoints, and providers. */
+export const broadcastLimits = Object.freeze({
+  subscriptions: 20,
+  requestBytes: 8_192,
+  payloadBytes: 65_536,
+  bufferedBytes: 1_048_576,
+  defaultLifetimeMs: 60_000,
+  maxLifetimeMs: 3_600_000,
+  lifetimeGraceMs: 5_000,
+  heartbeatMs: 25_000,
+  readyTimeoutMs: 10_000,
+});
+
+/** Invalid channel configuration or untrusted protocol input. */
+export class BroadcastValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BroadcastValidationError";
+  }
+}
+
+const namePattern = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+
+export function defineChannel<
+  const Name extends string,
+  Params extends StandardSchemaV1<unknown, Record<string, string>>,
+  const Events extends Record<string, StandardSchemaV1>,
+>(
+  name: Name,
+  options: { params: Params; events: Events },
+): ChannelDefinition<Name, Params, Events> {
+  if (!namePattern.test(name))
+    throw new BroadcastValidationError("Invalid broadcast channel name");
+  const events = Object.entries(options.events);
+  if (!events.length || events.some(([event]) => !namePattern.test(event))) {
+    throw new BroadcastValidationError(
+      `Channel ${name} needs valid event names`,
+    );
+  }
+  return Object.freeze({
+    kind: "channel",
+    name,
+    params: options.params,
+    events: Object.freeze({ ...options.events }),
+  });
+}
+
+/** Validate both sides of a transport boundary; schema transforms must be stable. */
+async function parseStable(
+  schema: StandardSchemaV1,
+  input: unknown,
+  label: string,
+): Promise<unknown> {
+  try {
+    const parsed = await schema["~standard"].validate(input);
+    if (parsed.issues) throw new BroadcastValidationError(`Invalid ${label}`);
+    const canonical = toEventTransportValue(label, parsed.value);
+    const second = await schema["~standard"].validate(canonical);
+    if (
+      second.issues ||
+      !eventTransportValuesEqual(
+        canonical,
+        toEventTransportValue(label, second.value),
+      )
+    ) {
+      throw new BroadcastValidationError(
+        `Unstable transport schema for ${label}`,
+      );
+    }
+    return canonical;
+  } catch (error) {
+    if (error instanceof BroadcastValidationError) throw error;
+    throw new BroadcastValidationError(`Invalid ${label}`);
+  }
+}
+
+/** Provider and transport boundary validation. Uses parsed, canonical parameters. */
+export async function parseChannelParams<C extends ChannelDefinition>(
+  channel: C,
+  input: unknown,
+): Promise<InferChannelParams<C>> {
+  const parsed = await parseStable(
+    channel.params,
+    input,
+    `${channel.name} parameters`,
+  );
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed) ||
+    Object.values(parsed).some((value) => typeof value !== "string")
+  ) {
+    throw new BroadcastValidationError(
+      `Channel ${channel.name} parameters must be a flat string record`,
+    );
+  }
+  if (
+    new TextEncoder().encode(JSON.stringify(parsed)).byteLength >
+    broadcastLimits.requestBytes
+  ) {
+    throw new BroadcastValidationError(
+      `Channel ${channel.name} parameters are too large`,
+    );
+  }
+  return parsed as InferChannelParams<C>;
+}
+
+/** Provider and browser boundary validation. Event names select their schema. */
+export async function parseChannelEvent<C extends ChannelDefinition>(
+  channel: C,
+  input: { event: string; data: unknown },
+): Promise<InferChannelEvent<C>> {
+  if (!Object.hasOwn(channel.events, input.event))
+    throw new BroadcastValidationError(
+      `Unknown event on channel ${channel.name}`,
+    );
+  const data = await parseStable(
+    channel.events[input.event],
+    input.data,
+    `${channel.name}.${input.event}`,
+  );
+  if (
+    new TextEncoder().encode(JSON.stringify(data)).byteLength >
+    broadcastLimits.payloadBytes
+  ) {
+    throw new BroadcastValidationError(
+      `Channel ${channel.name} payload is too large`,
+    );
+  }
+  return { event: input.event, data } as InferChannelEvent<C>;
+}
+
+/** Collision-free identity independent of parameter property order. Parse parameters first. */
+export function channelKey(
+  channel: string,
+  params: Readonly<Record<string, string>>,
+): string {
+  return JSON.stringify([
+    channel,
+    Object.entries(params).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  ]);
+}

package/src/broadcasting/server.ts

@@ -0,0 +1,352 @@
+import "../server-only.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  BroadcastValidationError,
+  broadcastLimits,
+  type ChannelDefinition,
+  channelKey,
+  type InferChannelEvent,
+  type InferChannelParams,
+  parseChannelEvent,
+  parseChannelParams,
+} from "./index.js";
+
+/** Server-authenticated scope captured at the originating HTTP boundary. JSON-safe for jobs. */
+export interface BroadcastOrigin {
+  readonly version: 1;
+  readonly clientId: string;
+  readonly scope: string;
+}
+
+const clientIdPattern = /^[a-zA-Z0-9_-]{22,128}$/;
+
+function parseOrigin(value: unknown): BroadcastOrigin | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as Record<string, unknown>;
+  if (
+    candidate.version !== 1 ||
+    typeof candidate.clientId !== "string" ||
+    !clientIdPattern.test(candidate.clientId) ||
+    typeof candidate.scope !== "string" ||
+    candidate.scope.length === 0 ||
+    candidate.scope.length > 2_048
+  )
+    return undefined;
+  return { version: 1, clientId: candidate.clientId, scope: candidate.scope };
+}
+
+/** Validate an origin already captured by a trusted server for a job payload. */
+export const broadcastOriginSchema: StandardSchemaV1<unknown, BroadcastOrigin> =
+  {
+    "~standard": {
+      version: 1,
+      vendor: "beignet",
+      validate(value) {
+        const origin = parseOrigin(value);
+        return origin
+          ? { value: origin }
+          : { issues: [{ message: "Invalid broadcast origin" }] };
+      },
+    },
+  };
+
+/** Never derive principal, tenant, or namespace from the optional client header. */
+export function resolveBroadcastOrigin(options: {
+  headers: Headers;
+  principalId?: string | null;
+  tenantId?: string | null;
+  namespace: string;
+}): BroadcastOrigin | undefined {
+  if (!options.principalId || !options.namespace) return undefined;
+  return parseOrigin({
+    version: 1,
+    clientId: options.headers.get("X-Beignet-Broadcast-Client"),
+    scope: JSON.stringify([
+      options.namespace,
+      options.tenantId ?? null,
+      options.principalId,
+    ]),
+  });
+}
+
+export type BroadcastPublication<C extends ChannelDefinition> =
+  InferChannelEvent<C> & {
+    params: InferChannelParams<C>;
+    excludeOrigin?: BroadcastOrigin;
+  };
+
+/** Readiness proves initial subscription only. Continuity loss requires reconnect and refetch. */
+export interface BroadcastSubscription {
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+
+export interface BroadcastPort {
+  /** Resolves when accepted by the provider, including when nobody is subscribed. */
+  publish<C extends ChannelDefinition>(
+    channel: C,
+    publication: BroadcastPublication<C>,
+  ): Promise<void>;
+  subscribe<C extends ChannelDefinition>(
+    channel: C,
+    options: {
+      params: InferChannelParams<C>;
+      onEvent: (
+        event: InferChannelEvent<C>,
+        metadata: { excludeOrigin?: BroadcastOrigin },
+      ) => void;
+      onDisconnect: () => void;
+    },
+  ): BroadcastSubscription;
+}
+
+/** Internal transport envelope carried by broadcast providers, never a browser payload. */
+export interface BroadcastEnvelope {
+  version: 1;
+  channel: string;
+  params: Record<string, string>;
+  event: string;
+  data: unknown;
+  excludeOrigin?: BroadcastOrigin;
+}
+
+/** Low-level adapter contract. Subscription callbacks must be isolated from publishers. */
+export interface BroadcastTransport {
+  publish(key: string, envelope: BroadcastEnvelope): Promise<void>;
+  subscribe(
+    key: string,
+    options: {
+      onMessage: (envelope: unknown) => void;
+      onDisconnect: () => void;
+    },
+  ): BroadcastSubscription;
+}
+
+/** Shared validation and cleanup for provider implementations. */
+export function createBroadcastPort(
+  transport: BroadcastTransport,
+): BroadcastPort {
+  return {
+    async publish(channel, publication) {
+      const params = await parseChannelParams(channel, publication.params);
+      const event = await parseChannelEvent(channel, publication);
+      const excludeOrigin =
+        publication.excludeOrigin === undefined
+          ? undefined
+          : parseOrigin(publication.excludeOrigin);
+      if (publication.excludeOrigin !== undefined && !excludeOrigin)
+        throw new BroadcastValidationError("Invalid broadcast origin");
+      await transport.publish(channelKey(channel.name, params), {
+        version: 1,
+        channel: channel.name,
+        params,
+        ...event,
+        ...(excludeOrigin ? { excludeOrigin } : {}),
+      });
+    },
+    subscribe(channel, options) {
+      let stopped = false;
+      let failed = false;
+      let subscription: BroadcastSubscription | undefined;
+      let queued = 0;
+      let queuedBytes = 0;
+      let pending = Promise.resolve();
+      let cancel: (() => void) | undefined;
+      let cleanup: Promise<void> | undefined;
+      const release = () =>
+        (cleanup ??= subscription?.unsubscribe() ?? Promise.resolve());
+      const disconnect = () => {
+        if (stopped || failed) return;
+        failed = true;
+        try {
+          options.onDisconnect();
+        } catch {
+          /* Consumer callbacks cannot break provider lifecycle. */
+        }
+      };
+      const initialize = (async () => {
+        const params = await parseChannelParams(channel, options.params);
+        if (stopped) return;
+        const key = channelKey(channel.name, params);
+        subscription = transport.subscribe(key, {
+          onDisconnect: disconnect,
+          onMessage(value) {
+            if (stopped || failed) return;
+            let bytes: number;
+            try {
+              bytes = new TextEncoder().encode(
+                JSON.stringify(value),
+              ).byteLength;
+            } catch {
+              disconnect();
+              return;
+            }
+            if (
+              bytes >
+                broadcastLimits.payloadBytes +
+                  broadcastLimits.requestBytes +
+                  16_384 ||
+              queuedBytes + bytes > broadcastLimits.bufferedBytes
+            ) {
+              disconnect();
+              return;
+            }
+            if (++queued > 128) {
+              disconnect();
+              return;
+            }
+            queuedBytes += bytes;
+            pending = pending
+              .then(async () => {
+                if (stopped || failed) return;
+                if (!value || typeof value !== "object")
+                  throw new BroadcastValidationError(
+                    "Invalid broadcast envelope",
+                  );
+                const envelope = value as BroadcastEnvelope;
+                if (envelope.version !== 1 || envelope.channel !== channel.name)
+                  throw new BroadcastValidationError(
+                    "Invalid broadcast envelope",
+                  );
+                const receivedParams = await parseChannelParams(
+                  channel,
+                  envelope.params,
+                );
+                if (channelKey(channel.name, receivedParams) !== key)
+                  throw new BroadcastValidationError(
+                    "Broadcast channel mismatch",
+                  );
+                const event = await parseChannelEvent(channel, envelope);
+                const excludeOrigin =
+                  envelope.excludeOrigin === undefined
+                    ? undefined
+                    : parseOrigin(envelope.excludeOrigin);
+                if (envelope.excludeOrigin !== undefined && !excludeOrigin)
+                  throw new BroadcastValidationError(
+                    "Invalid broadcast origin",
+                  );
+                if (!stopped && !failed)
+                  await options.onEvent(event, { excludeOrigin });
+              })
+              .catch(disconnect)
+              .finally(() => {
+                queued--;
+                queuedBytes -= bytes;
+              });
+          },
+        });
+        await subscription.ready;
+        if (stopped) await release();
+        if (failed)
+          throw new Error(
+            "Broadcast subscription lost continuity before readiness",
+          );
+      })();
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      const ready = Promise.race([
+        initialize,
+        new Promise<never>((_, reject) => {
+          cancel = () => reject(new Error("Broadcast subscription cancelled"));
+          timeout = setTimeout(
+            () =>
+              reject(new Error("Broadcast subscription readiness timed out")),
+            broadcastLimits.readyTimeoutMs,
+          );
+        }),
+      ])
+        .catch((error) => {
+          stopped = true;
+          void release().catch(() => undefined);
+          throw error;
+        })
+        .finally(() => {
+          if (timeout !== undefined) clearTimeout(timeout);
+          cancel = undefined;
+        });
+      // Callers still observe rejection through ready; early cancellation must not leak a rejection.
+      void ready.catch(() => undefined);
+      return {
+        ready,
+        async unsubscribe() {
+          stopped = true;
+          cancel?.();
+          await ready.catch(() => undefined);
+          await release();
+        },
+      };
+    },
+  };
+}
+
+export interface ChannelBinding<Ctx> {
+  readonly kind: "channel-binding";
+  readonly channel: ChannelDefinition;
+  authorize: (args: {
+    ctx: Ctx;
+    params: Record<string, string>;
+  }) => void | Promise<void>;
+}
+
+export interface ChannelRegistry<Ctx> {
+  readonly kind: "channel-registry";
+  readonly bindings: readonly ChannelBinding<Ctx>[];
+  get(name: string): ChannelBinding<Ctx> | undefined;
+}
+
+/** Bind every channel explicitly, including public channels. */
+export function createBroadcasting<Ctx>() {
+  function defineChannelBinding<C extends ChannelDefinition>(
+    channel: C,
+    options: {
+      authorize: (args: {
+        ctx: Ctx;
+        params: InferChannelParams<C>;
+      }) => void | Promise<void>;
+    },
+  ): ChannelBinding<Ctx> {
+    return Object.freeze({
+      kind: "channel-binding" as const,
+      channel,
+      authorize: ({
+        ctx,
+        params,
+      }: {
+        ctx: Ctx;
+        params: Record<string, string>;
+      }) => options.authorize({ ctx, params: params as InferChannelParams<C> }),
+    });
+  }
+  function defineChannelRegistry(
+    bindings: readonly ChannelBinding<Ctx>[],
+  ): ChannelRegistry<Ctx> {
+    const byName = new Map<string, ChannelBinding<Ctx>>();
+    for (const binding of bindings) {
+      if (byName.has(binding.channel.name))
+        throw new BroadcastValidationError(
+          `Duplicate channel ${binding.channel.name}`,
+        );
+      byName.set(binding.channel.name, binding);
+    }
+    return Object.freeze({
+      kind: "channel-registry",
+      bindings: Object.freeze([...bindings]),
+      get: (name: string) => byName.get(name),
+    });
+  }
+  return { defineChannelBinding, defineChannelRegistry };
+}
+
+/** Validate a configurable deadline without allowing an unbounded stream. */
+export function broadcastLifetime(
+  value: number = broadcastLimits.defaultLifetimeMs,
+): number {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < 1 ||
+    value > broadcastLimits.maxLifetimeMs
+  )
+    throw new BroadcastValidationError(
+      `Broadcast maxLifetimeMs must be a safe integer between 1 and ${broadcastLimits.maxLifetimeMs} milliseconds`,
+    );
+  return value;
+}

package/src/notifications/index.ts

@@ -1,4 +1,9 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ChannelDefinition } from "../broadcasting/index.js";
+import type {
+  BroadcastPort,
+  BroadcastPublication,
+} from "../broadcasting/server.js";
 import {
   createJobs,
   type JobDef,
@@ -1345,6 +1350,33 @@ export function defineMailNotificationChannel<
   };
 }
 
+/** Deliver a typed browser hint through the existing notification delivery pipeline.
+ * `sent` means provider acceptance, including when the recipient is offline.
+ * Return undefined to skip. Persistent inbox writes and their outbox ordering belong to the app.
+ */
+export function defineBroadcastNotificationChannel<
+  C extends ChannelDefinition,
+  Payload extends StandardSchema,
+  Ctx extends { ports: { broadcast: BroadcastPort } },
+>(options: {
+  channel: C;
+  render: (
+    args: NotificationChannelHandleArgs<Payload, Ctx>,
+  ) => MaybePromise<BroadcastPublication<NoInfer<C>> | undefined>;
+}): NotificationChannelHandler<Payload, Ctx> {
+  return async (args) => {
+    const publication = await options.render(args);
+    if (!publication)
+      return {
+        channel: args.channel,
+        status: "skipped",
+        reason: "No broadcast was returned.",
+      };
+    await args.ctx.ports.broadcast.publish(options.channel, publication);
+    return { channel: args.channel, status: "sent" };
+  };
+}
+
 /**
  * Create an in-memory notification port for tests and examples.
  *

package/src/ports/redaction.ts

@@ -28,6 +28,9 @@ export const DEFAULT_SENSITIVE_KEYS = [
   "accesskey",
   "jwt",
   "session",
+  "x-beignet-broadcast-client",
+  "broadcastorigin",
+  "excludeorigin",
 ] as const;
 
 /**

package/src/server/server.ts

@@ -29,6 +29,7 @@ import { createContextFinalizer, resolveServerContext } from "./context.js";
 import type { ContractLike, ResolveContract } from "./contract-like.js";
 import { resolveContract } from "./contract-like.js";
 import type {
+  AddedCtxFromHooks,
   Handler,
   HttpRequestLike,
   HttpResponse,
@@ -312,7 +313,11 @@ export interface ServerInstance<
    * are not added to the route registry; mount the returned handler at the
    * route's own path.
    */
-  rawRoute: (init: RawRouteInit) => RawRouteBuilder<Ctx>;
+  rawRoute: <
+    const Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+  >(
+    init: RawRouteInit & { hooks?: Hooks },
+  ) => RawRouteBuilder<Ctx & AddedCtxFromHooks<Hooks>>;
   /**
    * Build a fully assembled request context from a framework-neutral request.
    *
@@ -960,9 +965,9 @@ export async function createServer<
           finalPorts,
           contextRuntime,
           rawRouteContract(init),
-          fn,
+          fn as Handler<Ctx, HttpContractConfig>,
           hooks,
-          [],
+          (init.hooks ?? []) as readonly RouteHook<unknown, object>[],
           { rawRoute: true },
         );
         // The adapter owns routing for raw routes — the handler is mounted