ServeOptions

import type { ServeOptions } from "@shadow-js/dusk/node";

interface ServeOptions {
  /** Port to listen on; `0` picks a free one. Default 3000. */
  readonly port?: number;
  /** Interface to listen on. Default `"127.0.0.1"`; use `"0.0.0.0"` in a container. */
  readonly host?: string;
  /** Serve files of a directory before the handler (the client build output). */
  readonly static?: false | StaticOptions;
  /**
   * Compress responses (brotli, zstd where `node:zlib` has it, gzip). On by default; `false` leaves it to a proxy.
   * See {@link CompressOptions} for the level, the types and the `filter` that skips responses that reflect secrets.
   */
  readonly compress?: false | CompressOptions;
  /**
   * Send `103 Early Hints` for a page request: the entry script, the stylesheets and the matched routes' preloads go
   * out as `Link` headers (at most 8, same-origin only) before the page's data loads, so the browser starts fetching
   * them while the server renders. The final response carries the same `Link` header either way. HTTP/1.1 clients
   * only. Default `true`.
   */
  readonly earlyHints?: boolean;
  /** Believe `X-Forwarded-Proto` / `X-Forwarded-Host`. Only behind a proxy you control. Default `false`. */
  readonly trustProxy?: boolean;
  /** How long a shutdown waits for requests in flight before closing connections. Default 10 000. */
  readonly gracefulShutdownMs?: number;
  /** Signals that start a graceful shutdown. Default `["SIGTERM", "SIGINT"]`; `false` registers none. */
  readonly shutdownSignals?: false | readonly string[];
  /** Where signal listeners are registered. Default: `process`. */
  readonly signalTarget?: SignalTarget;
  /** After a signal-triggered shutdown, call `exit(0)`. Default `true`. */
  readonly exitOnSignal?: boolean;
  /** Called with the exit code after a signal-triggered shutdown. Default: `process.exit`. */
  readonly exit?: (code: number) => void;
  /**
   * Time to receive the request headers, in milliseconds. A deadline from the first byte of the request, not an
   * idle timer, so a client that sends one header line every second (slowloris) is closed with 408 all the same.
   * Default 30 000; `0` turns it off.
   */
  readonly headersTimeoutMs?: number;
  /**
   * Time to receive the whole request, headers and body, in milliseconds. A body that stalls or trickles is
   * closed with 408 and aborts the handler's `request.signal`. Raise it for routes that accept large uploads
   * over slow links. Default 120 000; `0` turns it off.
   */
  readonly requestTimeoutMs?: number;
  /** Idle time before a keep-alive connection is closed, in milliseconds. Default 5 000; `0` turns it off. */
  readonly keepAliveTimeoutMs?: number;
  /**
   * Most sockets open at once (counting upgraded WebSockets). A connection above the cap is closed before a byte
   * is read; the count is `ServerHandle.droppedConnections`. Default 10 000; `0` turns the cap off.
   */
  readonly maxConnections?: number;
  /**
   * Most requests one keep-alive socket may carry. The last one is answered with `Connection: close`, and a
   * request pipelined beyond the limit gets 503. Default 1 000; `0` turns the limit off.
   */
  readonly maxRequestsPerSocket?: number;
  /**
   * How long a response may make no progress, in milliseconds: a client that stops reading a large or streamed
   * response (its socket has bytes waiting and nothing is written or read for this long) is disconnected, which
   * cancels the response body. A handler that is merely slow to produce data is not affected, and neither is an
   * upgraded WebSocket. Default 60 000; `0` turns it off.
   */
  readonly writeTimeoutMs?: number;
  /** Largest request header block in bytes. Default 16 384. */
  readonly maxHeaderBytes?: number;
  /**
   * Run the server in several processes that share the port (`node:cluster`). A whole number from 1, or `"auto"`: one per
   * available core, at most 16. Absent or 1: one process, as before. With more than one, the process that calls `serve`
   * becomes a primary that forks the workers (each runs this same program and so calls `serve` too), replaces a worker that
   * dies, replaces them all on `SIGUSR2` without a gap, and stops them gracefully on `SIGTERM`/`SIGINT`. It resolves once
   * every worker listens, with a handle whose `role` is `"primary"` and whose `pool` controls the workers; a worker gets a handle with `role` `"worker"`.
   * Entries of in-memory stores are per worker: see the "Using every core" section of the deploy guide.
   */
  readonly workers?: number | "auto";
  /** How the primary supervises the workers: restart delays, the crash-loop breaker, the restart signal. See {@link SuperviseOptions}. */
  readonly supervise?: SuperviseOptions;
  /** Serve https with these TLS options instead of http. */
  readonly tls?: HttpsServerOptions;
  /** Receives failures that cannot be sent to the client (a body that broke mid-stream). Default: `console.error`. */
  readonly onError?: (error: unknown) => void;
}