@ngrok/app-server 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/README.md +652 -77
  2. package/dist/build-id-C6sYO9Yp.js +126 -0
  3. package/dist/build-id-C6sYO9Yp.js.map +1 -0
  4. package/dist/{build-manifest-8NfD1wnO.js → build-manifest-UDNk81Ce.js} +24 -6
  5. package/dist/build-manifest-UDNk81Ce.js.map +1 -0
  6. package/dist/cli.js +45 -25
  7. package/dist/cli.js.map +1 -1
  8. package/dist/client-browser.d.ts +12 -0
  9. package/dist/client-browser.js +3 -0
  10. package/dist/client.d.ts +21 -0
  11. package/dist/client.js +27 -0
  12. package/dist/client.js.map +1 -0
  13. package/dist/compression-7_gToa8R.js +97 -0
  14. package/dist/compression-7_gToa8R.js.map +1 -0
  15. package/dist/create-server-DkTeIJ8L.js +1409 -0
  16. package/dist/create-server-DkTeIJ8L.js.map +1 -0
  17. package/dist/{deno-DNRgzHrk.js → deno-aqhikNMG.js} +2 -2
  18. package/dist/deno-aqhikNMG.js.map +1 -0
  19. package/dist/entry-CM6Ma-Tv.d.ts +626 -0
  20. package/dist/entry-CenmvESk.js +116 -0
  21. package/dist/entry-CenmvESk.js.map +1 -0
  22. package/dist/gzip-Doi4wqjX.js +294 -0
  23. package/dist/gzip-Doi4wqjX.js.map +1 -0
  24. package/dist/header-hook-Vzw9J9BY.js +159 -0
  25. package/dist/header-hook-Vzw9J9BY.js.map +1 -0
  26. package/dist/{index-oSE-tYRW.d.ts → index-Bo5G9LuQ.d.ts} +53 -14
  27. package/dist/index.d.ts +99 -269
  28. package/dist/index.js +47 -59
  29. package/dist/index.js.map +1 -1
  30. package/dist/listen-options-7TaXjyrk.js.map +1 -1
  31. package/dist/{load-entry-C03qqmhr.js → load-entry-CmkdlmDX.js} +8 -4
  32. package/dist/{load-entry-C03qqmhr.js.map → load-entry-CmkdlmDX.js.map} +1 -1
  33. package/dist/log-BP6xXXZl.js +122 -0
  34. package/dist/log-BP6xXXZl.js.map +1 -0
  35. package/dist/node-BFH82eeL.js +333 -0
  36. package/dist/node-BFH82eeL.js.map +1 -0
  37. package/dist/node-tBVQPjQv.js +41 -0
  38. package/dist/node-tBVQPjQv.js.map +1 -0
  39. package/dist/node-vite.d.ts +5 -4
  40. package/dist/node-vite.js +2 -17
  41. package/dist/node.d.ts +23 -4
  42. package/dist/node.js +2 -2
  43. package/dist/react-router-vite.d.ts +4 -3
  44. package/dist/react-router-vite.js +2 -20
  45. package/dist/react-router.d.ts +1 -1
  46. package/dist/react-router.js +8 -7
  47. package/dist/react-router.js.map +1 -1
  48. package/dist/request-context-BtQ87VYb.js +40 -0
  49. package/dist/request-context-BtQ87VYb.js.map +1 -0
  50. package/dist/response-edge-Bc1-C_Cx.js +327 -0
  51. package/dist/response-edge-Bc1-C_Cx.js.map +1 -0
  52. package/dist/response-writer-B7FoJjEE.js +289 -0
  53. package/dist/response-writer-B7FoJjEE.js.map +1 -0
  54. package/dist/script-hashes-hqUk6kG7.js +53 -0
  55. package/dist/script-hashes-hqUk6kG7.js.map +1 -0
  56. package/dist/{serve-Cleo8RMO.js → serve-Cc-ADdhZ.js} +3 -3
  57. package/dist/{serve-Cleo8RMO.js.map → serve-Cc-ADdhZ.js.map} +1 -1
  58. package/dist/stale-build-navigation-PnMLtTF8.js +339 -0
  59. package/dist/stale-build-navigation-PnMLtTF8.js.map +1 -0
  60. package/dist/stale-build-navigation-ypV7Ow4o.d.ts +141 -0
  61. package/dist/{start-CINALHxy.js → start-Cb3kknlF.js} +14 -19
  62. package/dist/start-Cb3kknlF.js.map +1 -0
  63. package/dist/static-files-Beju9riB.js +302 -0
  64. package/dist/static-files-Beju9riB.js.map +1 -0
  65. package/dist/tanstack-start-vite.d.ts +6 -5
  66. package/dist/tanstack-start-vite.js +2 -23
  67. package/dist/tanstack-start.d.ts +19 -2
  68. package/dist/tanstack-start.js +5 -14
  69. package/dist/tanstack-start.js.map +1 -1
  70. package/dist/{tcp-C-9AmFuM.js → tcp-Dd1Mt6sN.js} +6 -5
  71. package/dist/{tcp-C-9AmFuM.js.map → tcp-Dd1Mt6sN.js.map} +1 -1
  72. package/dist/trailing-slash-DX7NB88H.d.ts +36 -0
  73. package/dist/types-DLYxYS6M.d.ts +392 -0
  74. package/dist/vercel-vite.d.ts +35 -0
  75. package/dist/vercel-vite.js +142 -0
  76. package/dist/vercel-vite.js.map +1 -0
  77. package/dist/vercel.d.ts +35 -0
  78. package/dist/vercel.js +89 -0
  79. package/dist/vercel.js.map +1 -0
  80. package/dist/vite-B-GfswoH.js +22 -0
  81. package/dist/vite-B-GfswoH.js.map +1 -0
  82. package/dist/vite-D4hfj3ph.js +19 -0
  83. package/dist/vite-D4hfj3ph.js.map +1 -0
  84. package/dist/vite-DyrhyKEr.js +25 -0
  85. package/dist/vite-DyrhyKEr.js.map +1 -0
  86. package/dist/vite-iioAoxSt.js +752 -0
  87. package/dist/vite-iioAoxSt.js.map +1 -0
  88. package/dist/vite.d.ts +2 -2
  89. package/dist/vite.js +1 -1
  90. package/package.json +25 -4
  91. package/dist/build-manifest-8NfD1wnO.js.map +0 -1
  92. package/dist/deno-DNRgzHrk.js.map +0 -1
  93. package/dist/entry-BkdUub2S.js +0 -638
  94. package/dist/entry-BkdUub2S.js.map +0 -1
  95. package/dist/log-CsjaKM8U.js +0 -59
  96. package/dist/log-CsjaKM8U.js.map +0 -1
  97. package/dist/node-CG7qXuWZ.js +0 -58
  98. package/dist/node-CG7qXuWZ.js.map +0 -1
  99. package/dist/node-YWPGmzAk.js +0 -215
  100. package/dist/node-YWPGmzAk.js.map +0 -1
  101. package/dist/node-ZMowKZDB.js +0 -3
  102. package/dist/node-vite.js.map +0 -1
  103. package/dist/react-router-vite.js.map +0 -1
  104. package/dist/start-CINALHxy.js.map +0 -1
  105. package/dist/tanstack-start-vite.js.map +0 -1
  106. package/dist/types-BfCkS7kQ.d.ts +0 -203
  107. package/dist/vite-mYZ2Y69u.js +0 -144
  108. package/dist/vite-mYZ2Y69u.js.map +0 -1
@@ -0,0 +1,626 @@
1
+ import { a as FrameworkRuntime, c as HostRuntime, d as ListenerBindings, g as Plugin, h as Mode, m as LogSink, r as FetchHandler, t as AppServerEnv, u as Listener, x as SentResponse } from "./types-DLYxYS6M.js";
2
+ import { t as TrailingSlash } from "./trailing-slash-DX7NB88H.js";
3
+ import { Context, Hono, MiddlewareHandler } from "hono";
4
+ /** Options for {@link accessLog}. */
5
+ type AccessLogOptions = {
6
+ /**
7
+ * Replace each query value with `REDACTED`, so a single-use code in a URL
8
+ * never reaches a log.
9
+ * @default true
10
+ */
11
+ redactQuery?: boolean;
12
+ /**
13
+ * More attributes for each request line, such as the app's user ID. It
14
+ * runs when the line goes out, with what went out. Read a response header
15
+ * from `sent.headers`, not from `c.res`, which can lack the changes of the
16
+ * header hooks.
17
+ */
18
+ attributes?: (context: Context<AppServerEnv>, sent: SentResponse) => Readonly<Record<string, unknown>>;
19
+ /**
20
+ * Set `Server-Timing: app;dur=<ms>` on each HTML document: the time until
21
+ * the response headers were ready. The browser's DevTools show it.
22
+ * @default false
23
+ */
24
+ serverTiming?: boolean;
25
+ };
26
+ /**
27
+ * One log line per request, static hits included, with Datadog standard
28
+ * attribute names. The line goes out when the response ends or the client
29
+ * disconnects, so a streamed response logs its full duration and size. It
30
+ * logs the response that leaves the server, after each stage. A listener
31
+ * with an `edge`, such as the node listener, counts the bytes.
32
+ *
33
+ * @example
34
+ * createServer({ plugins: [requestId(), accessLog({ redactQuery: false })] });
35
+ * // {"level":"info","message":"request","http.status_code":200,"network.bytes_written":5120,"duration":1830000,...}
36
+ */
37
+ declare function accessLog({ redactQuery, attributes, serverTiming }?: AccessLogOptions): Plugin;
38
+ /** Options for {@link buildId}. */
39
+ type BuildIdOptions = {
40
+ /** @default "X-Build-Id" */
41
+ header?: string;
42
+ /**
43
+ * The deployed build, such as the image tag. With no value or `""`, the
44
+ * plugin sends the ID that the `appServer` Vite plugin derives from the
45
+ * client build. In development, it then sends no build.
46
+ * @default the `buildId` of `.app-server.json` in the client build
47
+ */
48
+ value?: string | undefined;
49
+ /**
50
+ * More request paths whose responses carry the build in `Server-Timing`,
51
+ * such as the app's proxy routes to its API. A tab then finds a new build
52
+ * in the requests that it already sends. They get no build header, because
53
+ * the header marks the router's own responses. A response that a cache can
54
+ * use again without the server gets no build, so a cached copy never
55
+ * reports an old build. It runs in a header hook, so it can run more than
56
+ * once for one request.
57
+ *
58
+ * @example
59
+ * buildId({ paths: (path) => path.startsWith("/api/") });
60
+ */
61
+ paths?: (path: string) => boolean;
62
+ };
63
+ /**
64
+ * Sets a build ID header on documents and on the framework's data responses,
65
+ * such as React Router `.data` files, so a client can see that a deploy
66
+ * happened under it. Each of them also gets the build as
67
+ * `Server-Timing: build;desc="<value>"`. The `paths` option adds the metric
68
+ * to more routes, such as API proxy routes. The plugin removes the build
69
+ * header and the `build` metric of an upstream API from each other
70
+ * response, so the client reads only this app's build.
71
+ * `staleBuildReactRouter()` and `staleBuildTanStack()` from `@ngrok/app-server/client` read the metric
72
+ * from the document, and from a response that the browser fetches with no
73
+ * script, such as a prefetch.
74
+ *
75
+ * With no `value`, it sends the build ID that the `appServer` Vite plugin
76
+ * derives from the client build. Development and a build with no
77
+ * `.app-server.json` then get no build.
78
+ *
79
+ * @example
80
+ * buildId({ value: process.env.IMAGE_TAG });
81
+ */
82
+ declare function buildId({ header, value: given, paths }?: BuildIdOptions): Plugin;
83
+ /** Options for {@link health}. */
84
+ type HealthOptions = {
85
+ /** @default "/livez" */
86
+ livePath?: string;
87
+ /** @default "/readyz" */
88
+ readyPath?: string;
89
+ /**
90
+ * An app check for readiness, such as a database ping. A `false` or a
91
+ * throw makes the server not ready. When the check starts to fail, one
92
+ * warn line goes to the log, and when it passes again, one info line.
93
+ */
94
+ ready?: () => boolean | Promise<boolean>;
95
+ };
96
+ /**
97
+ * Answers the liveness and readiness probes of a load balancer or
98
+ * Kubernetes. `livePath` always answers 200. `readyPath` answers 200 until
99
+ * the server gets a stop signal, then 503. With `shutdownDelayMs` on
100
+ * `createServer`, the listeners serve on for that time, so the load
101
+ * balancer removes the server before the drain starts.
102
+ *
103
+ * `defaultPlugins()` runs it first, so a probe skips the access log. Its
104
+ * `health` option takes these options, and `false` turns it off.
105
+ *
106
+ * @example
107
+ * createServer({
108
+ * plugins: defaultPlugins({ health: { ready: async () => db.ping() } }),
109
+ * shutdownDelayMs: 5_000,
110
+ * });
111
+ */
112
+ declare function health({ livePath, readyPath, ready }?: HealthOptions): Plugin;
113
+ /** One redirect of a {@link redirects} table. */
114
+ type RedirectRule = {
115
+ /**
116
+ * The old URL path. A `:name` segment matches one path segment, and a `*`
117
+ * last segment matches the rest of the path, or nothing: `/docs/*` also
118
+ * matches `/docs`. A trailing slash does not change the match. Write the
119
+ * path as it is in the URL, percent-encoded.
120
+ */
121
+ from: string;
122
+ /**
123
+ * The new URL: a local path, or an absolute `http` or `https` URL. It can
124
+ * use each `:name` and the `*` of `from`. An absolute URL is
125
+ * percent-encoded as UTF-8.
126
+ */
127
+ to: string;
128
+ /** @default 301 */
129
+ status?: 301 | 308;
130
+ };
131
+ /**
132
+ * Sends a redirect from each old URL path in `rules` to its new URL, with
133
+ * the query string. The first rule that matches wins. An exact path is a
134
+ * map lookup. A rule with `:name` or `*` is a pattern.
135
+ *
136
+ * The rules compile at startup, and a rule that is not valid stops startup.
137
+ * A local target must be a safe local path. An absolute target must keep the
138
+ * origin that its rule names. A request whose values break either check goes
139
+ * on to the next stage, and so does a request that is already at its
140
+ * target. It applies to GET and HEAD only.
141
+ *
142
+ * Put it before `trailingSlash`, so `/old/` gets one redirect to the final
143
+ * URL, and give it the same `trailingSlash` mode. In `never` mode, a local
144
+ * target loses its trailing slash, so `trailingSlash` does not redirect it
145
+ * again. `defaultPlugins({ redirects })` does both.
146
+ *
147
+ * @example
148
+ * redirects([
149
+ * { from: "/blog/:slug", to: "/articles/:slug" },
150
+ * { from: "/docs/*", to: "https://docs.example.com/*", status: 308 },
151
+ * ]);
152
+ */
153
+ declare function redirects(rules: readonly RedirectRule[], { trailingSlash }?: {
154
+ trailingSlash?: TrailingSlash;
155
+ }): Plugin;
156
+ /** The headers that {@link securityHeaders} sets, by name. */
157
+ type SecurityHeaderValues = {
158
+ "X-Content-Type-Options"?: string | false;
159
+ "Referrer-Policy"?: string | false;
160
+ "Cross-Origin-Opener-Policy"?: string | false;
161
+ /** Sent on an HTTPS request only. */
162
+ "Strict-Transport-Security"?: string | false;
163
+ /**
164
+ * A policy that the plugin adds to each response, next to the app's own
165
+ * policy. It has no default.
166
+ */
167
+ "Content-Security-Policy"?: string | false;
168
+ };
169
+ /** Options for {@link securityHeaders}. */
170
+ type SecurityHeadersOptions = {
171
+ /** Values that replace the defaults. `false` turns a header off. */
172
+ headers?: SecurityHeaderValues;
173
+ };
174
+ /**
175
+ * Sets safe default security headers on each response:
176
+ *
177
+ * - `X-Content-Type-Options: nosniff`
178
+ * - `Referrer-Policy: strict-origin-when-cross-origin`
179
+ * - `Cross-Origin-Opener-Policy: same-origin`
180
+ * - `Strict-Transport-Security: max-age=31536000`, on an HTTPS request only
181
+ *
182
+ * A response that has a header keeps its own value. The exception is
183
+ * `Content-Security-Policy`, which has no default: the plugin adds a set
184
+ * value as a second policy, and a browser enforces both.
185
+ * `defaultPlugins()` puts it before the static stages, so it also sees
186
+ * prerendered pages.
187
+ *
188
+ * @example
189
+ * defaultPlugins({
190
+ * securityHeaders: {
191
+ * headers: {
192
+ * "Cross-Origin-Opener-Policy": "same-origin-allow-popups",
193
+ * "Content-Security-Policy": "frame-ancestors 'none'",
194
+ * },
195
+ * },
196
+ * });
197
+ */
198
+ declare function securityHeaders({ headers }?: SecurityHeadersOptions): Plugin;
199
+ /** Options for {@link contentSecurityPolicy}. */
200
+ type ContentSecurityPolicyOptions = {
201
+ /**
202
+ * The `Content-Security-Policy` of an HTML document. `scriptSrc` is the
203
+ * source list that trusts the document's scripts. Put it in `script-src`.
204
+ * `context` is the request, so the policy can change by path. It runs in a
205
+ * header hook, so it can run more than once for one request.
206
+ */
207
+ policy: (scriptSrc: string, context: Context<AppServerEnv>) => string;
208
+ };
209
+ /**
210
+ * Sets the `Content-Security-Policy` from `policy` on each HTML document. The
211
+ * policy trusts the document's scripts, and only them:
212
+ *
213
+ * - A rendered document gets `'nonce-…' 'strict-dynamic'` with a new nonce
214
+ * for each request. The app reads the nonce from `requestContext()` and
215
+ * gives it to the framework's render, so each inline script gets it.
216
+ * - A prerendered document gets `'self'` and the hash of each of its inline
217
+ * scripts, which the Vite plugin records. Its file has one nonce for every
218
+ * visitor, so a nonce protects nothing. Why no `'strict-dynamic'`: a hash,
219
+ * unlike a nonce, does not carry to the imports of an inline module script.
220
+ *
221
+ * The `contentSecurityPolicy` option of `defaultPlugins()` takes these
222
+ * options, and puts the plugin before the static stages, so it sees the
223
+ * prerendered documents. A response that has a `Content-Security-Policy`
224
+ * keeps it.
225
+ *
226
+ * @example
227
+ * defaultPlugins({
228
+ * contentSecurityPolicy: {
229
+ * policy: (scriptSrc) => `script-src ${scriptSrc}; object-src 'none'; base-uri 'none'`,
230
+ * },
231
+ * });
232
+ */
233
+ declare function contentSecurityPolicy({ policy }: ContentSecurityPolicyOptions): Plugin;
234
+ /** Options for {@link requestId}. */
235
+ type RequestIdOptions = {
236
+ /** @default "X-Request-Id" */
237
+ headerName?: string;
238
+ /**
239
+ * Also log the trace IDs as `dd.trace_id` and `dd.span_id`, the lower 64
240
+ * bits in decimal, so Datadog connects each log line to its trace.
241
+ * @default false
242
+ */
243
+ datadogTraceIds?: boolean;
244
+ };
245
+ /**
246
+ * Gives each request an ID: a valid incoming header (up to 255 word
247
+ * characters, `-`, and `=`), else a new UUID. The ID goes on the response, on
248
+ * every log line, and into the framework's context.
249
+ *
250
+ * A valid W3C `traceparent` header adds `trace_id` and `span_id` to each log
251
+ * line of the request.
252
+ *
253
+ * @example
254
+ * const app = createServer({ plugins: [requestId()] });
255
+ * const response = await app.request("/", { headers: { "X-Request-Id": "abc-123" } });
256
+ * response.headers.get("X-Request-Id"); // => "abc-123"
257
+ */
258
+ declare function requestId({ headerName, datadogTraceIds }?: RequestIdOptions): Plugin;
259
+ type StandardIssue = {
260
+ readonly message: string;
261
+ readonly path?: readonly (PropertyKey | {
262
+ readonly key: PropertyKey;
263
+ })[] | undefined;
264
+ };
265
+ type StandardResult<Output> = {
266
+ readonly value: Output;
267
+ readonly issues?: undefined;
268
+ } | {
269
+ readonly issues: readonly StandardIssue[];
270
+ };
271
+ /** A schema that follows the Standard Schema interface, such as a zod object. */
272
+ type StandardSchemaV1<Input = unknown, Output = Input> = {
273
+ readonly "~standard": {
274
+ readonly version: 1;
275
+ readonly vendor: string;
276
+ readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
277
+ readonly types?: {
278
+ readonly input: Input;
279
+ readonly output: Output;
280
+ } | undefined;
281
+ };
282
+ };
283
+ /** The parsed type of a Standard Schema. */
284
+ type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
285
+ /** The `id` of the JSON `<script>` that carries the public values into each HTML document. */
286
+ declare const PUBLIC_ENV_SCRIPT_ID = "app-server-public-env";
287
+ /** Options for {@link runtimeEnv}. */
288
+ type RuntimeEnvOptions = {
289
+ /** @default process.env */
290
+ source?: Readonly<Record<string, string | undefined>>;
291
+ /**
292
+ * Values whose names start with this prefix reach the browser.
293
+ * @default "PUBLIC_"
294
+ */
295
+ publicPrefix?: string;
296
+ };
297
+ /** The plugin that {@link runtimeEnv} returns, with the parsed values. */
298
+ type RuntimeEnv<Values> = Plugin & {
299
+ /** The parsed values. The first read parses, and a bad value throws. */
300
+ readonly values: Values;
301
+ /** The parsed values whose names start with the public prefix. */
302
+ readonly publicValues: Readonly<Record<string, unknown>>;
303
+ };
304
+ /**
305
+ * Validates the environment once, at startup, against a schema. A missing or
306
+ * bad value stops the server with a message that names it. The typed values
307
+ * are on `.values`.
308
+ *
309
+ * The values whose names start with `PUBLIC_` go into each HTML document,
310
+ * prerendered or rendered, as a JSON `<script id="app-server-public-env">`.
311
+ * So one image serves every environment, and a prerendered page never keeps
312
+ * the values of the build. Give it to the `env` option of `defaultPlugins()`,
313
+ * which puts it before the static stages, so it sees the prerendered pages.
314
+ *
315
+ * @example
316
+ * export const env = runtimeEnv(
317
+ * z.object({ PUBLIC_API_URL: z.url(), SESSION_KEY: z.string().min(32) }),
318
+ * );
319
+ * env.values.SESSION_KEY; // => string
320
+ * createServer({ plugins: defaultPlugins({ env }) });
321
+ *
322
+ * // In the browser:
323
+ * const publicEnv = JSON.parse(document.getElementById("app-server-public-env")?.textContent ?? "{}");
324
+ */
325
+ declare function runtimeEnv<Schema extends StandardSchemaV1>(schema: Schema, { source, publicPrefix }?: RuntimeEnvOptions): RuntimeEnv<InferOutput<Schema>>;
326
+ /**
327
+ * Serves the hashed files under `/assets/` with a one-year immutable cache.
328
+ * A missing asset gets a plain 404 with `Cache-Control: no-store`, not a
329
+ * rendered page. In development, the dev server serves the source modules,
330
+ * the HMR client, and the CSS here instead.
331
+ *
332
+ * @example
333
+ * createServer({ plugins: [requestId(), accessLog(), streamingCompress(), assets(), prerendered()] });
334
+ */
335
+ declare function assets(): Plugin;
336
+ /** Options for {@link prerendered}. */
337
+ type PrerenderedOptions = {
338
+ /**
339
+ * Extra headers for a served file, by its URL path. They replace the
340
+ * headers captured at build time.
341
+ */
342
+ headers?: (path: string, context: Context<AppServerEnv>) => Readonly<Record<string, string>> | undefined;
343
+ /**
344
+ * Maps a request path to the URL path of the file to serve, for content
345
+ * negotiation. Return the path unchanged to serve the usual file. The
346
+ * returned path follows the rules of a request path: one URL for each
347
+ * file, no dotfiles, and nothing outside the client build. When the
348
+ * answer depends on a request header, add a `Vary` for it in a plugin.
349
+ */
350
+ rewrite?: (path: string, context: Context<AppServerEnv>) => string;
351
+ /**
352
+ * Serves the markdown twin of a page, such as `/docs/button.md` for
353
+ * `/docs/button`, to a request that {@link prefersMarkdown} accepts. A
354
+ * page has a twin when `twinOf` names a file in the client build. `twinOf`
355
+ * gets the request path and the request's Hono context, the same as
356
+ * `rewrite`. It returns `undefined` for a request with no twin.
357
+ *
358
+ * - A request that prefers markdown gets the twin, with the twin's
359
+ * captured headers. `rewrite` does not run for it.
360
+ * - Each answer for a path with a twin gets `Vary: Accept`: the twin, the
361
+ * prerendered HTML, and the framework's answer. The server adds
362
+ * `Accept` to the `Vary` header and keeps the values in it.
363
+ * - Each answer for a path with a twin, except the twin, gets
364
+ * `Link: <twin>; rel="alternate"; type="text/markdown"`, so a client can
365
+ * find the twin.
366
+ * - A path with no twin gets no `Vary: Accept` and no `Link`, so a request
367
+ * for the twin's own URL gets none.
368
+ * - In development, the client build has no twins. A request that prefers
369
+ * markdown gets the framework's answer for the twin's URL, so an edit
370
+ * shows at once. When the framework knows the paths that the build will
371
+ * prerender, as React Router does, only those twins count. An error, or
372
+ * an answer that is not markdown, gives the HTML.
373
+ * - A plugin after `prerendered` does not see a twin, as it does not see
374
+ * a prerendered file.
375
+ *
376
+ * `true` uses the default `twinOf`: the path with no trailing slash plus
377
+ * `.md`, and `/index.md` for `/`. The returned path follows the rules of a
378
+ * request path.
379
+ *
380
+ * @example
381
+ * prerendered({ markdownTwins: { twinOf: (path) => `/markdown${path}.md` } });
382
+ */
383
+ markdownTwins?: boolean | {
384
+ twinOf: TwinOf;
385
+ };
386
+ /**
387
+ * Sends a request path to the next stage, with no file lookup. Use it for
388
+ * private pages, so the auth check in the app or the framework runs for
389
+ * them. A data request has its own path, such as `/app.data` in React
390
+ * Router.
391
+ *
392
+ * @example
393
+ * prerendered({ skip: (path) => path === "/app" || path.startsWith("/app/") || path.startsWith("/app.") });
394
+ */
395
+ skip?: (path: string) => boolean;
396
+ /**
397
+ * The `Cache-Control` of a served file, by the file's URL path, such as
398
+ * `/about/index.html`. `undefined` sends none. A header that the build
399
+ * captured, and the `headers` option, win over it.
400
+ *
401
+ * The default gives an HTML page, a markdown file, and a data file of the
402
+ * framework `public, max-age=0, must-revalidate`, so a visitor always sees
403
+ * the newest page and its markdown twin, and a 304 keeps it fast. It gives every other file
404
+ * `public, max-age=3600, stale-while-revalidate=86400`.
405
+ *
406
+ * @example
407
+ * prerendered({ cacheControl: (path) => (path.startsWith("/images/") ? "public, max-age=86400" : undefined) });
408
+ */
409
+ cacheControl?: (path: string) => string | undefined;
410
+ };
411
+ /** Maps a request to the URL path of its markdown twin, or `undefined` when it has none. */
412
+ type TwinOf = (path: string, context: Context<AppServerEnv>) => string | undefined;
413
+ /**
414
+ * Serves the client build: prerendered pages at their own URL with a 200,
415
+ * plus every other file in it. It sends no redirect. The `trailingSlash`
416
+ * plugin does. Each response gets
417
+ * the headers its loader sent at build time (the `appServer` Vite plugin
418
+ * captures them), a `Cache-Control` (see `cacheControl`), an ETag, and a 304
419
+ * for a matching `If-None-Match`. A GET with one byte range gets a 206. A path
420
+ * with no file goes on to the framework. In development, only
421
+ * `markdownTwins` runs.
422
+ *
423
+ * At startup, it warns about each prerendered path that has no file.
424
+ *
425
+ * @example
426
+ * prerendered({
427
+ * headers: (path) => (path.startsWith("/api/") ? { "Access-Control-Allow-Origin": "*" } : undefined),
428
+ * });
429
+ */
430
+ declare function prerendered(options?: PrerenderedOptions): Plugin;
431
+ /** A Hono app from {@link createServer}. Add routes to it before you export it. */
432
+ type AppServer = Hono<AppServerEnv>;
433
+ /** A server that listens. */
434
+ type RunningServer = {
435
+ /** The URL of each listener. */
436
+ urls: readonly string[];
437
+ /**
438
+ * Marks the server as not ready, and waits for the shutdown delay. Then it
439
+ * aborts `shutdownSignal()` and runs each plugin's `onShutdown` while the
440
+ * listeners stop and drain open requests. Both stop at the deadline.
441
+ */
442
+ shutdown: () => Promise<void>;
443
+ };
444
+ /** Options for {@link defaultPlugins}. */
445
+ type DefaultPluginsOptions = {
446
+ /**
447
+ * The options of the liveness and readiness probes. `false` turns them
448
+ * off, such as for an app with its own `/livez` route. See {@link health}.
449
+ * @default {}
450
+ */
451
+ health?: HealthOptions | false;
452
+ requestId?: RequestIdOptions;
453
+ accessLog?: AccessLogOptions;
454
+ prerendered?: PrerenderedOptions;
455
+ /**
456
+ * Redirects from old URL paths to new URLs. They run before
457
+ * `trailingSlash`, so an old URL gets one redirect. See {@link redirects}.
458
+ */
459
+ redirects?: readonly RedirectRule[];
460
+ /**
461
+ * How a page URL ends. Set the same mode in the framework's router when it
462
+ * has one, else the redirects loop. See {@link trailingSlash}.
463
+ * @default "never"
464
+ */
465
+ trailingSlash?: TrailingSlash;
466
+ /**
467
+ * The largest request body, in bytes. A larger body gets a 413. `false`
468
+ * turns the limit off. See {@link bodyLimit}.
469
+ * @default 10485760 (10 MiB)
470
+ */
471
+ bodyLimit?: number | false;
472
+ /**
473
+ * The options of the security headers. `false` turns them off. See
474
+ * {@link securityHeaders}.
475
+ */
476
+ securityHeaders?: SecurityHeadersOptions | false;
477
+ /**
478
+ * Sets `X-Robots-Tag: noindex, nofollow` on each response, such as on a
479
+ * preview deploy. See {@link noindex}.
480
+ * @default false
481
+ */
482
+ noindex?: boolean;
483
+ /**
484
+ * The options of the build ID on each document and data response. `false`
485
+ * turns it off. See {@link buildId}.
486
+ * @default {}, with the ID that the `appServer` Vite plugin derives from the client build
487
+ */
488
+ buildId?: BuildIdOptions | false;
489
+ /**
490
+ * The options of the `Content-Security-Policy` of each HTML document. It
491
+ * has no default. See {@link contentSecurityPolicy}.
492
+ */
493
+ contentSecurityPolicy?: ContentSecurityPolicyOptions;
494
+ /**
495
+ * The plugin from `runtimeEnv(schema)`. It writes the public values into
496
+ * each HTML document, prerendered pages included.
497
+ */
498
+ env?: RuntimeEnv<unknown>;
499
+ /**
500
+ * The app's own plugins that see every response, prerendered pages
501
+ * included, such as an auth check. They go after the plugins of the
502
+ * options above and before the static stages.
503
+ */
504
+ beforeStatic?: readonly Plugin[];
505
+ };
506
+ /**
507
+ * The default pipeline, in order: `health`, `requestId`, `accessLog`,
508
+ * `streamingCompress`, `securityHeaders`, `bodyLimit`, `noindex` (when
509
+ * set), `buildId`, `contentSecurityPolicy` (when set), `env` (when set), the
510
+ * `beforeStatic` plugins, `assets`, `redirects` (when the option has rules),
511
+ * `trailingSlash`, `prerendered`, and `privateDocuments`. It is a plain
512
+ * array, so an app can filter it or splice into it.
513
+ *
514
+ * @example
515
+ * createServer({
516
+ * plugins: defaultPlugins({ env, noindex: process.env.PREVIEW === "1", health: { ready: async () => db.ping() } }),
517
+ * });
518
+ */
519
+ declare function defaultPlugins(options?: DefaultPluginsOptions): Plugin[];
520
+ /** Options for {@link createServer}. */
521
+ type CreateServerOptions = {
522
+ /** @default defaultPlugins() */
523
+ plugins?: readonly Plugin[];
524
+ /** @default jsonSink() */
525
+ logger?: LogSink;
526
+ /** @default the host's listeners, such as `[tcp()]` on the node host */
527
+ listeners?: readonly Listener[];
528
+ /**
529
+ * Read the request scheme from `X-Forwarded-Proto`. Set it only behind a
530
+ * proxy that overwrites that header, else a client can spoof it.
531
+ * @default false
532
+ */
533
+ trustForwardedProto?: boolean;
534
+ /**
535
+ * How many proxies in front of the server add the address they got a
536
+ * request from to `X-Forwarded-For`. With N, the client address is the
537
+ * Nth address from the right of that header. A header with fewer
538
+ * addresses gives its leftmost address. Set it only to the number of
539
+ * proxies that you run, else a client can spoof its address.
540
+ * @default 0, the address of the socket
541
+ */
542
+ trustedProxyHops?: number;
543
+ /**
544
+ * How long the listeners serve on after a stop signal, before the drain
545
+ * starts. During this time, the `health` plugin's readiness probe answers
546
+ * 503, so a load balancer stops sending requests first. The drain deadline
547
+ * starts after the delay.
548
+ * @default 0
549
+ */
550
+ shutdownDelayMs?: number;
551
+ /**
552
+ * How long open requests get to finish after the drain starts.
553
+ * @default 10000
554
+ */
555
+ shutdownDeadlineMs?: number;
556
+ };
557
+ /**
558
+ * Builds an app server: a Hono app that runs the plugins in list order, then
559
+ * the app's own routes, then the framework. It does not listen; the
560
+ * `app-server` CLI starts it.
561
+ *
562
+ * Two plugins of one option of `defaultPlugins()`, such as two `buildId()`,
563
+ * stop startup.
564
+ *
565
+ * @example
566
+ * // server.ts
567
+ * const app = createServer({ logger: slogSink, plugins: defaultPlugins({ env }) });
568
+ * app.get("/api/status", (c) => c.json({ ok: true }));
569
+ * export default app;
570
+ */
571
+ declare function createServer({ plugins, logger, listeners, trustForwardedProto, trustedProxyHops, shutdownDelayMs, shutdownDeadlineMs }?: CreateServerOptions): AppServer;
572
+ /** The version of the contract between the CLI and the `appServer` export of a build. */
573
+ declare const ENTRY_PROTOCOL = 2;
574
+ /**
575
+ * What a server build exports as `appServer`. The CLI calls it, so the copy
576
+ * of this package in the build runs the server, and the CLI's copy runs
577
+ * nothing.
578
+ */
579
+ type AppServerEntry = {
580
+ /** The CLI refuses an entry with another version. */
581
+ protocol: typeof ENTRY_PROTOCOL;
582
+ /** The app. Two entries with the same app share its plugins. */
583
+ app: AppServer;
584
+ /**
585
+ * Production: runs each plugin's `setup` and listens. When the host's
586
+ * lifecycle stops, such as on `SIGTERM`, it shuts down.
587
+ */
588
+ start: () => Promise<void>;
589
+ /**
590
+ * Production, for a serverless host: answers one request, and does not
591
+ * listen. The first call runs each plugin's `setup`.
592
+ */
593
+ fetch: FetchHandler;
594
+ /** Development: answers one request with the dev server inside the pipeline. */
595
+ fetchDev: (request: Request, bindings: ListenerBindings, devServer: MiddlewareHandler<AppServerEnv>) => Promise<Response>;
596
+ /** Runs each plugin's `onShutdown` once, up to the shutdown deadline. */
597
+ stopPlugins: () => Promise<void>;
598
+ /** Aborts `shutdownSignal()` of this copy of the package. */
599
+ abortShutdownSignal: () => void;
600
+ };
601
+ /** Options for {@link createEntry}. */
602
+ type CreateEntryOptions = {
603
+ /** The app from `createServer`. */
604
+ app: AppServer;
605
+ /** The run side of the host adapter, such as `host` from `@ngrok/app-server/node`. */
606
+ host: HostRuntime;
607
+ /** Makes the run side of the framework adapter for a mode. */
608
+ framework: (mode: Mode) => FrameworkRuntime;
609
+ /**
610
+ * The client build, as a file path or a `file:` URL. The entry that the
611
+ * Vite plugin generates sets it.
612
+ * @default the framework's `clientDirectory`
613
+ */
614
+ clientDirectory?: string;
615
+ };
616
+ /**
617
+ * The `appServer` export of a server build: an app from `createServer`, the
618
+ * host, and the framework adapter for each mode. The `appServer` Vite plugin
619
+ * generates this export. Call this for a build without the plugin.
620
+ *
621
+ * @example
622
+ * export const appServer = createEntry({ app, host, framework: (mode) => runtime(build, { mode }) });
623
+ */
624
+ declare function createEntry({ app, host, framework, clientDirectory }: CreateEntryOptions): AppServerEntry;
625
+ export { BuildIdOptions as A, SecurityHeadersOptions as C, redirects as D, RedirectRule as E, AccessLogOptions as M, accessLog as N, HealthOptions as O, SecurityHeaderValues as S, securityHeaders as T, StandardSchemaV1 as _, CreateServerOptions as a, requestId as b, createServer as c, assets as d, prerendered as f, RuntimeEnvOptions as g, RuntimeEnv as h, AppServer as i, buildId as j, health as k, defaultPlugins as l, PUBLIC_ENV_SCRIPT_ID as m, CreateEntryOptions as n, DefaultPluginsOptions as o, InferOutput as p, createEntry as r, RunningServer as s, AppServerEntry as t, PrerenderedOptions as u, runtimeEnv as v, contentSecurityPolicy as w, ContentSecurityPolicyOptions as x, RequestIdOptions as y };
626
+ //# sourceMappingURL=entry-CM6Ma-Tv.d.ts.map