Skip to Content
Reference@streamsy/serve

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.

FieldDefaultMeaning
port3000The port to bind
hostname127.0.0.1The address to bind
server{}The options of createServer from node:http
gracefulShutdownTimeoutUnsetThe 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.

On this page