@jeffusion/bungee-core 5.15.2 → 5.17.0

package/dist/config-publication/worker-runtime-contract.d.ts

@@ -9,7 +9,7 @@ export interface ConfigWorkerLifecycle<ServingHandle> {
         readonly plugin_status: PluginRuntimeOrchestratorStatusReport;
     }>;
     stop(handle: ServingHandle): Promise<void>;
-    stopAccepting(handle: ServingHandle): Promise<void>;
+    stopAccepting(handle: ServingHandle, drainTimeoutMs?: number): Promise<void>;
     drain(handle: ServingHandle): Promise<void>;
     forceStop?(handle: ServingHandle): Promise<void>;
 }

package/dist/config-worker/lifecycle.d.ts

@@ -1,3 +1,4 @@
+import { type WebSocketBridge, type WebSocketBridgeData } from '../websocket';
 import type { AppConfig } from '@jeffusion/bungee-types';
 import type { Server } from 'bun';
 import { type ConfigWorkerLifecycle } from '../config-publication/worker-runtime-contract';
@@ -8,6 +9,9 @@ import type { PluginServiceHost } from '../plugin-services';
 type LifecycleServer = Pick<Server<unknown>, 'port' | 'stop'>;
 export type ConfigWorkerServingHandle = {
     readonly server: LifecycleServer;
+    readonly websocket?: WebSocketBridge;
+    readonly sessions?: Set<Promise<void>>;
+    closeTimer?: ReturnType<typeof setTimeout>;
     readonly cleanup: () => Promise<void>;
     drainPromise: Promise<void> | null;
     drainComplete: boolean;
@@ -16,6 +20,7 @@ export type ConfigWorkerServingHandle = {
     stopPromise: Promise<void> | null;
 };
 type LifecycleFetch = (request: Request) => Response | Promise<Response>;
+type WebSocketFetch = (request: Request, server?: Bun.Server<any>) => Response | undefined | Promise<Response | undefined>;
 export type ServingRequestContext = {
     readonly servingRevision: number;
     readonly logging?: RequestLoggerDependencies;
@@ -34,6 +39,7 @@ export type ProductionResources = {
     cleanupPluginRuntime(): Promise<void>;
     handleRequest(request: Request, config: AppConfig, context: ServingRequestContext): Promise<Response>;
     serve(fetch: LifecycleFetch): LifecycleServer;
+    serveWebSocket?(fetch: WebSocketFetch, websocket: Bun.WebSocketHandler<WebSocketBridgeData>): LifecycleServer;
     closeAccessLog(): Promise<void>;
     closeFileLog(): Promise<void>;
 };

package/dist/data-admission/worker.d.ts

@@ -42,6 +42,7 @@ export declare class WorkerRequestAdmission {
         url: string;
         model: string | null;
         body: unknown;
+        transport?: 'websocket';
     }, signal: AbortSignal, loadBody?: () => Promise<unknown>): Promise<PreparedAdmissionAttempt[]>;
     release(): Promise<void>;
 }

package/dist/gateway/contracts.d.ts

@@ -107,4 +107,4 @@ export interface GatewayLogResult {
     readonly logger?: RequestLogger;
 }
 /** Provider stages are fixed, required, and registered exactly once at startup. */
-export declare const GATEWAY_PROVIDER_STAGES: readonly ["onGatewayBody", "onGatewayRequest", "onGatewayRoute", "onGatewayAdmission", "onGatewayAdmissionSession", "onGatewayAdmissionPrepare", "onGatewaySelect", "onGatewayFailover", "onGatewayRetry", "onGatewayForward", "onGatewayHeaderRules", "onGatewayCors", "onGatewayBodyRules", "onGatewayQueryRules", "onGatewayResponseRules", "onGatewayLog"];
+export declare const GATEWAY_PROVIDER_STAGES: readonly ["onGatewayWebSocket", "onGatewayBody", "onGatewayRequest", "onGatewayRoute", "onGatewayAdmission", "onGatewayAdmissionSession", "onGatewayAdmissionPrepare", "onGatewaySelect", "onGatewayFailover", "onGatewayRetry", "onGatewayForward", "onGatewayHeaderRules", "onGatewayCors", "onGatewayBodyRules", "onGatewayQueryRules", "onGatewayResponseRules", "onGatewayLog"];

package/dist/gateway/plugin.d.ts

@@ -6,6 +6,7 @@ export type * from '../plugin-extensions';
 export type * from '../plugin-services';
 export type * from './contracts';
 export type * from './body-contracts';
+export type * from './websocket-contracts';
 export { protocolSSEOutput } from '../plugins/sse-envelope';
 export { logger } from '../plugin-logger';
 export { ANONYMOUS_PRINCIPAL } from '../plugin-extensions';

package/dist/gateway/plugin.js

@@ -319,6 +319,9 @@ var init_impl = __esm(() => {
 // src/hooks/plugin-hooks.ts
 function createPluginHooks() {
   return {
+    onGatewayWebSocket: new AsyncSeriesBailHook("onGatewayWebSocket"),
+    onWebSocketHandshake: new AsyncSeriesWaterfallHook("onWebSocketHandshake"),
+    onWebSocketObservation: new WebSocketObservationHook("onWebSocketObservation"),
     onGatewayBody: new SyncBailHook("onGatewayBody"),
     onGatewayRequest: new AsyncSeriesBailHook("onGatewayRequest"),
     onGatewayRoute: new AsyncSeriesBailHook("onGatewayRoute"),
@@ -358,7 +361,7 @@ function clearHooks(hooks) {
   for (const hook of Object.values(hooks))
     hook.clear();
 }
-var AttemptObservationHook;
+var AttemptObservationHook, WebSocketObservationHook;
 var init_plugin_hooks = __esm(() => {
   init_impl();
   AttemptObservationHook = class AttemptObservationHook extends AsyncParallelHook {
@@ -374,6 +377,17 @@ var init_plugin_hooks = __esm(() => {
       }
     }
   };
+  WebSocketObservationHook = class WebSocketObservationHook extends AsyncParallelHook {
+    async promise(...args) {
+      this.callCount++;
+      const started = performance.now();
+      try {
+        await Promise.all(this.taps.map((tap) => this.executeTap(tap, args)));
+      } finally {
+        this.totalTimeMs += performance.now() - started;
+      }
+    }
+  };
 });
 
 // src/hooks/index.ts

package/dist/gateway/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type PluginHooks } from '../hooks';
 import type { Plugin } from '../plugin.types';
 import { type executeHttpRequest } from './request-plugin';
+import type { GatewayWebSocketInput, GatewayWebSocketResult } from './websocket-contracts';
 export declare function gatewayBuiltins(): Plugin[];
 /** The host only owns registration; providers use the existing Plugin contract and Hook executor. */
 export declare function registerGatewayBuiltins(hooks: PluginHooks, plugins?: readonly Plugin[]): void;
@@ -10,3 +11,4 @@ export declare function gatewayHooks(): PluginHooks;
 export declare function initializeGateway(): void;
 export declare function requireGatewayResult<T>(value: T | undefined, stage: string): T;
 export declare const runGatewayRequest: typeof executeHttpRequest;
+export declare function runGatewayWebSocket(input: GatewayWebSocketInput): Promise<GatewayWebSocketResult>;

package/dist/gateway/websocket-contracts.d.ts

@@ -0,0 +1,62 @@
+/** Read-only WebSocket SDK. HTTP bodies and WebSocket messages have separate owners. */
+export interface WebSocketMessageView {
+    readonly kind: 'text' | 'binary';
+    readonly byteLength: number;
+    /** Demand-driven, shared, deeply frozen JSON; undefined for binary/invalid JSON. */
+    json(): unknown;
+}
+export interface WebSocketSessionContext {
+    readonly connectionId: string;
+    readonly keyId?: string | null;
+    readonly routeId: string;
+    readonly upstreamId: string;
+    readonly upstreamUrl: string;
+    readonly servingRevision?: number;
+}
+export interface WebSocketSessionMetrics {
+    readonly durationMs: number;
+    readonly clientMessages: number;
+    readonly upstreamMessages: number;
+    readonly clientBytes: number;
+    readonly upstreamBytes: number;
+}
+export type WebSocketObservationEvent = Readonly<WebSocketSessionContext & {
+    /** Delivery lease expires when the observer returns or exceeds its deadline. */
+    readonly isActive: () => boolean;
+} & ({
+    readonly phase: 'open';
+} | {
+    readonly phase: 'message';
+    readonly direction: 'client' | 'upstream';
+    readonly message: WebSocketMessageView;
+} | {
+    readonly phase: 'incomplete';
+    readonly reason: 'observer-timeout' | 'observer-error' | 'buffer-limit' | 'message-limit';
+} | {
+    readonly phase: 'close';
+    readonly code: number;
+    readonly reason: string;
+    readonly metrics: WebSocketSessionMetrics;
+})>;
+/** Handshake-only transforms; message data is never mutable through this hook. */
+export interface WebSocketHandshakeContext {
+    readonly connectionId: string;
+    readonly routeId: string;
+    readonly upstreamId: string;
+    readonly signal: AbortSignal;
+    url: URL;
+    headers: Headers;
+}
+export interface GatewayWebSocketInput {
+    readonly request: Request;
+    readonly nativeRequest: Request;
+    readonly server: Bun.Server<any>;
+    readonly bridge: import('../websocket').WebSocketBridge;
+    readonly config: import('@jeffusion/bungee-types').AppConfig;
+    readonly servingRevision: number;
+    /** Host shutdown barrier; retains observer/credential owners until close cleanup. */
+    readonly retain: (completion: Promise<void>) => void;
+}
+export interface GatewayWebSocketResult {
+    readonly response?: Response;
+}

package/dist/gateway/websocket-credential.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeUpstream } from '../worker/types';
+/** Uses the same exact endpoint/binding/origin credential policy as HTTP attempts. */
+export declare function websocketCredential(upstream: RuntimeUpstream, url: URL, sourceHeaders: Headers, revision: number, attemptId: string, signal: AbortSignal): Promise<Headers>;

package/dist/gateway/websocket-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { Plugin, PluginHooks } from '@jeffusion/bungee-core/plugin';
+/** WebSocket is a registered gateway provider, with handshake and read-only message hooks. */
+export declare class WebSocketGatewayPlugin implements Plugin {
+    bodyRequirements(): {
+        request: "none";
+    };
+    register(hooks: PluginHooks): void;
+    private upgrade;
+}

package/dist/hooks/plugin-hooks.d.ts

@@ -1,3 +1,4 @@
+import type { WebSocketObservationEvent, WebSocketHandshakeContext, GatewayWebSocketInput, GatewayWebSocketResult } from '../gateway/websocket-contracts';
 /**
  * Bungee Plugin Hooks 定义
  *
@@ -109,6 +110,10 @@ export type AttemptObservationEvent = Readonly<{
 declare class AttemptObservationHook extends AsyncParallelHook<[AttemptObservationEvent]> {
     promise(...args: [AttemptObservationEvent]): Promise<void>;
 }
+/** Strict, isolated WebSocket observers use the same plugin registration contract. */
+declare class WebSocketObservationHook extends AsyncParallelHook<[WebSocketObservationEvent]> {
+    promise(...args: [WebSocketObservationEvent]): Promise<void>;
+}
 /**
  * 错误上下文
  */
@@ -220,6 +225,9 @@ export declare function createPluginHooks(): PluginHooks;
  * Plugin Hooks 类型
  */
 export interface PluginHooks {
+    onGatewayWebSocket: AsyncSeriesBailHook<[GatewayWebSocketInput], GatewayWebSocketResult>;
+    onWebSocketHandshake: AsyncSeriesWaterfallHook<WebSocketHandshakeContext>;
+    onWebSocketObservation: WebSocketObservationHook;
     onGatewayBody: SyncBailHook<GatewayBodyArguments, BodySource>;
     onGatewayHeaderRules: AsyncSeriesBailHook<GatewayHeaderRuleArguments, true>;
     onGatewayCors: AsyncSeriesBailHook<GatewayCorsArguments, Response>;

package/dist/logger/access-log-writer.d.ts

@@ -100,7 +100,7 @@ export declare const accessLogWriter: {
     getDatabase: () => Database;
     updateResponseBodyId: (requestId: string, respBodyId: string) => void;
     updateBodyId: (requestId: string, type: "request" | "response" | "original-request", bodyId: string) => void;
-    updateProtocolOutcome: (requestId: string, outcome: "cancelled" | "failed" | "completed" | "incomplete", success: boolean, code?: string | undefined, diagnosticMessage?: string | undefined) => void;
+    updateProtocolOutcome: (requestId: string, outcome: "incomplete" | "cancelled" | "failed" | "completed", success: boolean, code?: string | undefined, diagnosticMessage?: string | undefined) => void;
     updateTransportOutcome: (requestId: string, outcome: "cancelled" | "unknown" | "failed" | "pending" | "completed", code?: string | undefined) => void;
     flush: () => Promise<void>;
     close: () => Promise<void>;