@fishenv/http 0.0.2 → 0.0.4

package/dist/ws/channels/channel.d.ts

@@ -0,0 +1,175 @@
+/**
+ * `channel()` — the server-side implementation of a channel, either from a
+ * shared `c.channel()` contract or defined inline.
+ *
+ * ```ts
+ * const roomImpl = channel(contract.room)
+ *   .join(async ({ ctx, path, data }) => ({ history: await load(path.roomId) }))
+ *   .on("message", async ({ data, channel }) => {
+ *     channel.broadcast("message", saved);
+ *     return { id: saved.id };
+ *   });
+ * ```
+ *
+ * Builders are immutable. The type parameters track which client events have
+ * handlers and whether an authorizer exists, so `.channels([...])` rejects
+ * incomplete implementations at compile time (and again at `build()`).
+ */
+import type * as v from "valibot";
+import { type AnyChannelContract, ChannelContract, type InferChannel } from "../../contract/index.ts";
+import { type AnySchema, type DIContainer } from "../../core/index.ts";
+import type { WsConnection } from "../connection.ts";
+import type { WsSendResult } from "../types.ts";
+type Shape<C> = InferChannel<C>;
+type MaybePromise<T> = T | Promise<T>;
+export type ClientEventName<C> = keyof Shape<C>["clientEvents"] & string;
+type ServerEvents<C> = Shape<C>["serverEvents"];
+/** Declared server events, or any name when the contract declares none (inline). */
+export type ServerEventName<C> = [keyof ServerEvents<C>] extends [never] ? string : keyof ServerEvents<C> & string;
+export type ServerEventPayload<C, E> = E extends keyof ServerEvents<C> ? ServerEvents<C>[E]["payloadIn"] : unknown;
+/** Why a channel was left; passed to `.leave()` handlers. */
+export type LeaveReason = "client" | "disconnect" | "kicked" | "server";
+type PresenceMetaIn<C> = [Shape<C>["presenceMeta"]] extends [never] ? never : Shape<C>["presenceMeta"] extends {
+    in: infer M;
+} ? M : never;
+/** Presence of the current channel, from a handler's point of view. */
+export interface ChannelPresence<M> {
+    /** Change the current socket's meta (it must be tracked). */
+    update(meta: M): boolean;
+    /** Cluster-wide `{ [key]: { ref, meta }[] }`. */
+    list(): Record<string, {
+        ref: string;
+        meta: M;
+    }[]>;
+    has(key: string): boolean;
+    keys(): string[];
+}
+/** The `channel` argument of every handler: actions scoped to this channel. */
+export interface ChannelContext<C> {
+    /** Only on channels whose contract declares `.presence()`. */
+    readonly presence: [PresenceMetaIn<C>] extends [never] ? undefined : ChannelPresence<PresenceMetaIn<C>>;
+    /** Concrete channel name, e.g. `rooms/42`. */
+    readonly name: string;
+    /** Everyone in the channel on every node, including the sender. */
+    broadcast<E extends ServerEventName<C>>(event: E, payload: ServerEventPayload<C, E>): number;
+    /** Everyone except the current socket. */
+    broadcastFrom<E extends ServerEventName<C>>(event: E, payload: ServerEventPayload<C, E>): number;
+    /** Only the current socket. */
+    push<E extends ServerEventName<C>>(event: E, payload: ServerEventPayload<C, E>): WsSendResult;
+    /** Server-initiated leave for the current socket. */
+    leave(reason?: string): void;
+}
+export interface ChannelHandlerArgs<Ctx, C> {
+    ctx: Ctx;
+    /** Channel-name params, validated by the contract's `.param()` schemas. */
+    path: Shape<C>["params"];
+    socket: WsConnection;
+    /** The upgrade request. */
+    req: Request;
+    container: DIContainer;
+    channel: ChannelContext<C>;
+}
+type ReplyOf<R> = [R] extends [undefined] ? unknown : R;
+export type JoinFn<Ctx, C> = (args: ChannelHandlerArgs<Ctx, C> & {
+    data: Shape<C>["join"]["payload"];
+}) => MaybePromise<ReplyOf<Shape<C>["join"]["replyIn"]>>;
+export type EventFn<Ctx, C, E extends ClientEventName<C>> = (args: ChannelHandlerArgs<Ctx, C> & {
+    data: Shape<C>["clientEvents"][E]["payload"];
+}) => MaybePromise<ReplyOf<Shape<C>["clientEvents"][E]["replyIn"]>>;
+export type AnyEventFn<Ctx, C> = (args: ChannelHandlerArgs<Ctx, C> & {
+    event: string;
+    data: unknown;
+}) => unknown;
+/**
+ * Decide how the joining socket appears in presence: return its key (e.g.
+ * the user id) and meta, or `null` to join without being tracked.
+ */
+export type PresenceFn<Ctx, C> = (args: ChannelHandlerArgs<Ctx, C> & {
+    data: Shape<C>["join"]["payload"];
+}) => MaybePromise<{
+    key: string;
+    meta: PresenceMetaIn<C>;
+} | null | undefined>;
+export type LeaveFn<Ctx, C> = (args: Omit<ChannelHandlerArgs<Ctx, C>, "channel"> & {
+    reason: LeaveReason;
+}) => unknown;
+/** Runtime data of a channel implementation. */
+export interface ChannelImplDefinition {
+    contract: AnyChannelContract;
+    pattern: RegExp;
+    paramNames: string[];
+    inline: boolean;
+    isPublic: boolean;
+    join?: (args: any) => unknown;
+    events: Map<string, (args: any) => unknown>;
+    any?: (args: any) => unknown;
+    leave?: (args: any) => unknown;
+    presence?: (args: any) => unknown;
+}
+type Status<Missing, Joined> = [Missing] extends [never] ? Joined extends true ? "complete" : "missing .join() or .public()" : `missing .on("${Missing & string}")`;
+export declare class ChannelImpl<Ctx, C extends AnyChannelContract, Handled extends string = never, Joined extends boolean = false> {
+    #private;
+    /** @internal Phantom: makes `Ctx` contravariant for `.channels()` checks. */
+    readonly _ctx?: (ctx: Ctx) => void;
+    /** @internal Phantom: `"complete"` once every event is handled and joins are authorized. */
+    readonly _status?: Status<Exclude<ClientEventName<C>, Handled>, Joined>;
+    readonly contract: C;
+    /** @internal Use {@link channel}. */
+    constructor(contract: C, def?: Partial<ChannelImplDefinition>);
+    get _definition(): ChannelImplDefinition;
+    /** Re-type the handler context, e.g. `channel(room).context<AppCtx>()`. */
+    context<NewCtx>(): ChannelImpl<NewCtx, C, Handled, Joined>;
+    /** Inline channels only: narrow/coerce a channel-name param. */
+    param<Name extends string & keyof Shape<C>["params"], S extends AnySchema>(name: Name, schema: S): ChannelImpl<Ctx, ParamResult<C, Name, S>, Handled, Joined>;
+    /**
+     * The join authorizer — throw (e.g. `ForbiddenError`) to refuse. The return
+     * value is the join reply. Inline channels may pass a payload schema first.
+     */
+    join(fn: JoinFn<Ctx, C>): ChannelImpl<Ctx, C, Handled, true>;
+    join<S extends AnySchema>(payload: S, fn: JoinFn<Ctx, JoinResult<C, S>>): ChannelImpl<Ctx, JoinResult<C, S>, Handled, true>;
+    /** Explicitly allow joining without authorization. */
+    public(): ChannelImpl<Ctx, C, Handled, true>;
+    /**
+     * Handle a client event. The return value is the reply (sent when the
+     * client passed a `ref`). Inline channels pass the payload schema second.
+     */
+    on<E extends ClientEventName<C>>(event: E, fn: EventFn<Ctx, C, E>): ChannelImpl<Ctx, C, Handled | E, Joined>;
+    on<E extends string, S extends AnySchema>(event: E, payload: S, fn: EventFn<Ctx, EventResult<C, E, S>, E & ClientEventName<EventResult<C, E, S>>>): ChannelImpl<Ctx, EventResult<C, E, S>, Handled | E, Joined>;
+    /**
+     * Catch-all for events without a handler — unvalidated, for proxies and
+     * bridges. Undeclared events are otherwise rejected with `unknown_event`.
+     */
+    onAny(fn: AnyEventFn<Ctx, C>): ChannelImpl<Ctx, C, Handled, Joined>;
+    /**
+     * Track joining sockets in presence (contract must declare `.presence()`).
+     * Untracked automatically on leave, kick and disconnect.
+     */
+    presence(fn: PresenceFn<Ctx, C>): ChannelImpl<Ctx, C, Handled, Joined>;
+    /** Runs when the socket leaves for any reason (client, disconnect, kick). */
+    leave(fn: LeaveFn<Ctx, C>): ChannelImpl<Ctx, C, Handled, Joined>;
+}
+type ParamResult<C, Name extends string, S extends AnySchema> = C extends ChannelContract<infer N, infer P, infer J, infer CE, infer SE, infer PM> ? ChannelContract<N, Omit<P, Name> & Record<Name, v.InferOutput<S>>, J, CE, SE, PM> : never;
+type JoinResult<C, S extends AnySchema> = C extends ChannelContract<infer N, infer P, infer _J, infer CE, infer SE, infer PM> ? ChannelContract<N, P, {
+    payload: S;
+    reply: undefined;
+}, CE, SE, PM> : never;
+type EventResult<C, E extends string, S extends AnySchema> = C extends ChannelContract<infer N, infer P, infer J, infer CE, infer SE, infer PM> ? ChannelContract<N, P, J, CE & Record<E, {
+    payload: S;
+    reply: undefined;
+}>, SE, PM> : never;
+export type AnyChannelImpl = ChannelImpl<any, AnyChannelContract, any, any>;
+export interface ChannelFactory<Ctx> {
+    /** Implement a shared `c.channel()` contract. */
+    <C extends AnyChannelContract>(contract: C): ChannelImpl<Ctx, C>;
+    /** Define a channel inline (router path syntax, e.g. `rooms/:roomId`). */
+    <N extends string>(name: N): ChannelImpl<Ctx, ChannelContract<N>>;
+}
+/**
+ * Create a channel implementation. Handler `ctx` is untyped by default; use
+ * `channel.withContext<AppCtx>()` (or `.context<AppCtx>()`) to type it, or
+ * the factory passed to `.channels((channel) => [...])`.
+ */
+export declare const channel: ChannelFactory<Record<string, unknown>> & {
+    withContext<Ctx>(): ChannelFactory<Ctx>;
+};
+export {};

package/dist/ws/channels/channel.js

@@ -0,0 +1,125 @@
+/**
+ * `channel()` — the server-side implementation of a channel, either from a
+ * shared `c.channel()` contract or defined inline.
+ *
+ * ```ts
+ * const roomImpl = channel(contract.room)
+ *   .join(async ({ ctx, path, data }) => ({ history: await load(path.roomId) }))
+ *   .on("message", async ({ data, channel }) => {
+ *     channel.broadcast("message", saved);
+ *     return { id: saved.id };
+ *   });
+ * ```
+ *
+ * Builders are immutable. The type parameters track which client events have
+ * handlers and whether an authorizer exists, so `.channels([...])` rejects
+ * incomplete implementations at compile time (and again at `build()`).
+ */
+import { ChannelContract, } from "../../contract/index.js";
+import { buildRouteRegex, } from "../../core/index.js";
+export class ChannelImpl {
+    contract;
+    #def;
+    /** @internal Use {@link channel}. */
+    constructor(contract, def) {
+        this.contract = contract;
+        const { regex, paramNames } = buildRouteRegex(`/${contract.name}`);
+        this.#def = {
+            contract,
+            pattern: regex,
+            paramNames,
+            inline: false,
+            isPublic: false,
+            events: new Map(),
+            ...def,
+        };
+    }
+    get _definition() {
+        return this.#def;
+    }
+    #next(patch, contract) {
+        return new ChannelImpl(contract ?? this.contract, {
+            ...this.#def,
+            events: new Map(this.#def.events),
+            ...patch,
+            ...(contract ? { contract } : {}),
+        });
+    }
+    /** Re-type the handler context, e.g. `channel(room).context<AppCtx>()`. */
+    context() {
+        return this;
+    }
+    /** Inline channels only: narrow/coerce a channel-name param. */
+    param(name, schema) {
+        this.#assertInline("param");
+        return this.#next({}, this.contract.param(name, schema));
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: overload implementation
+    join(a, b) {
+        if (b === undefined)
+            return this.#next({ join: a });
+        this.#assertInline("join(schema, fn)");
+        return this.#next({ join: b }, this.contract.join(a));
+    }
+    /** Explicitly allow joining without authorization. */
+    public() {
+        return this.#next({ isPublic: true });
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: overload implementation
+    on(event, a, b) {
+        if (this.#def.events.has(event)) {
+            throw new Error(`${this.contract.name}: .on("${event}") is already defined`);
+        }
+        if (b === undefined) {
+            if (!this.contract._definition.clientEvents.has(event)) {
+                throw new Error(`${this.contract.name}: "${event}" is not a client event of the contract`);
+            }
+            const events = new Map(this.#def.events);
+            events.set(event, a);
+            return this.#next({ events });
+        }
+        this.#assertInline(`on("${event}", schema, fn)`);
+        const events = new Map(this.#def.events);
+        events.set(event, b);
+        return this.#next({ events }, this.contract.clientEvent(event, a));
+    }
+    /**
+     * Catch-all for events without a handler — unvalidated, for proxies and
+     * bridges. Undeclared events are otherwise rejected with `unknown_event`.
+     */
+    onAny(fn) {
+        return this.#next({ any: fn });
+    }
+    /**
+     * Track joining sockets in presence (contract must declare `.presence()`).
+     * Untracked automatically on leave, kick and disconnect.
+     */
+    presence(fn) {
+        if (this.contract._definition.presence == null) {
+            throw new Error(`${this.contract.name}: .presence() requires presence in the channel contract`);
+        }
+        return this.#next({ presence: fn });
+    }
+    /** Runs when the socket leaves for any reason (client, disconnect, kick). */
+    leave(fn) {
+        return this.#next({ leave: fn });
+    }
+    #assertInline(what) {
+        if (!this.#def.inline) {
+            throw new Error(`${this.contract.name}: ${what} is only available on inline channels — the contract defines it`);
+        }
+    }
+}
+function createFactory() {
+    return ((source) => typeof source === "string"
+        ? new ChannelImpl(new ChannelContract(source), { inline: true })
+        : new ChannelImpl(source));
+}
+/**
+ * Create a channel implementation. Handler `ctx` is untyped by default; use
+ * `channel.withContext<AppCtx>()` (or `.context<AppCtx>()`) to type it, or
+ * the factory passed to `.channels((channel) => [...])`.
+ */
+export const channel = Object.assign(createFactory(), {
+    withContext: () => createFactory(),
+});

package/dist/ws/channels/handler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `channels()` — the opt-in protocol handler. A per-socket state machine
+ * that multiplexes authorized channels over one socket.
+ *
+ * Guarantees:
+ * - frames of one socket are processed **sequentially** (join → event →
+ *   leave order holds); different sockets run concurrently
+ * - nothing reaches a handler before the channel is joined and the payload
+ *   validated against the contract
+ * - a joining socket is a room member from the moment its join handler
+ *   starts: channel events sent meanwhile (broadcasts, `push`) are queued and
+ *   delivered right after the join reply, so a snapshot returned by the
+ *   handler plus the events that follow never leave a gap. Events sent while
+ *   the handler runs may also be in its snapshot; dedupe on the client (a
+ *   sequence number in the payload) if that matters
+ * - repeated protocol violations close the socket with `1008`
+ */
+import { WsHub } from "../hub.ts";
+import type { WsProtocolHandler } from "../route-builder.ts";
+import type { AnyChannelImpl } from "./channel.ts";
+export interface ChannelsOptions {
+    /** Default 32. Exceeding it fails the join with `429 too_many_channels`. */
+    maxChannelsPerSocket?: number;
+    /** Protocol violations tolerated before closing with `1008`. Default 10. */
+    maxViolations?: number;
+    /** Frames queued behind a slow handler before closing with `1013`. Default 64. */
+    maxPendingFrames?: number;
+    /**
+     * Channel events queued for a socket while its join handler runs. Default
+     * 1024. Exceeding it fails the join with `503 join_overflow`.
+     */
+    maxJoinBufferedFrames?: number;
+    /**
+     * Hub that backs channel membership — pass an instance or a DI token to
+     * reach channels from server code via `hub.channel(name)`. A private hub is
+     * used otherwise.
+     */
+    hub?: WsHub | (abstract new (...args: any[]) => WsHub);
+}
+/**
+ * Build the protocol handler. Prefer `.channels([...])` on a ws route,
+ * which also type-checks completeness; this form plugs into `.handleWith()`.
+ */
+export declare function channels(impls: readonly AnyChannelImpl[], options?: ChannelsOptions): WsProtocolHandler<Record<string, unknown>, Record<string, unknown>>;