HandlerOptions

import type { HandlerOptions } from "@shadow-js/dusk/server";

interface HandlerOptions {
  readonly manifest: DuskRuntimeManifest;
  /**
   * The features the handler has: `pages()`, `rpc()`, `isr()`, `dataCache()`, `apiRoutes()`, `streams()`,
   * `images()`, `draftMode()`, each imported from `@shadow-js/dusk/features/<name>`. Absent: none, so a handler
   * carries only the request pipeline. The generated server entry passes all of them. See {@link DuskFeature}.
   */
  readonly features?: readonly DuskFeature[];
  /** `"stream"` (default), `"async"` (wait for all data, one string) or `"string"` (no waiting). */
  readonly mode?: "string" | "async" | "stream";
  readonly middleware?: readonly Middleware[];
  readonly security?: SecurityOptions;
  /** Environment schema, validated at startup. */
  readonly env?: EnvSchema;
  /** Origins allowed to send cross-origin state-changing requests, and absolute redirect targets. */
  readonly trustedOrigins?: readonly string[];
  /** Mount point of the app, for example `/app`. Default `""`. */
  readonly base?: string;
  /** Trailing-slash policy of pages. Default `"never"`. */
  readonly trailingSlash?: "never" | "always" | "preserve";
  /** Development mode. Default: the build constant. Shows error details and relaxes cookie `Secure` on localhost. */
  readonly dev?: boolean;
  /**
   * Where environment variables come from. Default `process.env` when it exists. `false` skips
   * the startup check: the schema is validated on the first request from the host object passed
   * to `fetch(request, env)` (Workers bindings).
   */
  readonly envSource?: Readonly<Record<string, string | undefined>> | false;
  /** Receives every error the handler catches. Default: `console.error`. */
  readonly onError?: (error: unknown, info: ErrorInfo) => void;
  /** Receives configuration warnings. Default: `console.warn`. */
  readonly onWarning?: (message: string) => void;
  /** Document shell options. */
  readonly document?: DocumentOptions;
  /** Use `AsyncLocalStorage` for `getRequestEvent()` when the runtime has it. Default `true`. */
  readonly asyncContext?: boolean;
  /** The ISR cache of pages with `revalidate`: store, bounds and clock. See {@link CacheOptions}. */
  readonly cache?: CacheOptions;
  /** Limits of the stream routes (server-sent events and WebSocket). See {@link StreamOptions}. */
  readonly streams?: StreamOptions;
  /** The image optimizer at `/_dusk/image`. See {@link ImagesOptions}. Absent: local sources are 404. */
  readonly images?: ImagesOptions;
  /** Declarative routing of `dusk.config.ts`: redirects, rewrites, headers and route rules (validated at start). */
  readonly routing?: RoutingConfig;
  /**
   * Runs the global middleware (`middleware`) for a request that names a static file: `public/` files and the build's
   * assets. Default `false`: a file is answered before the middleware, as before, so a file costs no code. With `true`,
   * the middleware runs first: it can refuse the file, redirect it, or set headers and cookies that go out with it (the
   * framing headers stay the server's). The Node server (`serve`, `dusk start`) and the Cloudflare Worker honor it; a
   * platform that answers files from its CDN before any code runs (Vercel, Netlify, a static export) cannot, and the
   * build warns. `dusk dev` answers files through Vite, so the middleware does not run for them there.
   */
  readonly runMiddlewareForStaticFiles?: boolean;
  /** Named cache lifetimes (`cacheLife` profiles), added to the presets. */
  readonly cacheLife?: Readonly<Record<string, CacheLifeProfile>>;
  /** Draft mode: the secret variable and the endpoints. Absent: draft mode is off. */
  readonly draft?: Partial<DraftModeSettings>;
  /**
   * The global error document (`src/routes/_global-error.tsx`): answered, with status 500, when the app itself fails to
   * render above the routes. Needs `pages()`. Absent: the built-in 500 page.
   */
  readonly globalError?: GlobalErrorModule;
  /**
   * The built-in 404 page (answered when no route renders a not-found UI): its document title and whether it asks
   * search engines not to index it. Default `{ title: "Not found", noindex: true }`; `false` keeps the status title
   * (`404 Not Found`) and no robots tag.
   */
  readonly notFoundPage?: { readonly title?: string; readonly noindex?: boolean } | false;
  /** The `instrumentation.ts` module (register, onRequest, onRequestError, tracer). */
  readonly instrumentation?: InstrumentationModule;
  /**
   * The `Server-Timing` header (W3C): `total`, `route`, `loaders` and `render` durations, plus the metrics of
   * `event.timing`. `true` or `false` switches the header; an object sets `header` and the `onTimings` hook. Default:
   * on in development, off in production (the numbers describe your server's internals, so enable it deliberately).
   * A response that already has its own `Server-Timing` is left alone. For a streamed page the header carries the time
   * to the shell; `onTimings` receives the full render time when the stream ends.
   */
  readonly serverTiming?: boolean | ServerTimingOptions;
  /**
   * A request counter (`dusk.server.requests`) and a duration histogram (`http.server.request.duration`, seconds),
   * both by `http.route`, `http.request.method` and `http.response.status_class`. Pass a Meter of the OpenTelemetry
   * Metrics API (`metrics.getMeter("app")`) or any object with `createCounter` and `createHistogram`.
   */
  readonly metrics?: MetricsLike;
  /** Identifies this deployment. A client from another deployment gets 409 DEPLOYMENT_MISMATCH. */
  readonly deploymentId?: string;
  /** The default language of `<html lang>` (the default locale of `i18n`). */
  readonly i18n?: { readonly locales: readonly string[]; readonly defaultLocale: string };
  /** Prefix of hydration keys. Default `"0"`. */
  readonly renderId?: string;
  /** Send `x-dusk-render: <mode>` on pages. Default `false`. */
  readonly renderHeader?: boolean;
  /** Largest hydration payload in bytes; an oversized match is dropped from the payload. Default 2 MiB. */
  readonly maxPayloadBytes?: number;
  /** Limits of the server function endpoint. */
  readonly rpc?: {
    /** Largest GET payload (`?p=`), in characters. Default 4096; larger gives 414. */
    readonly maxGetPayloadChars?: number;
    /** Largest response body in bytes. Default 8 MiB. */
    readonly maxResponseBytes?: number;
    /** Most calls one batch request may carry. Default 25; more gives 413. */
    readonly maxBatchSize?: number;
  };
  /** Path of the health endpoint (always answers 200 `ok`). Default `"/_dusk/health"`; `false` disables. */
  readonly healthPath?: string | false;
}