@fishenv/http 0.0.2 → 0.0.3

package/dist/ws/typed.js

@@ -0,0 +1,104 @@
+/**
+ * A contract-typed view of a {@link WsConnection} for `c.ws().messages()`
+ * sockets: inbound JSON is validated against the client schema, outbound
+ * messages are typed (and validated in development).
+ */
+import * as v from "valibot";
+import { WsProtocolError, } from "./types.js";
+/** Thrown in development when the server sends something off-contract. */
+export class ContractViolationError extends Error {
+    issues;
+    constructor(what, issues) {
+        const first = issues[0];
+        const path = first?.path?.map((p) => String(p.key)).join(".") ?? "";
+        super(`${what} does not match the contract${path ? ` at "${path}"` : ""}: ${first?.message ?? "invalid"}`);
+        this.name = "ContractViolationError";
+        this.issues = issues;
+    }
+}
+/**
+ * Validate an inbound payload. Failure is the *client's* fault → protocol
+ * error (`1008`); the reason names the first issue only in development.
+ */
+export function parseInbound(schema, value, development) {
+    const result = v.safeParse(schema, value);
+    if (result.success)
+        return result.output;
+    const issue = result.issues[0];
+    throw new WsProtocolError(development && issue
+        ? `Invalid message: ${issue.message}`
+        : "Invalid message");
+}
+/**
+ * In development, validate an outbound payload so contract drift surfaces
+ * immediately. A no-op in production (types are the guarantee there).
+ */
+export function checkOutbound(schema, value, development, what) {
+    if (!development || schema == null)
+        return;
+    const result = v.safeParse(schema, value);
+    if (!result.success)
+        throw new ContractViolationError(what, result.issues);
+}
+export class TypedWsConnection {
+    /** The untyped connection — pass this to hubs. */
+    connection;
+    #client;
+    #server;
+    #development;
+    /** @internal Created by contract routes. */
+    constructor(connection, schemas, development) {
+        this.connection = connection;
+        this.#client = schemas.client;
+        this.#server = schemas.server;
+        this.#development = development;
+    }
+    get id() {
+        return this.connection.id;
+    }
+    get req() {
+        return this.connection.req;
+    }
+    get protocol() {
+        return this.connection.protocol;
+    }
+    get closed() {
+        return this.connection.closed;
+    }
+    get remoteAddress() {
+        return this.connection.remoteAddress;
+    }
+    get bufferedBytes() {
+        return this.connection.bufferedBytes;
+    }
+    get data() {
+        return this.connection.data;
+    }
+    set data(value) {
+        this.connection.data = value;
+    }
+    /**
+     * Validated inbound messages. Non-JSON or off-contract input closes the
+     * socket with `1008` before `fn` runs.
+     */
+    onMessage(fn) {
+        return this.connection.onMessage((message) => fn(parseInbound(this.#client, message.json(), this.#development()), message));
+    }
+    /** JSON-encode and send. Validated against the server schema in development. */
+    send(data) {
+        checkOutbound(this.#server, data, this.#development(), "Outbound message");
+        return this.connection.sendJson(data);
+    }
+    close(code, reason) {
+        this.connection.close(code, reason);
+    }
+    expireAt(when) {
+        this.connection.expireAt(when);
+    }
+    onClose(fn) {
+        this.connection.onClose(fn);
+    }
+    onDrain(fn) {
+        return this.connection.onDrain(fn);
+    }
+}

package/dist/ws/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared WebSocket types, close codes and error → close-code mapping.
+ * Deliberately free of class references from other ws modules so everything
+ * can import from here without a cycle.
+ */
+import { type UpgradedSocket } from "../core/index.ts";
+export declare const WsCloseCode: {
+    readonly Normal: 1000;
+    readonly GoingAway: 1001;
+    /** Rate limit, protocol violation, invalid payload. */
+    readonly PolicyViolation: 1008;
+    readonly MessageTooBig: 1009;
+    readonly InternalError: 1011;
+    /** Backpressure / overload. */
+    readonly TryAgainLater: 1013;
+    /** `socket.expireAt()` reached. */
+    readonly SessionExpired: 4001;
+};
+/** Close reasons are limited to 123 UTF-8 bytes by RFC 6455. */
+export declare const MAX_CLOSE_REASON_BYTES = 123;
+/** Throw from any handler to close the socket with a specific code. */
+export declare class WsCloseError extends Error {
+    readonly code: number;
+    constructor(code: number, reason?: string);
+}
+/** The client sent something that violates the expected protocol. */
+export declare class WsProtocolError extends WsCloseError {
+    constructor(reason?: string);
+}
+/**
+ * Map a thrown value to a close frame. `HttpError`s become `4000 + status`
+ * with their public message; anything unknown becomes `1011` with a generic
+ * reason (the real message is only exposed in development).
+ */
+export declare function closeFrameFor(err: unknown, development?: boolean): {
+    code: number;
+    reason: string;
+};
+/** Truncate to {@link MAX_CLOSE_REASON_BYTES} without splitting a code point. */
+export declare function truncateReason(reason: string): string;
+/** Return value is ignored; a returned promise is awaited only for error logging. */
+export type WsCleanupFn = () => unknown;
+/**
+ * - `sent` — written (or queued below the backpressure limit)
+ * - `backpressure` — queued, but the socket is over its buffer limit
+ * - `dropped` — not sent (Bun dropped it)
+ * - `closed` — the socket is gone
+ */
+export type WsSendResult = "sent" | "backpressure" | "dropped" | "closed";
+/** Whatever Bun's `ServerWebSocket.send()` accepts (string, buffers, Blob). */
+export type WsSendable = Parameters<UpgradedSocket["send"]>[0];
+export interface WsRateLimit {
+    /** Messages allowed per window (also the burst size). */
+    messages: number;
+    /** Window length in ms. */
+    perMs: number;
+    /** Default `"close"` → `1008`. `"drop"` silently discards excess messages. */
+    onExceed?: "close" | "drop";
+}
+export interface WsConnectionOptions {
+    /** Per-route inbound limit in bytes; must be ≤ the server-wide limit. */
+    maxMessageSize?: number;
+    rateLimit?: WsRateLimit;
+    /** Messages buffered while an async handler sets up. Default 256. */
+    maxQueuedMessages?: number;
+    /** Include error messages in close reasons. Set from `serve({ development })`. */
+    development?: boolean;
+}
+export declare const DEFAULT_MAX_QUEUED_MESSAGES = 256;

package/dist/ws/types.js

@@ -0,0 +1,70 @@
+/**
+ * Shared WebSocket types, close codes and error → close-code mapping.
+ * Deliberately free of class references from other ws modules so everything
+ * can import from here without a cycle.
+ */
+import { HttpError } from "../core/index.js";
+// ── Close codes ──────────────────────────────────────────────────────────
+export const WsCloseCode = {
+    Normal: 1000,
+    GoingAway: 1001,
+    /** Rate limit, protocol violation, invalid payload. */
+    PolicyViolation: 1008,
+    MessageTooBig: 1009,
+    InternalError: 1011,
+    /** Backpressure / overload. */
+    TryAgainLater: 1013,
+    /** `socket.expireAt()` reached. */
+    SessionExpired: 4001,
+};
+/** Close reasons are limited to 123 UTF-8 bytes by RFC 6455. */
+export const MAX_CLOSE_REASON_BYTES = 123;
+/** Throw from any handler to close the socket with a specific code. */
+export class WsCloseError extends Error {
+    code;
+    constructor(code, reason = "") {
+        super(reason);
+        this.name = "WsCloseError";
+        this.code = code;
+    }
+}
+/** The client sent something that violates the expected protocol. */
+export class WsProtocolError extends WsCloseError {
+    constructor(reason = "Protocol violation") {
+        super(WsCloseCode.PolicyViolation, reason);
+        this.name = "WsProtocolError";
+    }
+}
+/**
+ * Map a thrown value to a close frame. `HttpError`s become `4000 + status`
+ * with their public message; anything unknown becomes `1011` with a generic
+ * reason (the real message is only exposed in development).
+ */
+export function closeFrameFor(err, development = false) {
+    if (err instanceof WsCloseError) {
+        return { code: err.code, reason: truncateReason(err.message) };
+    }
+    if (err instanceof HttpError && err.status >= 100 && err.status <= 999) {
+        return { code: 4000 + err.status, reason: truncateReason(err.message) };
+    }
+    const reason = development && err instanceof Error ? err.message : "Internal Error";
+    return { code: WsCloseCode.InternalError, reason: truncateReason(reason) };
+}
+/** Truncate to {@link MAX_CLOSE_REASON_BYTES} without splitting a code point. */
+export function truncateReason(reason) {
+    const encoder = new TextEncoder();
+    if (encoder.encode(reason).byteLength <= MAX_CLOSE_REASON_BYTES) {
+        return reason;
+    }
+    let out = "";
+    let bytes = 0;
+    for (const char of reason) {
+        const size = encoder.encode(char).byteLength;
+        if (bytes + size > MAX_CLOSE_REASON_BYTES)
+            break;
+        out += char;
+        bytes += size;
+    }
+    return out;
+}
+export const DEFAULT_MAX_QUEUED_MESSAGES = 256;

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@fishenv/http",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Type-safe HTTP router for Bun with valibot validation, contracts and Server-Sent Events.",
   "license": "AGPL-3.0-only",
   "type": "module",
   "sideEffects": false,
+  "repository": {
+    "url": "https://github.com/freshfish70/fishenv.http"
+  },
   "files": [
     "dist"
   ],
@@ -17,13 +20,22 @@
       "types": "./dist/sse/index.d.ts",
       "default": "./dist/sse/index.js"
     },
+    "./ws": {
+      "types": "./dist/ws/index.d.ts",
+      "default": "./dist/ws/index.js"
+    },
     "./contract": {
       "types": "./dist/contract/index.d.ts",
       "default": "./dist/contract/index.js"
+    },
+    "./static": {
+      "types": "./dist/static/index.d.ts",
+      "default": "./dist/static/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "scripts": {
     "test": "bun test",