@jeffusion/bungee-core 5.16.0 → 5.17.0

package/dist/public-listener/websocket.d.ts

@@ -0,0 +1,4 @@
+import type { ForwardPublicRequestOptions } from './forwarding';
+import { type WebSocketBridge } from '../websocket';
+/** Pin the admitted worker for this connection; publication never migrates an open socket. */
+export declare function forwardPublicWebSocket(request: Request, server: Bun.Server<any>, bridge: WebSocketBridge, options: ForwardPublicRequestOptions, peer?: string): Promise<Response | undefined>;

package/dist/scoped-plugin-registry.d.ts

@@ -231,6 +231,8 @@ export declare class ScopedPluginRegistry {
     private combinedHooksCache;
     /** Phase-aware Hooks 缓存：`phase-aware:${routeId}#${upstreamId}#${serviceName}` → PhaseAwareHooks */
     private phaseAwareCache;
+    private websocketHandshakeHooks;
+    private websocketObservationHooks;
     private attemptObservationHooks;
     /** 已加载的插件类：pluginName → PluginClass */
     private pluginClasses;
@@ -390,6 +392,16 @@ export declare class ScopedPluginRegistry {
      * ```
      */
     getPrecompiledHooks(routeId: string, upstreamId?: string, serviceName?: string): PhaseAwareHooks;
+    /** Retain every instance actually executed by handshake phases; observer precedence is different. */
+    getWebSocketHandshakeOwners(routeId: string, upstreamId: string, serviceName?: string): Array<{
+        pluginName: string;
+        scopeKey: string;
+    }>;
+    getWebSocketOwners(routeId: string, upstreamId?: string, serviceName?: string): Array<{
+        pluginName: string;
+        scopeKey: string;
+        hooks: PluginHooks['onWebSocketObservation'];
+    }>;
     getAttemptObservationOwners(routeId: string, upstreamId?: string, serviceName?: string, context?: PluginBodyRequirementContext): AttemptObservationOwner[];
     /**
      * 获取路由级预编译 Hooks（不含上游插件）

package/dist/websocket/headers.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, OutgoingHttpHeaders } from 'node:http';
+/** Ordinary HTTP and other upgrade protocols remain owned by the HTTP router. */
+export declare function isWebSocketUpgradeRequest(request: Request): boolean;
+export declare function validateWebSocketRequest(request: Request): Response | undefined;
+export declare function offeredProtocols(request: Request): string[];
+/** ws generates a fresh key, Host, Connection, Upgrade and version for this hop. */
+export declare function upstreamHeaders(headers: Headers, protocols: readonly string[]): OutgoingHttpHeaders;
+/** rawHeaders retains repeated Set-Cookie; framing and internal headers do not cross hops. */
+export declare function downstreamHeaders(response: IncomingMessage, rejection?: boolean): Headers;

package/dist/websocket/index.d.ts

@@ -0,0 +1,3 @@
+export { createWebSocketMessageView } from './message';
+export { isWebSocketUpgradeRequest, validateWebSocketRequest } from './headers';
+export { createWebSocketBridge, WebSocketBridge, WEBSOCKET_BRIDGE_DEFAULTS, type WebSocketBridgeOptions, type WebSocketBridgeData, type WebSocketUpgradeOptions, type WebSocketBridgeStats, } from './transport';

package/dist/websocket/message.d.ts

@@ -0,0 +1,3 @@
+import type { WebSocketMessageView } from '../gateway/websocket-contracts';
+/** One immutable view per complete message; parsing is shared and demand driven. */
+export declare function createWebSocketMessageView(message: string | Uint8Array): WebSocketMessageView;

package/dist/websocket/observation.d.ts

@@ -0,0 +1,17 @@
+import type { PluginHooks } from '../hooks';
+import type { WebSocketObservationEvent, WebSocketSessionContext } from '../gateway/websocket-contracts';
+type Detail = WebSocketObservationEvent extends infer E ? E extends WebSocketObservationEvent ? Omit<E, keyof WebSocketSessionContext | 'isActive'> : never : never;
+type Owner = {
+    pluginName: string;
+    hooks: PluginHooks['onWebSocketObservation'];
+};
+/** Independent, ordered queues: an optional observer cannot block forwarding or another owner. */
+export declare class WebSocketObservers {
+    private branches;
+    constructor(context: WebSocketSessionContext, owners: readonly Owner[]);
+    emit(detail: Detail): void;
+    close(detail: Extract<Detail, {
+        phase: 'close';
+    }>): Promise<void>;
+}
+export {};

package/dist/websocket/transport.d.ts

@@ -0,0 +1,77 @@
+import type { WebSocketMessageView, WebSocketSessionMetrics } from '../gateway/websocket-contracts';
+export declare const WEBSOCKET_BRIDGE_DEFAULTS: Readonly<{
+    maxMessageBytes: number;
+    maxConnections: 64;
+    maxHandshakes: 16;
+    handshakeTimeoutMs: 10000;
+    maxBufferedBytes: number;
+    maxTotalBufferedBytes: number;
+    maxEarlyMessages: 16;
+    maxFragments: 1024;
+    maxRejectedBodyBytes: number;
+    closeTimeoutMs: 1000;
+}>;
+type Limits = {
+    [K in keyof typeof WEBSOCKET_BRIDGE_DEFAULTS]: number;
+};
+export type WebSocketBridgeOptions = Partial<Limits>;
+/** Opaque token prevents callbacks from taking ownership of another bridge's session. */
+export interface WebSocketBridgeData {
+    readonly connection: object;
+}
+export interface WebSocketUpgradeOptions {
+    readonly url: URL | string;
+    readonly headers: Headers;
+    /** Handshake cancellation only. Removed before committing the downstream upgrade. */
+    readonly signal?: AbortSignal;
+    readonly onOpen?: () => unknown;
+    readonly onMessage?: (direction: 'client' | 'upstream', message: WebSocketMessageView) => unknown;
+    /** Runs once after both native close callbacks, for committed sessions only. */
+    readonly onClose?: (code: number, reason: string, metrics: WebSocketSessionMetrics) => unknown;
+}
+export interface WebSocketBridgeStats {
+    readonly accepting: boolean;
+    readonly connections: number;
+    readonly handshakes: number;
+    readonly bufferedBytes: number;
+    readonly processBufferedBytes: number;
+    readonly downstreamBackpressureEvents: number;
+    readonly downstreamDrainEvents: number;
+}
+export declare class WebSocketBridge {
+    #private;
+    readonly limits: Readonly<Limits>;
+    readonly websocket: Bun.WebSocketHandler<WebSocketBridgeData>;
+    constructor(options?: WebSocketBridgeOptions);
+    get stats(): WebSocketBridgeStats;
+    /** Call only for upgrade candidates; ordinary HTTP returns undefined without taking ownership. */
+    upgrade(request: Request, server: Bun.Server<any>, options: WebSocketUpgradeOptions): Promise<Response | undefined>;
+    stopAccepting(): void;
+    /** 1012 close, bounded grace, then terminate, and require actual native close confirmation. */
+    stop(): Promise<void>;
+    forceStop(): Promise<void>;
+    get accepting(): boolean;
+    /** @internal */ endHandshake(): void;
+    /** @internal */ backpressure(): void;
+    /** @internal */ confirmGone(session: BridgeSession): void;
+}
+type Message = string | Buffer;
+declare class BridgeSession {
+    #private;
+    readonly token: Readonly<{}>;
+    readonly response: Promise<Response | undefined>;
+    constructor(bridge: WebSocketBridge, request: Request, server: Bun.Server<any>, options: WebSocketUpgradeOptions, url: URL);
+    get bufferedBytes(): number;
+    get processLimit(): number;
+    start(): void;
+    cancelHandshake(status: number, reason: string): void;
+    downstreamOpen(socket: Bun.ServerWebSocket<WebSocketBridgeData>): void;
+    fromClient(message: Message): void;
+    downstreamDrain(): void;
+    refreshBuffered(): void;
+    close(code: number, reason: string): void;
+    terminate(): void;
+    downstreamClose(code: number, reason: string): void;
+}
+export declare function createWebSocketBridge(options?: WebSocketBridgeOptions): WebSocketBridge;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffusion/bungee-core",
-  "version": "5.16.0",
+  "version": "5.17.0",
   "description": "Bungee reverse proxy core engine",
   "main": "./dist/main.js",
   "types": "./dist/main.d.ts",
@@ -12,7 +12,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@jeffusion/bungee-types": "^5.16.0",
+    "@bungee/ws-client": "npm:ws@8.22.0",
+    "@types/ws": "^8.18.1",
+    "@jeffusion/bungee-types": "^5.17.0",
     "@types/lodash-es": "^4.17.12",
     "acorn": "^8.15.0",
     "canonicalize": "3.0.0",