@fluojs/platform-nodejs

Raw Node.js HTTP adapter package for the fluo runtime.

Table of Contents

• Installation
• When to Use
• Quick Start
• Common Patterns
• Behavioral Contracts
• Conformance Coverage
• Public API Overview
• Related Packages
• Example Sources

Installation

npm install @fluojs/platform-nodejs

When to Use

Use this package when you want to run a fluo application directly on the Node.js built-in http or https modules without the overhead of an intermediate framework like Express or Fastify. It is ideal for minimal footprints, custom low-level optimizations, or environments where standard Node APIs are preferred.

Quick Start

import { createNodejsAdapter } from '@fluojs/platform-nodejs';
import { fluoFactory } from '@fluojs/runtime';
import { AppModule } from './app.module';

const app = await fluoFactory.create(AppModule, {
  adapter: createNodejsAdapter({ port: 3000 }),
});

await app.listen();

Common Patterns

Customizing Server Options

The adapter exposes the documented Node.js transport options: host/port binding, HTTPS configuration, request body limits, raw-body preservation, listen retry settings, and shutdown drain bounds.

const adapter = createNodejsAdapter({
  port: 443,
  https: {
    key: fs.readFileSync('key.pem'),
    cert: fs.readFileSync('cert.pem'),
  },
  maxBodySize: 1_048_576,
});

maxBodySize accepts a byte count number. It is enforced while the raw Node request body is still streaming, and the same limit becomes the default total multipart payload cap unless you override multipart.maxTotalSize during bootstrap.

createNodejsAdapter() defaults to port 3000, ignores process.env.PORT, and throws when port, maxBodySize, retryDelayMs, retryLimit, or adapter-level shutdownTimeoutMs are invalid. The default request body cap is 1 MiB.

Direct Application Execution

You can use runNodejsApplication for a zero-boilerplate startup that includes graceful shutdown and logging.

When signal-driven shutdown exceeds the run-helper forceExitTimeoutMs or fails, the helper logs the condition and sets process.exitCode, but leaves final process termination to the host process owner. Use adapter-level shutdownTimeoutMs for connection drain bounds and run-helper forceExitTimeoutMs for signal handler completion bounds.

bootstrapNodejsApplication(...) and runNodejsApplication(...) use the framework console logger by default. Pass logger when a host or portability test needs startup/shutdown diagnostics captured through an injected ApplicationLogger.

import { runNodejsApplication } from '@fluojs/platform-nodejs';
import { AppModule } from './app.module';

await runNodejsApplication(AppModule, {
  port: 3000,
  globalPrefix: 'api',
  shutdownSignals: ['SIGINT', 'SIGTERM'],
});

Use bootstrapNodejsApplication(...) when you want to create the application without starting the listener:

const app = await bootstrapNodejsApplication(AppModule, { port: 3000 });
await app.listen();

Behavioral Contracts

• createNodejsAdapter(options) is the adapter-first entrypoint for running fluo directly on Node's built-in http or https server primitives.
• maxBodySize accepts a non-negative integer byte count, is enforced while raw Node request bytes are still streaming, and becomes the default multipart total-size cap unless multipart.maxTotalSize is explicitly provided through the bootstrap/run helpers.
• The raw Node adapter normalizes mixed-case JSON and multipart content-type values, returns 413 when request bodies exceed maxBodySize, propagates x-request-id with x-correlation-id fallback into the request context and error responses, and exposes a server-backed realtime capability through getServer() / getRealtimeCapability().
• bootstrapNodejsApplication(module, options) creates an application with the raw Node adapter but does not start listening, so the caller owns the subsequent app.listen() and app.close() lifecycle.
• runNodejsApplication(module, options) bootstraps, starts, and wires graceful shutdown. Listen retries honor retryLimit/retryDelayMs, shutdown closes idle keep-alive connections before bounded drain, and when signal-driven shutdown times out or fails it logs the condition and sets process.exitCode; final process termination remains owned by the host process.
• Advanced compression and shutdown utility functions remain on @fluojs/runtime/node or internal runtime seams rather than this primary platform startup surface.

Conformance Coverage

packages/platform-nodejs/src/index.test.ts is the package-local regression target for the documented Node.js contract. It runs the shared createHttpAdapterPortabilityHarness(...) checks for malformed cookie preservation, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body exclusion, multipart total-size defaults, SSE framing, response stream drain settlement, host and HTTPS startup logging, and shutdown signal listener cleanup.

The same file also covers the package-specific public surface, type aliases, adapter-first startup, lifecycle option validation, listen retry behavior, idle keep-alive shutdown, maxBodySize failures, mixed-case JSON and multipart content-type parsing, x-correlation-id request ID fallback, and server-backed realtime capability exposure. Keep README example pointers aligned with that test file and the Node.js chapter examples below when changing startup behavior.

Public API Overview

• createNodejsAdapter(options): Primary factory for the raw Node.js HTTP adapter.
• bootstrapNodejsApplication(module, options): Creates an application instance without starting the listener.
• runNodejsApplication(module, options): Bootstraps and starts the application with lifecycle management.
• BootstrapNodejsApplicationOptions: Options for bootstrap-only Node.js application creation.
• NodejsAdapterOptions: Transport-level options for createNodejsAdapter(...), including port, host, https, maxBodySize, retry settings, raw body preservation, and shutdown timeout.
• NodejsApplicationSignal: Supported signal names for runNodejsApplication(...) shutdown registration.
• NodejsHttpApplicationAdapter: Type-only alias describing the adapter instances returned by createNodejsAdapter(...), while preserving the public adapter surface exported from @fluojs/runtime/node.
• RunNodejsApplicationOptions: Options for one-call bootstrap, listen, and graceful shutdown wiring.

Related Packages

• @fluojs/runtime: The core runtime facade.
• @fluojs/websockets: Real-time gateway support.
• @fluojs/http: Shared HTTP abstractions and decorators.

Example Sources

• packages/platform-nodejs/src/index.test.ts
• book/intermediate/ch21-express-node.md