Skip to main content

InversifyUwebSocketsHttpAdapter

The uWebSockets.js HTTP adapter implementation. This adapter allows you to use InversifyJS framework with uWebSockets.js, one of the fastest HTTP server implementations available.

Base class documentation

This adapter extends InversifyHttpAdapter. See the base class documentation for information about common methods like applyGlobalMiddleware, useGlobalFilters, applyGlobalGuards, useGlobalInterceptors, and useGlobalPipe.

Installation​

npm install @inversifyjs/http-uwebsockets uWebSockets.js inversify reflect-metadata

Constructor​

constructor(
  container: Container,
  httpAdapterOptions?: UwebSocketsHttpAdapterOptions,
  customApp?: TemplatedApp,
)

Creates a uWebSockets adapter instance.

Parameters​

  • container: The Inversify container that holds controllers, guards, pipes, middleware, interceptors, and filters.
  • httpAdapterOptions (optional): Configuration options for the adapter. See Options below.
  • customApp (optional): A custom uWebSockets.js TemplatedApp instance (created with App() or SSLApp()). If not provided, a default HTTP app is created.

Default Options​

The adapter uses these defaults if not overridden:

{
  logger: true,
}

Methods​

build​

async build(): Promise<TemplatedApp>

Builds and returns the uWebSockets.js application with all configured routes, middleware, and handlers.

Returns: The uWebSockets.js TemplatedApp instance ready to be used with app.listen().

Options​

UwebSocketsHttpAdapterOptions​

type UwebSocketsHttpAdapterOptions = HttpAdapterOptions;

Currently, the uWebSockets adapter uses the base HttpAdapterOptions:

Properties​

  • logger: Set to true to log route mappings on build, or false to disable logging, or provide a custom logger implementing the Logger interface from @inversifyjs/logger. Default: true

Usage Example​

const container: Container = new Container();
// ... bind your controllers, services, etc.

// Create the adapter with options
const adapter: InversifyUwebSocketsHttpAdapter =
  new InversifyUwebSocketsHttpAdapter(container, {
    logger: true,
  });

// Build the uWebSockets application
const app = await adapter.build();

// Start the server
app.listen('0.0.0.0', 3000, (socket) => {
  if (socket !== false) {
    const port: number = us_socket_local_port(socket);
    console.log(`Server listening on port ${String(port)}`);
  } else {
    console.error('Failed to start server');
  }
});

uWebSockets.js-Specific Features​

Extreme Performance​

uWebSockets.js is benchmarked as one of the fastest HTTP server implementations in existence, not just in Node.js. It provides microsecond-level response times and can handle millions of requests with minimal resource usage.

SSL/TLS Support​

You can create an SSL-enabled server by passing a custom SSLApp() instance:

import { SSLApp } from 'uWebSockets.js';

const sslApp = SSLApp({
  key_file_name: 'path/to/key.pem',
  cert_file_name: 'path/to/cert.pem',
});

const adapter = new InversifyUwebSocketsHttpAdapter(
  container,
  { logger: true },
  sslApp,
);

WebSocket Support​

While this adapter focuses on HTTP, uWebSockets.js also provides excellent WebSocket support. You can combine InversifyJS HTTP controllers with native uWebSockets.js WebSocket handlers.

Body Parsing​

Body parsing in uWebSockets.js is handled asynchronously due to the streaming nature of the API. The adapter automatically awaits body parameters decorated with @Body().

Backpressure Handling​

uWebSockets.js requires careful handling of response streams to respect backpressure. The adapter handles this automatically when using @Response() parameter decorators with streams.

Type Parameters​

The adapter is strongly typed with uWebSockets.js types:

InversifyUwebSocketsHttpAdapter extends InversifyHttpAdapter<
  HttpRequest,                  // uWebSockets.js HttpRequest
  HttpResponse,                 // uWebSockets.js HttpResponse
  () => void,                   // Next function
  void,                         // Handler return type
  UwebSocketsHttpAdapterOptions
>

Performance Considerations​

  • uWebSockets.js uses a completely different architecture than Node.js's built-in HTTP module
  • Responses must be sent within the callback scope or corked for optimal performance
  • The adapter handles these details automatically, but custom middleware should be aware of these constraints

See Also​