feat: add opt-in bandwidth monitoring behind BANDWIDTH_MONITOR_ENABLED #1094
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| import { WebSocket } from 'ws'; | ||
|
|
||
| /** | ||
| * Optional, opt-in bandwidth monitoring. Tracks bytes sent by every response | ||
| * the server emits (HTTP responses and every WebSocket channel: shell, chat, | ||
| * desktop notifications, plugin proxy), bucketed by a coarse key, and logs | ||
| * totals on an interval so they can be correlated against client-side data | ||
| * usage readings. Disabled by default - enable with BANDWIDTH_MONITOR_ENABLED=true. | ||
| */ | ||
|
|
||
| export function isBandwidthMonitorEnabled(): boolean { | ||
| return process.env.BANDWIDTH_MONITOR_ENABLED === 'true'; | ||
| } | ||
|
|
||
| type BandwidthBucket = { | ||
| messages: number; | ||
| bytes: number; | ||
| }; | ||
|
|
||
| const buckets = new Map<string, BandwidthBucket>(); | ||
| const monitorStartedAt = Date.now(); | ||
|
|
||
| function bucketFor(key: string): BandwidthBucket { | ||
| let bucket = buckets.get(key); | ||
| if (!bucket) { | ||
| bucket = { messages: 0, bytes: 0 }; | ||
| buckets.set(key, bucket); | ||
| } | ||
| return bucket; | ||
| } | ||
|
|
||
| export function recordBandwidth(key: string, byteLength: number): void { | ||
| if (!isBandwidthMonitorEnabled()) { | ||
| return; | ||
| } | ||
| const bucket = bucketFor(key); | ||
| bucket.messages += 1; | ||
| bucket.bytes += byteLength; | ||
| } | ||
|
|
||
| export function estimateByteLength(data: unknown): number { | ||
| if (typeof data === 'string') { | ||
| return Buffer.byteLength(data, 'utf8'); | ||
| } | ||
| if (Buffer.isBuffer(data)) { | ||
| return data.length; | ||
| } | ||
| if (data instanceof ArrayBuffer) { | ||
| return data.byteLength; | ||
| } | ||
| if (ArrayBuffer.isView(data)) { | ||
| return data.byteLength; | ||
| } | ||
| return 0; | ||
| } | ||
|
|
||
| let loggingStarted = false; | ||
|
|
||
| export function startBandwidthLogging(intervalMs = 10_000): void { | ||
| if (!isBandwidthMonitorEnabled() || loggingStarted) { | ||
| return; | ||
| } | ||
| loggingStarted = true; | ||
|
|
||
| const timer = setInterval(() => { | ||
| const elapsedSec = ((Date.now() - monitorStartedAt) / 1000).toFixed(1); | ||
| const entries = Array.from(buckets.entries()).sort((a, b) => b[1].bytes - a[1].bytes); | ||
| const totalBytes = entries.reduce((sum, [, bucket]) => sum + bucket.bytes, 0); | ||
| const breakdown = entries | ||
| .map(([key, bucket]) => `${key}: ${bucket.messages} msgs / ${(bucket.bytes / 1024).toFixed(1)}KB`) | ||
| .join(' | '); | ||
|
|
||
| console.log( | ||
| `[bandwidth-monitor] elapsed=${elapsedSec}s TOTAL=${(totalBytes / 1024).toFixed(1)}KB${breakdown ? ' | ' + breakdown : ''}` | ||
| ); | ||
| }, intervalMs); | ||
|
|
||
| timer.unref(); | ||
| } | ||
|
|
||
| type TaggedWebSocket = WebSocket & { _bandwidthRoute?: string }; | ||
|
|
||
| let webSocketSendPatched = false; | ||
|
|
||
| /** | ||
| * Monkey-patches WebSocket.prototype.send once so every outbound WS frame on | ||
| * every channel (shell, chat, desktop-notifications, plugin proxy) is | ||
| * counted, without needing to instrument each service individually. No-op | ||
| * unless bandwidth monitoring is enabled. | ||
| */ | ||
| export function patchWebSocketBandwidthTracking(): void { | ||
| if (!isBandwidthMonitorEnabled() || webSocketSendPatched) { | ||
| return; | ||
| } | ||
| webSocketSendPatched = true; | ||
|
|
||
| const originalSend = WebSocket.prototype.send; | ||
|
|
||
| WebSocket.prototype.send = function patchedSend( | ||
| this: TaggedWebSocket, | ||
| data: Parameters<typeof originalSend>[0], | ||
| ...rest: unknown[] | ||
| ) { | ||
| try { | ||
| const route = this._bandwidthRoute ?? 'ws:unknown'; | ||
| recordBandwidth(route, estimateByteLength(data)); | ||
| } catch { | ||
| // Monitoring must never break real traffic. | ||
| } | ||
|
|
||
| // @ts-expect-error - forwarding the library's overloaded variadic signature as-is | ||
| return originalSend.call(this, data, ...rest); | ||
| }; | ||
| } | ||
|
|
||
| export function tagWebSocketRoute(ws: WebSocket, route: string): void { | ||
| if (!isBandwidthMonitorEnabled()) { | ||
| return; | ||
| } | ||
| (ws as TaggedWebSocket)._bandwidthRoute = `ws:${route}`; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
Repository: siteboon/claudecodeui
Length of output: 11345
🌐 Web query:
Node.js http.ServerResponse events close finish premature termination client aborted documentation💡 Result:
In Node.js, the http.ServerResponse object behaves as a Writable stream. To identify a premature termination (such as a client aborting the request), you should monitor the close event and verify that the response did not finish normally [1][2]. Event definitions: - finish: Emitted when the last segment of the response headers and body have been handed off to the operating system for transmission [3][4]. It does not guarantee that the client received the data [3][5]. - close: Emitted when the response is completed or when the underlying connection is terminated prematurely (before the response is fully sent) [3]. Detecting Premature Termination: Because the close event is emitted regardless of whether the response finished successfully or was terminated, you must check the status of the response to distinguish between these cases [6][7]. The standard way to detect a premature termination is to check if the response was not properly finalized [1][2]: const server = http.createServer((req, res) => { res.on('close', => { if (!res.writableEnded) { console.log('Response was aborted by the client'); } else { console.log('Response closed normally'); } }); }); Alternatively, you can check res.writableFinished, which will be true only if the response finished successfully [3][4]. Note on Modern Practices: - The 'aborted' event on requests and responses has been largely deprecated or discouraged in favor of checking the 'close' event alongside the stream's state [7][2]. - For cancelling asynchronous work (like database queries) when a client disconnects, you can now use the req.signal property, which provides an AbortSignal that is aborted when the underlying socket closes or the request is destroyed [8]. - Be aware that in recent Node.js versions, there has been an ongoing effort to align stream behaviors. Generally, a "clean abort" (where the connection closes without an explicit error) will emit 'close' without emitting an 'error' event [1][2]. Always prioritize checking!res.writableEnded or!res.writableFinished within the 'close' event listener to reliably detect interruptions [2].
Citations:
🌐 Web query:
Node.js http.ServerResponse close finish both emitted response finished normally documentation💡 Result:
In Node.js, the 'finish' and 'close' events on an http.ServerResponse serve distinct purposes regarding the lifecycle of an HTTP response [1][2]. 'finish' event The 'finish' event is emitted when the response has been sent [1][3]. Specifically, this occurs when the last segment of the response headers and body has been handed off to the operating system for transmission over the network [1][4]. It does not guarantee that the client has received the data; it only signifies that Node.js has completed its local processing and handed the data to the system [1][2]. After this event, no further events are emitted on the response object [3][5]. 'close' event The 'close' event indicates that the response has completed, or that the underlying connection was terminated prematurely before the response was finished [1][6]. In modern Node.js versions, this event is emitted at the end of every response, regardless of whether it finished successfully or was interrupted [6][2]. Comparison While both events are relevant to the end of a request/response cycle, their primary distinction lies in what they signify [2]: - 'finish' tracks the successful hand-off of the outgoing data to the OS [1][2]. - 'close' tracks the final state of the response object or its underlying connection [6][2]. When a response completes normally, both events are typically emitted [6]. Comparing these two events can be useful for diagnostics; for example, if a 'close' event occurs without a corresponding 'finish', it may indicate that the connection was terminated prematurely [2].
Citations:
Record bandwidth for responses that close early.
res.on('finish')misses responses after some chunks are written if the connection closes before the response finishes. Use a one-time guarded listener on bothfinishandclosesorecordBandwidthstill runs, including when Node has already handed data off to the OS.🤖 Prompt for AI Agents