@jeffusion/bungee-core 5.15.2 → 5.17.0

package/dist/plugins/token-stats/manifest.json

@@ -242,6 +242,8 @@
       "ui.previousInterval": "vs previous {interval}",
       "ui.minutes": "min",
       "ui.hours": "h",
+      "ui.days": "d",
+      "page.trendHint": "Compares the two latest complete time buckets in the selected range; incomplete buckets are excluded.",
       "ui.newActivity": "New",
       "page.range": "Time range",
       "page.range.1h": "1 hour",
@@ -355,6 +357,8 @@
       "ui.previousInterval": "较上个{interval}",
       "ui.minutes": "分钟",
       "ui.hours": "小时",
+      "ui.days": "天",
+      "page.trendHint": "对比所选范围内最近两个完整统计时段，未完成时段不参与。",
       "ui.newActivity": "新增",
       "page.range": "时间范围",
       "page.range.1h": "1 小时",

package/dist/plugins/token-stats/ui/TokenStatsPage.svelte

@@ -11,6 +11,8 @@
   import { Input } from '$components/ui/input';
   import UsageTimeChart from './UsageTimeChart.svelte';
   import { getStatsResource } from './stats';
+  import KpiTrendValue from '$components/industrial/KpiTrendValue.svelte';
+  import { overviewTrends, PAGE_METRICS } from './overview-trends';
   import { formatCacheInputPercentage, formatEstimatedUsd, formatTokenCount, modelTokenTotal, tokenComposition, usagePresentation, type TokenPageRange } from './labels';
   import type { StatsState, StatsResource } from './stats-resource';
 
@@ -21,11 +23,12 @@
   let keysFailed = $state(false);
   let sort = $state('tokens');
   let search = $state('');
-  let models: StatsState = $state({ data: null, busy: false, error: '', refreshedAt: 0 });
-  let time: StatsState = $state({ data: null, busy: false, error: '', refreshedAt: 0 });
+  let models: StatsState = $state({ data: null, busy: true, error: '', refreshedAt: 0 });
+  let time: StatsState = $state({ data: null, busy: true, error: '', refreshedAt: 0 });
   let modelResource: StatsResource | undefined = $state();
   let timeResource: StatsResource | undefined = $state();
-  const t = (key: string) => $isLoading ? '' : getPluginText(key, pluginName, (id, options) => $_(id, options));
+  const t = (key: string, values?: Record<string, string>) => $isLoading ? '' : getPluginText(key, pluginName,
+    (id, options) => $_(id, { ...options, values }));
   const display = formatCompactNumber;
   const fullCount = (value: unknown) => formatTokenCount(value, $locale ?? undefined);
   const displayCost = (value: unknown) => typeof value === 'number' && value >= 1000
@@ -47,6 +50,16 @@
     .filter(row => modelLabel(row.dimension).toLowerCase().includes(search.trim().toLowerCase()))
     .sort((a, b) => rankAmount(b) - rankAmount(a) || a.dimension.localeCompare(b.dimension)));
   const maxTokens = $derived(Math.max(0, ...rows.map(row => modelTokenTotal(row) ?? 0)));
+  const modelsLoading = $derived(models.busy && !models.data);
+  const trends = $derived(overviewTrends(time.error || time.data?.reportingIncomplete ? null : time.data, PAGE_METRICS));
+  const comparisonCaption = $derived(t('ui.previousInterval', { interval: ['day', '1d'].includes(range)
+    ? `1${t('ui.hours')}` : `1${t('ui.days')}` }));
+  const summaryMetrics = $derived([
+    { metric: 'input', label: t('ui.input'), value: display(usage?.input), title: fullCount(usage?.input) },
+    { metric: 'output', label: t('ui.output'), value: display(usage?.output), title: fullCount(usage?.output) },
+    { metric: 'tokens', label: t('page.tokens'), value: display(models.data ? modelTokenTotal(models.data) : null), title: fullCount(models.data ? modelTokenTotal(models.data) : null) },
+    { metric: 'cost', label: t('ui.estimatedCostUsd'), value: displayCost(models.data?.estimatedCostUsd), title: formatEstimatedUsd(models.data?.estimatedCostUsd) },
+  ] as const);
   const busy = $derived(models.busy || time.busy);
   const refreshedAt = $derived(Math.min(models.refreshedAt, time.refreshedAt));
   const ranges = $derived(['day', 'week', 'month', '1d', '7d', '30d'].map(value => ({ value, label: t(`page.range.${value}`) })));
@@ -76,6 +89,10 @@
   function refresh() { void modelResource?.refresh(); void timeResource?.refresh(); }
 </script>
 
+{#snippet loadingKpi()}
+  <LoadingIndicator label={t('ui.loading')} size="sm" height="none" class="h-9 w-full" />
+{/snippet}
+
 <div class="min-w-0 space-y-4" data-testid="token-stats-page">
   <div class="flex flex-wrap items-center justify-between gap-3">
     <div class="flex flex-wrap items-center gap-3">
@@ -97,29 +114,40 @@
       <span>{t('ui.loadFailed')}</span><Button variant="ghost" size="sm" onclick={refresh} disabled={busy}>{t('page.retry')}</Button>
     </div>
   {/if}
-  {#if models.busy && !models.data}
-    <LoadingIndicator label={t('ui.loading')} height="sm" />
-  {:else if models.data}
-    <div class="grid grid-cols-2 gap-3 xl:grid-cols-4" data-testid="token-stats-page-summary">
-      <KpiCard class="min-w-0 [container-type:inline-size]" label={t('ui.input')} value={display(usage?.input)} valueTitle={fullCount(usage?.input)} />
-      <KpiCard class="min-w-0 [container-type:inline-size]" label={t('ui.output')} value={display(usage?.output)} valueTitle={fullCount(usage?.output)} />
-      <KpiCard class="min-w-0 [container-type:inline-size]" label={t('page.tokens')} value={display(modelTokenTotal(models.data))} valueTitle={fullCount(modelTokenTotal(models.data))} />
-      <KpiCard class="min-w-0 [container-type:inline-size]" label={t('ui.estimatedCostUsd')} value={displayCost(models.data.estimatedCostUsd)} valueTitle={formatEstimatedUsd(models.data.estimatedCostUsd)} />
-    </div>
-    {#if usage?.state === 'empty'}<p class="py-8 text-center text-sm text-zinc-400" data-testid="token-stats-page-empty">{t('ui.noData')}</p>{/if}
-  {/if}
+  <div class="grid grid-cols-2 gap-3 xl:grid-cols-4" data-testid="token-stats-page-summary" aria-busy={modelsLoading}>
+    {#each summaryMetrics as item, index (item.metric)}
+      {@const trend = trends[index]!}
+      <KpiCard fillHeight reserveFooter class="h-[144px] min-w-0 [container-type:inline-size] xl:h-[168px]"
+        label={item.label} value={item.value} valueTitle={item.title} children={modelsLoading ? loadingKpi : undefined}>
+        {#snippet foot()}
+          <div class="flex h-full min-w-0 flex-wrap items-center gap-x-1.5 gap-y-0.5" data-testid={`token-stats-page-trend-${item.metric}`} title={t('page.trendHint')}>
+            {#if time.busy && !time.data}
+              <LoadingIndicator size="xs" centered={false} height="none" label={t('ui.loading')} />
+            {:else}
+              <KpiTrendValue value={trend.isNew ? t('ui.newActivity') : trend.percent == null ? '—' : `${trend.percent >= 0 ? '+' : ''}${trend.percent.toFixed(1)}%`}
+                change={trend.change} direction={item.metric === 'cost' ? 'down' : 'up'} clamp />
+              <span class="nx-label-sm">{comparisonCaption}</span>
+            {/if}
+          </div>
+        {/snippet}
+      </KpiCard>
+    {/each}
+  </div>
+  {#if usage?.state === 'empty'}<p class="py-8 text-center text-sm text-zinc-400" data-testid="token-stats-page-empty">{t('ui.noData')}</p>{/if}
 
   <PanelCard title={t('page.activity')} tag="TOKEN / TIME">
     <div class="h-[240px] min-w-0 sm:h-[300px]">
-      {#if time.busy && !time.data}<LoadingIndicator label={t('ui.loading')} />
+      {#if time.busy && !time.data}<LoadingIndicator label={t('ui.loading')} height="none" class="h-full" />
       {:else if time.data && usagePresentation(time.data).positive}
         <UsageTimeChart stats={time.data} {range} refreshedAt={time.refreshedAt} {pluginName} presentation="page" />
       {:else}<p class="flex h-full items-center justify-center text-sm text-zinc-400">{t(time.data && usagePresentation(time.data).state === 'empty' ? 'ui.noData' : 'ui.noBreakdown')}</p>{/if}
     </div>
   </PanelCard>
 
-  {#if models.data}
-    <PanelCard title={t('page.models')} tag={`${rows.length} / ${models.data.data.length}`}>
+  <PanelCard title={t('page.models')} tag={models.data ? `${rows.length} / ${models.data.data.length}` : ''}>
+    {#if modelsLoading}
+      <LoadingIndicator label={t('ui.loading')} />
+    {:else if models.data}
       <div class="mb-3 flex flex-wrap items-center gap-3">
         <BSegmentedControl options={sorts} bind:value={sort} ariaLabel={t('page.sort')} class="shrink-0" />
         <Input bind:value={search} aria-label={t('page.searchModels')} placeholder={t('page.searchModels')} class="min-w-[140px] flex-1 sm:max-w-64" />
@@ -143,6 +171,8 @@
           </li>
         {:else}<li class="py-6 text-center text-xs text-zinc-400">{t(search ? 'page.noModels' : 'ui.noData')}</li>{/each}
       </ol>
-    </PanelCard>
-  {/if}
+    {:else}
+      <p class="py-6 text-center text-xs text-zinc-400">{t(models.error ? 'ui.loadFailed' : 'ui.noData')}</p>
+    {/if}
+  </PanelCard>
 </div>

package/dist/plugins/token-stats/ui/overview-trends.ts

@@ -1,29 +1,42 @@
 import { bucketTrend } from '../../../packages/ui/src/components/dashboard/trends';
-import { usagePresentation } from './labels';
+import { modelTokenTotal, usagePresentation } from './labels';
 import type { StatsResponse } from './stats-resource';
 
 export const OVERVIEW_METRICS = ['input', 'output', 'cost'] as const;
 export type OverviewMetric = typeof OVERVIEW_METRICS[number];
-export type OverviewTrend = { metric: OverviewMetric; percent: number | null; change: 'up' | 'down' | 'flat' | null; isNew: boolean };
+export const PAGE_METRICS = ['input', 'output', 'tokens', 'cost'] as const;
+export type SummaryMetric = typeof PAGE_METRICS[number];
+export type OverviewTrend = { metric: SummaryMetric; percent: number | null; change: 'up' | 'down' | 'flat' | null; isNew: boolean };
 
 /** Compare adjacent completed server buckets. Missing traffic is zero; missing metering stays unknown. */
-export function overviewTrends(snapshot: StatsResponse | null): OverviewTrend[] {
+export function overviewTrends(snapshot: StatsResponse | null, metrics: readonly SummaryMetric[] = OVERVIEW_METRICS): OverviewTrend[] {
   const { asOfMs, bucketMs } = snapshot ?? {};
-  const valid = snapshot?.groupBy === 'time' && Number.isSafeInteger(asOfMs) && Number.isSafeInteger(bucketMs) && bucketMs! > 0;
-  const currentStart = valid ? Math.floor(asOfMs! / bucketMs!) * bucketMs! - bucketMs! : NaN;
-  return OVERVIEW_METRICS.map(metric => {
+  let valid = snapshot?.groupBy === 'time' && Number.isSafeInteger(asOfMs) && Number.isSafeInteger(bucketMs) && bucketMs! > 0;
+  let currentStart = valid ? Math.floor(asOfMs! / bucketMs!) * bucketMs! - bucketMs! : NaN;
+  let previousStart = currentStart - bucketMs!;
+  if (valid && snapshot?.bucketStarts) {
+    const starts = snapshot.bucketStarts;
+    valid = starts.every((start, index) => Number.isSafeInteger(start) && (index === 0 || start > starts[index - 1]!));
+    // Calendar days can span 23/25 hours; rolling page windows need not align with the UTC clock.
+    const current = valid ? starts.findLastIndex((start, index) =>
+      (starts[index + 1] ?? snapshot.bucketEndMs ?? start + bucketMs!) <= asOfMs!) : -1;
+    valid = current >= 1;
+    currentStart = valid ? starts[current]! : NaN;
+    previousStart = valid ? starts[current - 1]! : NaN;
+  }
+  return metrics.map(metric => {
     const amount = (start: number): number | null => {
       if (!valid) return null;
       const rows = snapshot!.data.filter(row => row.bucketStartMs === start);
       let total = 0;
       for (const row of rows) {
-        const value = metric === 'cost' ? row.estimatedCostUsd : usagePresentation(row)[metric];
+        const value = metric === 'cost' ? row.estimatedCostUsd : metric === 'tokens' ? modelTokenTotal(row) : usagePresentation(row)[metric];
         if (value == null || !Number.isFinite(value) || value < 0) return null;
         total += value;
       }
       return total;
     };
-    const previous = amount(currentStart - bucketMs!), current = amount(currentStart);
+    const previous = amount(previousStart), current = amount(currentStart);
     const known = previous !== null && current !== null;
     const percent = known ? bucketTrend([previous, current]) : null;
     return { metric, percent: Number.isFinite(percent) ? percent : null,

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.15.2",
+  "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.15.2",
+    "@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",