@dunx/http 0.1.0

package/dist/ws/relay.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What `PubSub` needs from something that carries a message to the other nodes:
+ * publish, and subscribe. Nothing else, so anything that already talks to a
+ * broker satisfies it — `@dunx/infra/redis`'s `RedisConnection` does, structurally
+ * and with no adapter, and so does a bare `Bun.RedisClient` pair.
+ *
+ * The return types are `unknown` rather than `Promise<void>` deliberately: Bun's
+ * `publish` resolves the subscriber count, `@dunx/infra`'s resolves nothing, and a
+ * synchronous in-memory bus resolves at all. A returned promise is awaited by
+ * `subscribe` and watched for rejection by `publish`; anything else is taken as
+ * having succeeded.
+ */
+export interface PubSubRelay {
+    /** Hand `message` to every node subscribed to `channel`, this one included. */
+    publish(channel: string, message: string): unknown;
+    /**
+     * Deliver every message published to `channel` to `listener`. Called once, with
+     * one channel — pattern subscription is not used, because Bun's `psubscribe`
+     * does not work (see docs/bun-apis.md).
+     */
+    subscribe(channel: string, listener: (message: string) => void): unknown;
+    /**
+     * Release whatever this relay opened. Implement it only for connections the
+     * relay itself owns: a relay that is the application's own shared
+     * `RedisConnection` must leave closing to the container, and simply omitting
+     * this method is how it says so.
+     */
+    close?(): unknown;
+}
+/** Which relay call failed, so one message can say what degraded. */
+export type RelayPhase = 'publish' | 'subscribe' | 'close';
+export interface RelayOptions {
+    /**
+     * The one broker channel every topic's frames travel on.
+     *
+     * One channel rather than one per topic, because a node cannot know which
+     * topics its sockets joined — `socket.subscribe()` goes straight into Bun — and
+     * `psubscribe` is unusable. The cost is that every node reads every relayed
+     * frame and drops the ones for topics it has no local subscriber on, which is a
+     * `server.publish` returning `0`. Two apps sharing a Redis need two channels.
+     *
+     * @default 'dunx:ws'
+     */
+    readonly channel?: string;
+    /**
+     * Where a relay failure goes. Called once when the relay starts failing and not
+     * again until it works, so an unreachable broker cannot flood the log.
+     *
+     * @default console.warn
+     */
+    readonly onError?: (error: unknown, phase: RelayPhase) => void;
+    /**
+     * What to do when the **boot** subscribe fails. Publishing recovers on its own —
+     * every publish retries the broker — but a failed subscribe used to be retried
+     * by nothing, so the node stayed permanently deaf to other nodes while still
+     * looking healthy.
+     *
+     * Bounded rather than infinite, and the timer is unref'd, so a broker that never
+     * comes back cannot hold the process open or spin forever.
+     */
+    readonly resubscribe?: {
+        /** Retries after the first failure. `0` disables them. @default 5 */
+        readonly attempts?: number;
+        /** First delay; doubles each attempt, capped at 30s. @default 500 */
+        readonly delayMs?: number;
+    };
+}
+export declare const DEFAULT_RELAY_CHANNEL = "dunx:ws";
+export declare const defaultRelayError: (error: unknown, phase: RelayPhase) => void;
+/**
+ * One relayed publish: which process published it, which topic it belongs to, and
+ * the frame itself. `origin` is the whole duplicate-delivery defence — the broker
+ * echoes a publish back to the publisher, and fanning that out locally a second
+ * time would give every client on the originating node the message twice.
+ */
+export interface RelayFrame {
+    readonly origin: string;
+    readonly topic: string;
+    readonly data: string | Uint8Array<ArrayBufferLike>;
+}
+export declare const encodeRelay: (origin: string, topic: string, data: string | Bun.BufferSource) => string;
+/** `undefined` for anything that is not one of our frames, which is then ignored. */
+export declare const decodeRelay: (message: string) => RelayFrame | undefined;

package/dist/ws/runtime.d.ts

@@ -0,0 +1,25 @@
+import type { DiscoveredGateway, Invoke } from './discover.js';
+/**
+ * One gateway reduced to direct references, built once at boot. Dispatch reads
+ * these fields and nothing else — no lookup, no metadata, no DI per message.
+ */
+export interface GatewayRuntime {
+    readonly name: string;
+    readonly path: string;
+    readonly upgrade: Invoke | undefined;
+    readonly open: Invoke | undefined;
+    readonly close: Invoke | undefined;
+    readonly drain: Invoke | undefined;
+    readonly ping: Invoke | undefined;
+    readonly pong: Invoke | undefined;
+    /** The raw `@OnMessage()` catch-all: every frame no named event claimed. */
+    readonly raw: Invoke | undefined;
+    readonly events: ReadonlyMap<string, Invoke>;
+}
+export declare const buildRuntime: (gateway: DiscoveredGateway) => GatewayRuntime;
+/**
+ * One route per gateway path, so two gateways on one path would mean one of them
+ * could never receive a connection. That is a boot error naming both.
+ */
+export declare const buildGateways: (discovered: readonly DiscoveredGateway[]) => ReadonlyMap<string, GatewayRuntime>;
+export declare const someHandler: (gateways: Iterable<GatewayRuntime>, pick: (gateway: GatewayRuntime) => Invoke | undefined) => boolean;

package/dist/ws/socket.d.ts

@@ -0,0 +1,28 @@
+import type { ServerWebSocket, WebSocketHandler } from 'bun';
+/**
+ * What every socket carries. `path` is the gateway it upgraded on; `context` is
+ * whatever that gateway's `@OnUpgrade` returned, so per-connection state is
+ * declared where the connection is accepted.
+ */
+export interface SocketData<T = unknown> {
+    readonly path: string;
+    readonly context: T;
+}
+/**
+ * Bun's native socket, unwrapped. `send`, `subscribe`, `unsubscribe`,
+ * `isSubscribed`, `publish`, `cork` and `close` are its own methods — nothing here
+ * reimplements them.
+ */
+export type Socket<T = unknown> = ServerWebSocket<SocketData<T>>;
+/** Named for the socket, so it reads apart from the HTTP `ErrorMapper`. */
+export type SocketErrorHandler = (error: unknown, socket: Socket) => void;
+/**
+ * The websocket half of `HttpOptions`. Everything but `onError` is `Pick`ed from
+ * Bun's own handler type rather than restated, so the names and the accepted values
+ * cannot drift from the runtime. `idleTimeout` is in seconds and Bun rejects
+ * anything above 960 at `Bun.serve` time.
+ */
+export type SocketOptions = Readonly<Pick<WebSocketHandler<SocketData>, 'backpressureLimit' | 'closeOnBackpressureLimit' | 'idleTimeout' | 'maxPayloadLength' | 'perMessageDeflate' | 'publishToSelf' | 'sendPings'>> & {
+    /** Where a throwing or rejecting handler goes. @default console.error */
+    readonly onError?: SocketErrorHandler;
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@dunx/http",
+  "version": "0.1.0",
+  "description": "Bun.serve adapter for the dunx framework: controllers, middleware and WebSocket gateways",
+  "keywords": [
+    "bun",
+    "controller",
+    "dunx",
+    "http",
+    "pubsub",
+    "realtime",
+    "router",
+    "websocket"
+  ],
+  "homepage": "https://github.com/petarzarkov/dunx/tree/main/packages/http#readme",
+  "license": "MIT",
+  "author": {
+    "name": "Petar Zarkov",
+    "email": "pzarko1@gmail.com",
+    "url": "https://github.com/petarzarkov"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petarzarkov/dunx.git",
+    "directory": "packages/http"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts",
+    "test": "bun test --bail",
+    "test:cov": "bun test --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@dunx/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@dunx/core": "0.1.0",
+    "@types/bun": ">=1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/bun": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  }
+}