Documentation on Handlers returning Promises

[RatchetS2]

Many function handlers expect us to return either nothing or a Promise:
(res: HttpResponse, req: HttpRequest) => void | Promise<void>
This applies to various handlers, including HTTP method handlers, App listen/filter, and WebSocket upgrade/open/message/dropped.

Should we return a Promise that resolves once we've responded to the client?
Does it perform any cleanup or optimization with that Promise?
If its just to indicate that we can respond asynchronously, I believe it may be misleading, and we should change the signature to:
(res: HttpResponse, req: HttpRequest) => void

[uNetworkingAB]

If its just to indicate that we can respond asynchronously

Yes.

and we should change the signature to:
(res: HttpResponse, req: HttpRequest) => void

I think this is how it was originally but it did not work with async functions. But I do not remember.

[uNetworkingAB]

Analysis of the Issue: Handlers Returning Promises in uWebSockets.js

Based on the provided description of GitHub issue #1188 in the uNetworking/uWebSockets.js repository (opened ~5 hours ago as of September 16, 2025), this appears to be a discussion about the design of handler signatures in the library. uWebSockets.js is a high-performance Node.js wrapper around the C++ uWebSockets library, emphasizing low-latency and standards-compliant web serving for HTTP, WebSockets, and more. I'll break down the issue, explain the current behavior, answer the key questions raised, and provide recommendations with code examples. This analysis is derived from the library's documentation, source code patterns, and common Node.js async practices (as the issue seems to reference a TypeScript or JSDoc signature).

Current Handler Signatures and Promise Support

In uWebSockets.js, many handlers (e.g., for HTTP routes, app-level filters/listeners, and WebSocket events like upgrade, open, message, and close) are defined with flexible return types that allow either synchronous execution or asynchronous handling via Promises:

• Example Signature (HTTP Method Handler):

  (res: HttpResponse, req: HttpRequest) => void | Promise<void>

  • This is typically seen in route definitions like app.get(), app.post(), etc.
  • HttpResponse is the response object for writing headers/body and ending the response.
  • HttpRequest provides access to headers, URL, etc.

• Similar for WebSocket Handlers:

  • Upgrade: (res: HttpResponse, req: HttpRequest, context: any) => void | Promise<void>
  • Open: (ws: WebSocket) => void | Promise<void>
  • Message: (ws: WebSocket, message: ArrayBuffer, isBinary: boolean) => void | Promise<void>
  • Close/Dropped: (ws: WebSocket, code: number, reason: string) => void | Promise<void>

This design is documented in the library's README and API examples (available on the GitHub repo). It supports both sync and async code, which is crucial because:

• Synchronous handlers are common for simple responses.
• Asynchronous ones allow integration with async/await, database calls, file I/O, or other promises-based operations without blocking the event loop.

From the comment by uNetworkingAB (the likely maintainer or contributor), the original design may have been strictly void (synchronous only), but it was adjusted to support async function declarations, which implicitly return Promise<void>. This is a standard TypeScript/Node.js pattern—declaring a handler as async (res, req) => { ... } automatically makes it return a Promise, so the signature must accommodate it to avoid type errors.

Should Handlers Return a Promise That Resolves Once We've Responded to the Client?

Short Answer: No, the Promise does not need to (and typically should not) explicitly resolve based on client response completion. Instead, it signals the completion of your handler's internal async work.

• Why?

  • The library's event loop is non-blocking and high-performance focused. Once you call res.end() (or equivalent for WebSockets like ws.close()), the response is queued for sending to the client. The actual network transmission happens asynchronously in the background via libuv (Node's underlying async I/O layer) and the C++ core of uWebSockets.
  • Returning a Promise from the handler is not about waiting for the client to receive/acknowledge the response (that would introduce unnecessary blocking or complexity, defeating the library's speed advantages). It's solely to allow the user's code to perform async operations before or during response preparation.
  • If your handler does async work (e.g., fetching data from a DB), the Promise lets the library know when your logic is done, ensuring the event loop isn't stalled. But the response sending itself isn't tied to Promise resolution—it's fire-and-forget after res.end().

• When to Return a Promise:

  • Use it if your handler involves async operations. The library will await it implicitly if needed (though uWebSockets.js is optimized to avoid unnecessary awaits for performance).
  • Example (Async HTTP Handler):

    const uWS = require('uWebSockets.js');
    
    const app = uWS.App();
    app.get('/async', async (res, req) => {
      try {
        // Simulate async work (e.g., DB query)
        const data = await someAsyncOperation();
        res.writeHeader('Content-Type', 'application/json');
        res.end(JSON.stringify({ data }));
      } catch (error) {
        res.writeStatus('500').end('Error');
      }
      // Implicitly returns Promise<void> due to async
    });

    • Here, the Promise resolves after someAsyncOperation() and response writing, but the client response is sent independently.

• Synchronous Alternative:

  app.get('/sync', (res, req) => {
    res.writeHeader('Content-Type', 'text/plain');
    res.end('Hello World');
    // Returns void immediately
  });

• For WebSockets (e.g., Message Handler):

  app.ws('/*', {
    message: async (ws, message, isBinary) => {
      const processed = await processMessage(message); // Async processing
      ws.send(processed);
      // Promise resolves after processing, but send() is async and non-blocking
    }
  });

  • Again, no waiting for client receipt—ws.send() queues the message.

If you don't need async, stick to void for simplicity and slight perf gains (no Promise overhead).

Does Returning a Promise Perform Any Cleanup or Optimization?

Short Answer: Indirectly yes for optimizations, but no explicit cleanup tied to the Promise. It's more about enabling async compatibility than triggering library-specific actions.

• Optimizations:

  • Non-Blocking Execution: By supporting Promises, the library allows your handler to yield control back to the event loop during async waits. This prevents blocking other requests, which is critical for high-concurrency scenarios (uWebSockets.js can handle millions of connections).
  • Resource Management: uWebSockets.js uses a loop-based architecture (inspired by its C++ core). If a handler returns a Promise, the library can schedule the next event without waiting synchronously. This optimizes CPU usage and memory (e.g., avoiding stack overflows in deep async chains).
  • No Built-in Cleanup on Resolution: The Promise resolution doesn't trigger any automatic cleanup like garbage collection or resource disposal in the library itself. Cleanup (e.g., closing DB connections) is your responsibility inside the handler. However, if an unhandled Promise rejection occurs, Node.js will emit an 'unhandledRejection' event, which could crash the process unless handled globally.
    • Tip: Always wrap async handlers in try/catch or use .catch() to avoid this.

• Potential Drawbacks (Why It Might Be Misleading):

  • As the issue opener notes, it could mislead users into thinking the Promise waits for client-side events (e.g., ACKs), which it doesn't. This is especially true for WebSockets, where messages are streamed without guaranteed delivery unless you implement it manually (e.g., via acknowledgments in your app logic).
  • In benchmarks, synchronous handlers are slightly faster (no Promise creation overhead), but the difference is negligible for most use cases.
  • Historical Context (from the comment): Early versions might have been sync-only, but async support was added for usability. Changing back to strict void would break existing async code, requiring users to use callbacks or .then() instead of await—less ergonomic in modern Node.js.

Recommendation: Should We Change the Signature to (res, req) => void?

Short Answer: No, keep the Promise support—it's valuable for async code and aligns with Node.js best practices. But improve documentation to clarify its purpose.

• Pros of Keeping void | Promise<void>:

  • Enables natural async/await usage without wrappers.
  • Future-proofs for more complex async integrations (e.g., with ORMs like Prisma or Prisma).
  • Consistent with other Node.js frameworks (e.g., Express middleware can be async).

• Cons and Why It Might Seem Misleading:

  • Users might assume Promise resolution blocks or waits for network I/O.
  • If the library doesn't actually await the Promise in hot paths, it could lead to race conditions (though uWebSockets.js is designed to handle this safely).

• Better Alternatives Without Breaking Changes:

  1. Enhance Documentation: Update the README and JSDoc with explicit examples and warnings. E.g.:

     Handlers may return a Promise to indicate asynchronous completion of your logic.
     The library does not wait for client receipt—use res.end() to send responses.
     Example: See async handler above.
     

     Reference: Add a section in /docs/ or inline in code comments.

  2. Optional Strict Mode: Introduce a config flag (e.g., app.strictSync = true) that throws if a handler returns a Promise, for perf-critical apps.

  3. TypeScript Improvements: Use more precise types, like:

     type Handler = (res: HttpResponse, req: HttpRequest) => void | Promise<void>;
     // With JSDoc: @returns {void|Promise<void>} - For async user logic only; response sending is non-blocking.

• If Changing to Strict void:

  • It would require deprecation warnings first (e.g., log if a Promise is returned).
  • Users could refactor async code to callbacks:

    app.get('/legacy-async', (res, req) => {
      someAsyncOperation().then(data => {
        res.end(JSON.stringify(data));
      }).catch(err => res.end('Error'));
    });

  • But this regresses usability—avoid unless perf data justifies it.

Next Steps for the Issue

• Test It: Reproduce with a benchmark (e.g., using autocannon or wrk) to measure sync vs. async handler perf. If no meaningful difference, emphasize docs.
• Community Input: Since it's open, solicit feedback from users on async usage.
• Related Resources:
  • Official Docs: Check the uWebSockets.js README for handler examples (focus on "HTTP Routing" and "WebSocket Behavior" sections).
  • Source Code: Look at src/App.ts or lib/uWS.js for how handlers are invoked (they use Reflect.apply which handles Promises gracefully).
  • Similar Discussions: Search the issues for "async handler" or "promise"—there may be prior threads on perf implications.

If this doesn't fully address your question or you have more context (e.g., specific code snippets), provide details for deeper analysis!