@chojs/web/serve
Keep the server handle returned by serve. Its port and close operation belong to the listener, while the application owns its providers. Start and drain a network listener · Browse all packages
ChoWebServer
A server started by serve.
export type ChoWebServer = {
readonly runtime: EngineType;
readonly port: number;
readonly hostname: string;
close(): Promise<void>;
};runtime The runtime the server runs on.
port The port the server listens on: the real one, when 0 was asked.
hostname The host name or address the server listens on.
Usage
const server: ChoWebServer = await serve(app.handler, { port: 0 });
console.log(server.port);
await server.close();ServeHandler
A fetch-style request handler: what serve serves.
export type ServeHandler = (req: Request) => Response | Promise<Response>;Usage
const echo: ServeHandler = async (req) =>
Response.json({
method: req.method,
url: req.url,
token: req.headers.get("x-token"),
accept: req.headers.get("accept"),
body: req.body === null ? null : await req.text(),
});ServeOptions
The options of serve.
export type ServeOptions = SocketOptions & {
port?: number;
hostname?: string;
signal?: AbortSignal;
closeTimeout?: number;
};port The port to listen on. 0 picks a free port. Default: 3000.
hostname The host name or address to listen on. Default: the default of the runtime's server, which listens on every network interface.
signal Closes the server when it is aborted. Default: none.
closeTimeout How long closing the server waits for the requests in flight, in milliseconds, before it cuts their connections; 0 cuts them at once. Default: none: it waits for every request to end, however long that takes, and for ever for a response that has no end, such as a stream of server-sent events that is still open.
Usage
const server = await serve(app.handler, { port: 8082, closeTimeout: 2000 });serve
Serve a fetch-style request handler on the server of the current runtime.
| Runtime | Server |
|---|---|
| Deno | Deno.serve (needs --allow-net) |
| Bun | Bun.serve |
| Node.js | node:http, bridged to Request / Response |
On Node.js a handler that rejects is logged with console.error and answered with 500; on Deno and Bun the runtime's server does the same.
Closing the server waits for the requests in flight. A response with no end, such as an open stream of server-sent events, would hold it for ever: the closeTimeout option cuts what is still in flight after a grace period.
export function serve(app: ServeHandler | ServeApp, options?: ServeOptions): Promise<ChoWebServer>;Usage
import { ChoWeb } from "@chojs/web";
import { serve } from "@chojs/web/serve";
const app = await ChoWeb.create(AppModule);
const server = await serve(app.handler, { port: 3000 });
console.log(`listening on http://localhost:${server.port}`);Closing
const server = await serve(app.handler);
// ...
await server.close(); // stop the server, then release the application
await app.close();Closing with open streams
// Requests get 10 seconds to end; what is still open then is cut.
const server = await serve(app.handler, { closeTimeout: 10_000 });serve_node
Serve a handler on the node:http server. It is the Node.js part of serve; it also runs on the runtimes that have node:http.
export function serve_node(handler: ServeHandler, port: number, hostname?: string, close_timeout?: number, on_upgrade?: NodeUpgradeListener, cut?: () => void): Promise<ChoWebServer>;Usage
const server = await serve_node(app.handler, 3000, "127.0.0.1");
// During shutdown
await server.close();serve_on
Serve a handler on the server of a given runtime (see serve).
export function serve_on(runtime: EngineType, app: ServeHandler | ServeApp, options?: ServeOptions): Promise<ChoWebServer>;Usage
const server = await serve_on("deno", app.handler, { port: 3000 });
// During shutdown
await server.close();Also exported here
These declarations share their implementation with another entry point. Each link opens the full declaration.
ServeApp
An application supplies a Fetch handler and an optional upgrade(req) function. Pass the whole application when hosting sockets.
const hosted: ServeApp = app;
const server = await serve(hosted, { port: 3000 });SocketOptions
Set maxPayload in bytes to limit incoming WebSocket messages on Node.js and Bun. The default is 1 MiB.
const limits: SocketOptions = { maxPayload: 64 * 1024 };
await serve(app, { ...limits, port: 3000 });bunOptions
BunOptions
bunOptions(app, options?) returns the fetch handler and the websocket callbacks Bun needs when creating a listener.
import { bunOptions, type BunOptions } from "@chojs/web/serve";
const handlers: BunOptions = bunOptions(app);
Bun.serve({ ...handlers, port: 3000 });nodeUpgrade
NodeUpgradeListener
nodeUpgrade(app, options?) creates the listener for the Node HTTP server's upgrade event. Keep the existing server's ordinary HTTP request handling in place.
import { nodeUpgrade, type NodeUpgradeListener } from "@chojs/web/serve";
const onUpgrade: NodeUpgradeListener = nodeUpgrade(app, { maxPayload: 65536 });
server.on("upgrade", onUpgrade);