Node
Reference for the host exports in @streamsy/serve/node. They provide a scoped Node HTTP listener.
import * as Node from "@streamsy/serve/node";
import type { Duration, Effect, Layer } from "effect";
import type { Etag, HttpPlatform, HttpServer, HttpServerError } from "effect/http";
import type { FileSystem, Path, Stdio, Terminal } from "effect";
import type { ChildProcessSpawner } from "effect/process";
import type { ServerOptions } from "node:http";Node.listener is the HTTP listener Layer of a Streamsy host on Node. Provide it to Serve.layer. See Run a process server and Clean shutdown.
Listener
Node.listener
declare function listener(
options?: Node.ListenerOptions,
): Layer.Layer<
| Etag.Generator
| HttpPlatform.HttpPlatform
| HttpServer.HttpServer
| ChildProcessSpawner.ChildProcessSpawner
| FileSystem.FileSystem
| Path.Path
| Stdio.Stdio
| Terminal.Terminal,
HttpServerError.ServeError,
never
>;
Node.listener binds the port when its Layer builds, and closes the server when the scope of the Layer closes. When the bind fails, the Layer fails with HttpServerError.ServeError. The Layer requires no services.
The listener binds port 3000 on 127.0.0.1 unless the options set others. Without gracefulShutdownTimeout, the listener turns off the preemptive shutdown of the platform server, and its scope finalizer waits for in-flight requests to end. With gracefulShutdownTimeout, the platform server stops waiting after that time.
Node binds the port before the routes serve, and it never answers a request that arrives while no route handler is attached. So before the routes attach and after they detach, the listener answers each request with 503, Retry-After: 1, and Connection: close. A client that retries reaches the routes once they serve.
Some protocol responses carry a web Response as a raw body, which the Node server cannot write. The listener converts such a body into a stream body with the same status and headers.
Options
Node.ListenerOptions
interface ListenerOptions {
readonly port?: number;
readonly hostname?: string;
readonly server?: ServerOptions;
readonly gracefulShutdownTimeout?: Duration.Input;
}
Node.ListenerOptions holds the options of Node.listener.
| Field | Default | Meaning |
|---|---|---|
port | 3000 | The port to bind |
hostname | 127.0.0.1 | The address to bind |
server | {} | The options of createServer from node:http |
gracefulShutdownTimeout | Unset | The longest wait for in-flight requests during shutdown |
Node's requestTimeout bounds the time to receive a request, not the time to answer it. So the default server options keep a parked long poll and an open SSE body alive.
Defaults
Node.DEFAULT_PORT
declare const DEFAULT_PORT: 3000;
Node.DEFAULT_PORT is the default port of Node.listener: 3000.
Node.DEFAULT_HOSTNAME
declare const DEFAULT_HOSTNAME: "127.0.0.1";
Node.DEFAULT_HOSTNAME is the default bind address of Node.listener: 127.0.0.1.