velocious 1.0.680 → 1.0.682

package/src/http-server/client/index.js

@@ -61,6 +61,11 @@ export default class VeoliciousHttpServerClient {
 
     /** @type {Set<(result: "completed" | "aborted") => Promise<void>>} */
     this.pendingFileResponses = new Set()
+
+    /**
+     * Streams that have started but have not finished or been aborted yet.
+     * @type {Map<import("./response.js").default, {clientCount: number, request: import("./request.js").default}>} */
+    this._activeStreamResponses = new Map()
   }
 
   /**
@@ -181,6 +186,15 @@ export default class VeoliciousHttpServerClient {
 
     this.requestRunners.push(requestRunner)
 
+    // A streaming response emits its headers and chunks to the client while
+    // the request is still running, so the response needs the owning client
+    // as its transport sink before the handler runs. Sub-requests (e.g.
+    // websocket request payloads) have no socket and keep transport null;
+    // their responses fail loudly if they attempt to stream.
+    const socketRequest = currentRequest
+    requestRunner.response.transport = this
+    requestRunner.response.transportRequest = socketRequest
+
     requestRunner.events.on("done", this.requestDone)
     requestRunner.run()
   }
@@ -423,6 +437,15 @@ export default class VeoliciousHttpServerClient {
    */
   async sendResponse(requestRunner) {
     const response = digg(requestRunner, "response")
+
+    // A streaming response already emitted its status line, headers, every
+    // chunk, and the chunked terminator to the client while the request was
+    // running. Nothing left to send here — just log the completed request.
+    if (response.isStreaming()) {
+      await requestRunner.logCompletedRequest()
+      return
+    }
+
     const request = requestRunner.getRequest()
     const filePath = response.getFilePath()
     const fileOnFinished = response.getFileOnFinished()
@@ -666,6 +689,143 @@ export default class VeoliciousHttpServerClient {
     await Promise.all([...this.pendingFileResponses].map((settle) => settle("aborted")))
   }
 
+  /**
+   * Sink the owning worker handler wires in for stream output. The
+   * in-process handler resolves it after the framed output has been enqueued
+   * for delivery to the socket, so stream chunks share the bounded, ordered
+   * delivery path (byte/frame limits and socket backpressure) instead of
+   * being buffered unboundedly for a stalled client. The worker-thread
+   * handler keeps null: its output crosses to the parent over IPC and no
+   * per-chunk acknowledgement is available.
+   * @type {((output: string) => Promise<void>) | null} */
+  streamOutputSink = null
+
+  /**
+   * Narrows the response to the documented streaming transport shape.
+   * @param {import("./response.js").default} response - Response to stream.
+   * @returns {{streaming: boolean, streamEnded: boolean, streamAborted: boolean, headers: Record<string, string[]>, getStatusCode: () => number, getStatusMessage: () => string, streamCloseCallbacks: Set<() => void>}} - Streaming view of the response.
+   */
+  _streamingResponse(response) {
+    return response
+  }
+
+  /**
+   * Starts a live chunked stream for a socket-bound response: emits the
+   * status line and headers (with `Transfer-Encoding: chunked`) to the
+   * client immediately so subsequent `write()` chunks reach the client as
+   * they are produced.
+   * @param {import("./response.js").default} response - Response to stream.
+   * @param {import("./request.js").default} request - Socket-bound request.
+   * @returns {void} - No return value.
+   */
+  beginStreamResponse(response, request) {
+    this._activeStreamResponses.set(response, {clientCount: this.clientCount, request})
+
+    const httpVersion = request.httpVersion()
+
+    // HTTP/1.0 has no chunked transfer encoding: terminate the stream with a
+    // connection close instead of a zero-length chunk.
+    if (httpVersion == "1.0" && !this.shouldCloseConnection(request)) {
+      response.setHeader("Connection", "Close")
+    }
+
+    // The chunked framing owns the body length; a Content-Length header set
+    // by the application before stream() would desynchronize the framing.
+    response.removeHeader("Content-Length")
+    if (response.getHeader("Transfer-Encoding").length === 0) {
+      response.setHeader("Transfer-Encoding", "chunked")
+    }
+
+    response.setHeader("Date", new Date().toUTCString())
+    response.setHeader("Server", "Velocious")
+
+    const responseView = this._streamingResponse(response)
+    let headers = ""
+    headers += `HTTP/${httpVersion} ${responseView.getStatusCode()} ${responseView.getStatusMessage()}\r\n`
+
+    for (const headerKey in responseView.headers) {
+      for (const headerValue of responseView.headers[headerKey]) {
+        headers += `${headerKey}: ${headerValue}\r\n`
+      }
+    }
+
+    headers += "\r\n"
+    this.events.emit("output", headers)
+  }
+
+  /**
+   * Emits one chunked-encoded body chunk for an active stream.
+   * @param {string | Uint8Array} chunk - Chunk to emit.
+   * @returns {Promise<void>} - Settles after the chunk has been delivered to
+   * the client.
+   */
+  async writeStreamChunk(chunk) {
+    const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk)
+    const frame = `${bytes.length.toString(16)}\r\n${bytes}\r\n`
+    if (this.streamOutputSink === null) {
+      this.events.emit("output", frame)
+      return
+    }
+    await this.streamOutputSink(frame)
+  }
+
+  /**
+   * Emits the zero-length chunked terminator for a stream that finished on a
+   * live connection, then runs its close callbacks.
+   * @param {import("./response.js").default} response - Response to finish.
+   * @returns {Promise<void>} - Settles after the terminator was delivered and
+   * the close callbacks ran.
+   */
+  async endStreamResponse(response) {
+    if (response.streamEnded) return
+    response.streamEnded = true
+    this._activeStreamResponses.delete(response)
+    if (this.streamOutputSink === null) {
+      this.events.emit("output", "0\r\n\r\n")
+    } else {
+      await this.streamOutputSink("0\r\n\r\n")
+    }
+    await this._runStreamCloseCallbacks(response)
+  }
+
+  /**
+   * Aborts every stream whose client connection went away: marks the stream
+   * aborted and runs the close callbacks so in-flight work can settle its
+   * resources. No terminator is emitted — the connection is already gone.
+   * @returns {Promise<void>} - Resolves after every stream settled.
+   */
+  async abortStreamResponses() {
+    for (const response of [...this._activeStreamResponses.keys()]) {
+      if (response.streamAborted) continue
+      response.streamAborted = true
+      this._activeStreamResponses.delete(response)
+      await this._runStreamCloseCallbacks(response)
+    }
+  }
+
+  /**
+   * Runs the close callbacks of a finished or aborted stream exactly once.
+   * @param {import("./response.js").default} response - Finished stream.
+   * @returns {Promise<void>} - Resolves after every callback ran.
+   */
+  async _runStreamCloseCallbacks(response) {
+    if (response.streamCloseCallbacks.size === 0) return
+
+    for (const callback of response.streamCloseCallbacks) {
+      try {
+        callback()
+      } catch (error) {
+        const errorPayload = {
+          context: {clientCount: this.clientCount, stage: "stream-close-callback"},
+          error
+        }
+        this.configuration.getErrorEvents().emit("framework-error", errorPayload)
+        this.configuration.getErrorEvents().emit("all-error", {...errorPayload, errorType: "framework-error"})
+      }
+    }
+    response.streamCloseCallbacks.clear()
+  }
+
   /**
    * Runs should close connection.
    * @param {import("./request.js").default | import("./websocket-request.js").default} request - Request object.

package/src/http-server/client/request-runner.js

@@ -305,12 +305,20 @@ export default class VelociousHttpServerClientRequestRunner {
       })
 
       response.setStatus(500)
-      try {
-        response.setErrorBody(error)
-      } catch (responseError) {
-        if (!(responseError instanceof HttpResponseBodyTooLargeError)) throw responseError
+      if (response.isStreaming()) {
+        // The headers already went to the client, so a plain error body is
+        // impossible. The handler owns the stream lifecycle: it aborts the
+        // stream (terminator + close callbacks) or, when it still controls
+        // the connection, writes an error SSE frame.
+        response.abortStream()
+      } else {
+        try {
+          response.setErrorBody(error)
+        } catch (responseError) {
+          if (!(responseError instanceof HttpResponseBodyTooLargeError)) throw responseError
 
-        response.setBody("")
+          response.setBody("")
+        }
       }
     }
 

package/src/http-server/client/response.js

@@ -105,6 +105,41 @@ export default class VelociousHttpServerClientResponse {
    * @type {boolean} */
   compressionDisabled = false
 
+  /**
+   * Whether this response has been switched to live chunked streaming. Once
+   * streaming has started, the status line and headers are emitted to the
+   * client immediately and every `write()` is emitted as it happens, instead
+   * of the whole body being buffered and sent once after the handler
+   * returns.
+   * @type {boolean} */
+  streaming = false
+
+  /**
+   * Whether the stream has been finished with `end()` (or finalized).
+   * @type {boolean} */
+  streamEnded = false
+
+  /**
+   * Whether the client connection dropped while the stream was in flight.
+   * @type {boolean} */
+  streamAborted = false
+
+  /**
+   * Transport sink wired in by the owning client so the response can emit
+   * headers and chunks to the socket-bound connection.
+   * @type {import("./index.js").default | null} */
+  transport = null
+
+  /**
+   * The socket-bound request this response belongs to.
+   * @type {import("./request.js").default | null} */
+  transportRequest = null
+
+  /**
+   * Callbacks fired when the client disconnects mid-stream.
+   * @type {Set<() => void>} */
+  streamCloseCallbacks = new Set()
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
@@ -240,6 +275,113 @@ export default class VelociousHttpServerClientResponse {
     this.body = value
   }
 
+  /**
+   * Whether this response is (or was) a live chunked stream.
+   * @returns {boolean} - Whether streaming has started.
+   */
+  isStreaming() {
+    return this.streaming
+  }
+
+  /**
+   * Whether the client disconnected mid-stream.
+   * @returns {boolean} - Whether the stream was aborted by the client.
+   */
+  isStreamAborted() {
+    return this.streamAborted
+  }
+
+  /**
+   * Switches this response to live chunked streaming. The status line and
+   * headers are emitted to the client immediately (with a
+   * `Transfer-Encoding: chunked` framing header) so `write()` chunks reach
+   * the client as they are produced — instead of the whole body being
+   * buffered and emitted once after the handler returns.
+   *
+   * Streaming requires a socket-bound HTTP request and an HTTP version that
+   * supports chunked framing, a status that may carry a body, and a
+   * non-HEAD request. It cannot be combined with a buffered body, a file
+   * response, or a second `stream()` call.
+   * @returns {void} - No return value.
+   */
+  stream() {
+    if (this.streaming) throw new Error("The response is already streaming")
+    if (this.filePath !== null) throw new Error("A file response cannot be switched to streaming")
+    if (this.body !== null && this.body !== undefined) throw new Error("A buffered body was already set; call stream() before setBody() to stream instead")
+    if (this.transport === null) throw new Error("Streaming responses require a socket-bound HTTP request")
+
+    const request = this.transportRequest
+    if (!request) throw new Error("Streaming responses require a socket-bound HTTP request")
+
+    if (request.httpMethod() === "HEAD") throw new Error("HEAD responses cannot stream a body")
+
+    const statusCode = this.getStatusCode()
+    if ((statusCode >= 100 && statusCode < 200) || statusCode === 204 || statusCode === 304) {
+      throw new Error(`Status ${statusCode} cannot carry a streaming body`)
+    }
+
+    this.streaming = true
+    this.transport.beginStreamResponse(this, request)
+  }
+
+  /**
+   * Emits one chunk to the client as soon as it is produced. Returns a
+   * promise that settles once the chunk has been delivered to the socket, so
+   * a relay loop can `await response.write(chunk)` and get socket
+   * backpressure without an ad-hoc drain wait. Rejects when the stream has
+   * ended or been aborted, or when the outbound delivery queue cannot accept
+   * the chunk (a stalled client).
+   * @param {string | Uint8Array} value - Chunk to emit.
+   * @returns {Promise<void>} - Settles after the chunk is delivered.
+   */
+  async write(value) {
+    if (this.transport === null) throw new Error("write() requires an active streaming response")
+    if (!this.streaming) throw new Error("write() requires stream() to be called first")
+    if (this.streamEnded || this.streamAborted) return
+
+    await this.transport.writeStreamChunk(value)
+  }
+
+  /**
+   * Finishes an active stream: emits the chunked terminator and releases the
+   * response for completion logging. Settles after the terminator has been
+   * delivered to the socket.
+   * @returns {Promise<void>} - Settles after the stream is finished.
+   */
+  async end() {
+    if (this.transport === null) throw new Error("end() requires an active streaming response")
+    if (!this.streaming) throw new Error("end() requires stream() to be called first")
+    if (this.streamEnded) return
+
+    await this.transport.endStreamResponse(this)
+  }
+
+  /**
+   * Registers a callback fired when the client disconnects mid-stream, so
+   * the handler can release whatever the in-flight work reserved. Fired at
+   * most once; also fires when the stream is finalized after the client is
+   * already gone.
+   * @param {() => void} callback - Disconnect callback.
+   * @returns {void} - No return value.
+   */
+  onStreamClose(callback) {
+    this.streamCloseCallbacks.add(callback)
+  }
+
+  /**
+   * Terminates an active stream after a framework-level failure (the handler
+   * threw after `stream()` started): emits the chunked terminator and runs
+   * the close callbacks so in-flight work settles its resources. No-op when
+   * the stream already ended or was aborted.
+   * @returns {void} - No return value.
+   */
+  abortStream() {
+    if (!this.streaming || this.streamEnded || this.transport === null) return
+
+    this.streamEnded = true
+    this.transport.endStreamResponse(this)
+  }
+
   /**
    * Runs get file path.
    * @returns {string | null} - File path.

package/src/http-server/worker-handler/in-process.js

@@ -69,6 +69,17 @@ export default class VelociousHttpServerInProcessHandler {
       }
     })
 
+    // Streaming responses emit chunks while the request is running. Route
+    // their framed output through the counted delivery path so a stalled
+    // client cannot buffer engine chunks unboundedly: each chunk settles only
+    // after it has been delivered to the socket, which gives the handler
+    // backpressure, and the byte/frame limits bound what a silent client can
+    // retain before the connection is torn down.
+    httpClient.streamOutputSink = (output) => deliveryQueue.enqueueFrame({
+      byteLength: Buffer.byteLength(output),
+      delivery: () => serverClient.send(output)
+    })
+
     httpClient.events.on("output", (output, {websocketFrame = false} = {}) => {
       if (output !== null && output !== undefined) {
         const delivery = () => serverClient.send(output)
@@ -101,9 +112,13 @@ export default class VelociousHttpServerInProcessHandler {
 
     serverClient.events.on("close", () => {
       deliveryQueue.destroy()
-      const cleanup = httpClient.abortPendingFileResponses()
+      const cleanup = Promise.all([
+        httpClient.abortPendingFileResponses(),
+        httpClient.abortStreamResponses()
+      ])
+        .then(() => {})
         .catch((error) => {
-          this.logger.warn("Failed to abort file responses after client close", error)
+          this.logger.warn("Failed to abort responses after client close", error)
         })
         .finally(() => {
           this.pendingClientCloseCleanups.delete(cleanup)
@@ -160,6 +175,9 @@ export default class VelociousHttpServerInProcessHandler {
         httpClient.abortPendingFileResponses().catch((error) => {
           this.logger.warn("Failed to abort file responses during shutdown", error)
         }),
+        httpClient.abortStreamResponses().catch((error) => {
+          this.logger.warn("Failed to abort streaming responses during shutdown", error)
+        }),
         serverClient.end().catch((error) => {
           this.logger.warn("Failed to close client during shutdown", error)
         })

package/src/http-server/worker-handler/worker-thread.js

@@ -217,7 +217,10 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
     const settlements = []
     const client = this.clients[clientCount]
 
-    if (client) settlements.push(client.abortPendingFileResponses())
+    if (client) {
+      settlements.push(client.abortPendingFileResponses())
+      settlements.push(client.abortStreamResponses())
+    }
 
     for (const [transferId, transfer] of this.fileTransfers) {
       if (transfer.clientCount !== clientCount) continue