@fishenv/http 0.0.0-stage → 0.0.3

package/dist/static/router.js

@@ -0,0 +1,217 @@
+/** `staticFiles()`, `spa()` and the `withStatic()` mixin. */
+import path from "node:path";
+import { BadRequestError, NotFoundError, r, } from "../core/index.js";
+import { acceptsHtml } from "./negotiate.js";
+import { compileStaticOptions, isServable, } from "./options.js";
+import { BAD_ENCODING, locate, parseRequestPath } from "./resolve.js";
+import { serveWithVariants, statFile, } from "./response.js";
+import { applyRules } from "./rules.js";
+/**
+ * Serve a directory as a mountable router:
+ *
+ * ```ts
+ * app.add("/assets", staticFiles({ root: "./public" }));
+ * ```
+ *
+ * Paths are decoded and validated per segment, kept inside the (real) root,
+ * and dotfiles are hidden by default. Every rejection is a plain 404
+ * (`NotFoundError`), except undecodable `%` sequences (`BadRequestError`).
+ * Throws at creation on any misconfiguration.
+ */
+export function staticFiles(opts) {
+    const cfg = compileStaticOptions(opts);
+    const cache = cfg.cache ? new LookupCache(cfg.cache) : null;
+    const router = r();
+    router.get("/:path*").handle(async ({ req, path: params }) => {
+        const raw = params.path;
+        const parsed = parseRequestPath(raw, cfg.windows);
+        if (parsed === BAD_ENCODING)
+            throw new BadRequestError();
+        if (parsed === null || !isServable(cfg, parsed.segments)) {
+            throw new NotFoundError();
+        }
+        const key = parsed.segments.join("/") + (parsed.trailingSlash ? "/" : "");
+        const found = await resolveFresh(cfg, cache, key, parsed);
+        if (found.kind === "file")
+            return serveLookup(req, cfg, found, found.stat);
+        if (found.kind === "redirect")
+            return redirectToDirectory(req);
+        if (cfg.fallback && isFallbackEligible(req, parsed.segments)) {
+            const shell = await withStat(await lookup(cfg, cfg.fallback, false));
+            if (shell?.kind === "file") {
+                return serveLookup(req, cfg, shell, shell.stat, { forceNoCache: true });
+            }
+        }
+        throw new NotFoundError();
+    });
+    return Object.defineProperty(router, "invalidate", {
+        value: (relPath) => cache?.invalidate(relPath),
+        enumerable: false,
+        configurable: true,
+    });
+}
+/**
+ * Single-page app: `staticFiles()` with `index.html` as both the directory
+ * index and the fallback for unknown, extension-less HTML requests.
+ *
+ * ```ts
+ * app.add(api).add(spa({ root: "./dist", exclude: ["api/**"] }));
+ * ```
+ */
+export function spa(opts) {
+    return staticFiles({
+        index: ["index.html"],
+        fallback: "index.html",
+        ...opts,
+    });
+}
+/** Mixin sugar for `router.add(prefix, staticFiles(opts))`. */
+// biome-ignore lint/suspicious/noExplicitAny: accepts routers of any context
+export function withStatic(router, prefix, opts) {
+    router.add(prefix, staticFiles(opts));
+    return router;
+}
+/** Attach a fresh stat to a file lookup; `null` if it is no longer a file. */
+async function withStat(found) {
+    if (found.kind !== "file")
+        return found;
+    const stat = await statFile(found.abs);
+    return stat ? { ...found, stat } : null;
+}
+/**
+ * Look up through the cache, but never build a response from a cached file
+ * without a fresh stat: a vanished or replaced entry is resolved again.
+ */
+async function resolveFresh(cfg, cache, key, parsed) {
+    const cached = cache?.get(key);
+    if (cached) {
+        const fresh = await withStat(cached);
+        if (fresh)
+            return fresh;
+        cache?.delete(key);
+    }
+    const found = await lookup(cfg, parsed.segments, parsed.trailingSlash);
+    const fresh = await withStat(found);
+    if (fresh) {
+        cache?.set(key, found);
+        return fresh;
+    }
+    return { kind: "missing" };
+}
+function serveLookup(req, cfg, found, stat, extras = {}) {
+    const rules = applyRules(cfg.rules, found.rel);
+    return serveWithVariants(req, cfg, { path: found.rel, abs: found.abs, stat, variants: found.variants }, { cacheControl: rules.cacheControl, headers: rules.headers, ...extras });
+}
+/** Steps 6–10: file, directory index, redirect, extension fallback. */
+async function lookup(cfg, segments, trailingSlash) {
+    const target = await locate(cfg.root, segments, cfg.symlinks, cfg.allowCanonical);
+    if (target?.stat.isDirectory()) {
+        if (cfg.index.length === 0)
+            return { kind: "missing" };
+        if (!trailingSlash)
+            return { kind: "redirect" };
+        for (const name of cfg.index) {
+            const found = await findFile(cfg, [...segments, name]);
+            if (found)
+                return found;
+        }
+        return { kind: "missing" };
+    }
+    if (target && !trailingSlash)
+        return withVariants(cfg, segments, target.abs);
+    if (!trailingSlash && segments.length > 0) {
+        const last = segments[segments.length - 1];
+        for (const ext of cfg.extensions) {
+            const found = await findFile(cfg, [
+                ...segments.slice(0, -1),
+                `${last}.${ext}`,
+            ]);
+            if (found)
+                return found;
+        }
+    }
+    return { kind: "missing" };
+}
+/** A derived candidate (index, extension) is checked like a request path. */
+async function findFile(cfg, segments) {
+    if (!isServable(cfg, segments))
+        return null;
+    const located = await locate(cfg.root, segments, cfg.symlinks, cfg.allowCanonical);
+    if (!located?.stat.isFile())
+        return null;
+    return withVariants(cfg, segments, located.abs);
+}
+async function withVariants(cfg, segments, abs) {
+    const variants = {};
+    const last = segments[segments.length - 1];
+    for (const enc of cfg.precompressed) {
+        const suffix = enc === "br" ? ".br" : ".gz";
+        const sibling = await locate(cfg.root, [...segments.slice(0, -1), last + suffix], cfg.symlinks, cfg.allowCanonical);
+        if (sibling?.stat.isFile())
+            variants[enc] = sibling.abs;
+    }
+    return { kind: "file", rel: segments.join("/"), abs, variants };
+}
+/**
+ * Redirect `/dir` to `/dir/` with a relative `Location` built from the last
+ * URL segment. `./` keeps a segment like `https:evil.com` from reading as an
+ * absolute URL; nothing here can produce `//host`.
+ */
+function redirectToDirectory(req) {
+    const url = new URL(req.url);
+    const last = url.pathname.slice(url.pathname.lastIndexOf("/") + 1);
+    return new Response(null, {
+        status: 301,
+        headers: { Location: `./${last}/${url.search}` },
+    });
+}
+function isFallbackEligible(req, segments) {
+    const last = segments[segments.length - 1] ?? "";
+    if (path.extname(last) !== "")
+        return false;
+    return acceptsHtml(req.headers.get("accept"));
+}
+/** Bounded LRU of lookups. Misses expire sooner than hits. Internal; exported for tests. */
+export class LookupCache {
+    #entries = new Map();
+    #ttlMs;
+    #maxEntries;
+    constructor(opts) {
+        this.#ttlMs = opts.ttlMs;
+        this.#maxEntries = opts.maxEntries;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get(key) {
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return undefined;
+        this.#entries.delete(key);
+        if (entry.expires <= Date.now())
+            return undefined;
+        this.#entries.set(key, entry); // most recently used goes last
+        return entry.lookup;
+    }
+    set(key, lookup) {
+        const ttl = lookup.kind === "missing" ? Math.min(this.#ttlMs, 1_000) : this.#ttlMs;
+        this.#entries.delete(key);
+        this.#entries.set(key, { lookup, expires: Date.now() + ttl });
+        while (this.#entries.size > this.#maxEntries) {
+            const oldest = this.#entries.keys().next().value;
+            this.#entries.delete(oldest);
+        }
+    }
+    delete(key) {
+        this.#entries.delete(key);
+    }
+    invalidate(relPath) {
+        if (relPath === undefined) {
+            this.#entries.clear();
+            return;
+        }
+        const key = relPath.replace(/^\/+/, "").replace(/\/+$/, "");
+        this.#entries.delete(key);
+        this.#entries.delete(`${key}/`);
+    }
+}

package/dist/static/rules.d.ts

@@ -0,0 +1,21 @@
+import type { StaticRule } from "./types.ts";
+export interface CompiledRule {
+    regex: RegExp;
+    rule: StaticRule;
+}
+export interface RuleResult {
+    deny: boolean;
+    cacheControl?: string;
+    headers: Record<string, string>;
+}
+/**
+ * Compile a route-style glob for matching relative file paths. Reuses the
+ * route compiler so there is one glob dialect and no user-supplied RegExp.
+ * Matching is case-insensitive so deny rules hold on case-insensitive disks.
+ */
+export declare function compileGlob(pattern: string): RegExp;
+/** True when `rel` (no leading slash) matches the compiled glob. */
+export declare function matchesGlob(regex: RegExp, rel: string): boolean;
+export declare function compileRules(rules: StaticRule[]): CompiledRule[];
+/** Fold every matching rule in order; later rules win per field. */
+export declare function applyRules(rules: CompiledRule[], rel: string): RuleResult;

package/dist/static/rules.js

@@ -0,0 +1,49 @@
+import { buildRouteRegex } from "../core/index.js";
+/**
+ * Compile a route-style glob for matching relative file paths. Reuses the
+ * route compiler so there is one glob dialect and no user-supplied RegExp.
+ * Matching is case-insensitive so deny rules hold on case-insensitive disks.
+ */
+export function compileGlob(pattern) {
+    if (typeof pattern !== "string" || pattern.trim() === "") {
+        throw new Error("static: glob patterns must be non-empty strings");
+    }
+    const trimmed = pattern.replace(/^\/+/, "");
+    if (trimmed.split("/").some((seg) => seg.startsWith(":"))) {
+        throw new Error(`static: glob "${pattern}" has a ":param" segment; use * or ** instead`);
+    }
+    const { regex } = buildRouteRegex(`/${trimmed}`);
+    return new RegExp(regex.source, "i");
+}
+/** True when `rel` (no leading slash) matches the compiled glob. */
+export function matchesGlob(regex, rel) {
+    return regex.test(`/${rel}`);
+}
+export function compileRules(rules) {
+    return rules.map((rule) => {
+        if (typeof rule !== "object" || rule === null) {
+            throw new Error("static: each rule must be an object");
+        }
+        for (const key of Object.keys(rule)) {
+            if (!["match", "cacheControl", "headers", "deny"].includes(key)) {
+                throw new Error(`static: unknown rule option "${key}"`);
+            }
+        }
+        return { regex: compileGlob(rule.match), rule };
+    });
+}
+/** Fold every matching rule in order; later rules win per field. */
+export function applyRules(rules, rel) {
+    const result = { deny: false, headers: {} };
+    for (const { regex, rule } of rules) {
+        if (!matchesGlob(regex, rel))
+            continue;
+        if (rule.deny !== undefined)
+            result.deny = rule.deny;
+        if (rule.cacheControl !== undefined)
+            result.cacheControl = rule.cacheControl;
+        if (rule.headers)
+            Object.assign(result.headers, rule.headers);
+    }
+    return result;
+}

package/dist/static/types.d.ts

@@ -0,0 +1,76 @@
+/** Pre-compressed sibling encodings: `file.br` and `file.gz`. */
+export type StaticEncoding = "br" | "gzip";
+/** Per-path overrides, matched against the decoded relative path. */
+export interface StaticRule {
+    /** Route-style glob (`*`, `**`, `{a,b}`), matched case-insensitively. */
+    match: string;
+    cacheControl?: string;
+    headers?: Record<string, string>;
+    /** Respond 404 as if the file did not exist. */
+    deny?: boolean;
+}
+/** What `setHeaders` learns about the file being served. */
+export interface StaticFileInfo {
+    /** Relative `/`-joined path inside the root (absolute for `serveFile`). */
+    path: string;
+    size: number;
+    mtime: Date;
+    /** Set when a pre-compressed sibling is served. */
+    encoding?: StaticEncoding;
+}
+export type SetHeadersFn = (info: StaticFileInfo, headers: Headers) => void;
+/** Response options shared by `staticFiles()` and `serveFile()`. */
+export interface StaticResponseOptions {
+    /** Sibling encodings to look for, in server preference order. Default `[]`. */
+    precompressed?: StaticEncoding[];
+    /** Default `true`. */
+    etag?: boolean;
+    /** Default `true`. */
+    lastModified?: boolean;
+    /** Default `"no-cache"`. */
+    cacheControl?: string;
+    /** Added to every file response. */
+    headers?: Record<string, string>;
+    /**
+     * Serve files as untrusted (user uploads): CSP sandbox on every response and
+     * `Content-Disposition: attachment` for anything but passive media types.
+     */
+    untrusted?: boolean;
+    /** Runs last; may override any header. */
+    setHeaders?: SetHeadersFn;
+}
+export interface StaticCacheOptions {
+    /** Default 5000. */
+    ttlMs?: number;
+    /** Default 10000. */
+    maxEntries?: number;
+}
+export interface StaticOptions extends StaticResponseOptions {
+    /** Directory to serve. Resolved through symlinks once, at creation. */
+    root: string;
+    /** File names tried for directory requests. Default `["index.html"]`. */
+    index?: string[];
+    /** Extensions tried for extension-less misses, e.g. `["html"]`. Default `[]`. */
+    extensions?: string[];
+    /** `"hide"` (default) answers 404 for any path segment starting with `.`. */
+    dotfiles?: "hide" | "allow";
+    /** Dot-segments still served under `dotfiles: "hide"`, e.g. `[".well-known"]`. */
+    allowDotfiles?: string[];
+    /**
+     * `"within-root"` (default) follows links whose target stays inside the
+     * root; `"deny"` refuses any link; `"follow"` follows links anywhere.
+     * Defaults to `"deny"` when `untrusted` is set.
+     */
+    symlinks?: "within-root" | "deny" | "follow";
+    /** Ordered per-path overrides; later rules win per field. */
+    rules?: StaticRule[];
+    /** Globs this router never serves (and never falls back for). */
+    exclude?: string[];
+    /**
+     * File served for unknown extension-less paths when the client accepts
+     * HTML (SPA routing), e.g. `"index.html"`. Always sent `no-cache`.
+     */
+    fallback?: string;
+    /** Cache path resolution (not contents). `true` uses the defaults. */
+    cache?: boolean | StaticCacheOptions;
+}

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(),
+});