@ngrok/app-server 0.2.0 → 0.3.0
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.
- package/README.md +610 -76
- package/dist/build-id-C6sYO9Yp.js +126 -0
- package/dist/build-id-C6sYO9Yp.js.map +1 -0
- package/dist/{build-manifest-8NfD1wnO.js → build-manifest-UDNk81Ce.js} +24 -6
- package/dist/build-manifest-UDNk81Ce.js.map +1 -0
- package/dist/cli.js +45 -25
- package/dist/cli.js.map +1 -1
- package/dist/client.d.ts +141 -0
- package/dist/client.js +326 -0
- package/dist/client.js.map +1 -0
- package/dist/compression-7_gToa8R.js +97 -0
- package/dist/compression-7_gToa8R.js.map +1 -0
- package/dist/create-server-iE1-s6Bi.js +1409 -0
- package/dist/create-server-iE1-s6Bi.js.map +1 -0
- package/dist/{deno-DNRgzHrk.js → deno-aqhikNMG.js} +2 -2
- package/dist/deno-aqhikNMG.js.map +1 -0
- package/dist/entry-DZ3qo7qF.js +116 -0
- package/dist/entry-DZ3qo7qF.js.map +1 -0
- package/dist/entry-DmJEqVfd.d.ts +622 -0
- package/dist/gzip-Doi4wqjX.js +294 -0
- package/dist/gzip-Doi4wqjX.js.map +1 -0
- package/dist/header-hook-Vzw9J9BY.js +159 -0
- package/dist/header-hook-Vzw9J9BY.js.map +1 -0
- package/dist/{index-oSE-tYRW.d.ts → index-Bo5G9LuQ.d.ts} +53 -14
- package/dist/index.d.ts +99 -269
- package/dist/index.js +47 -59
- package/dist/index.js.map +1 -1
- package/dist/listen-options-7TaXjyrk.js.map +1 -1
- package/dist/{load-entry-C03qqmhr.js → load-entry-AfYS_zS9.js} +8 -4
- package/dist/{load-entry-C03qqmhr.js.map → load-entry-AfYS_zS9.js.map} +1 -1
- package/dist/log-BP6xXXZl.js +122 -0
- package/dist/log-BP6xXXZl.js.map +1 -0
- package/dist/node-BFH82eeL.js +333 -0
- package/dist/node-BFH82eeL.js.map +1 -0
- package/dist/node-tBVQPjQv.js +41 -0
- package/dist/node-tBVQPjQv.js.map +1 -0
- package/dist/node-vite.d.ts +5 -4
- package/dist/node-vite.js +2 -17
- package/dist/node.d.ts +23 -4
- package/dist/node.js +2 -2
- package/dist/react-router-vite.d.ts +4 -3
- package/dist/react-router-vite.js +2 -20
- package/dist/react-router.d.ts +1 -1
- package/dist/react-router.js +8 -7
- package/dist/react-router.js.map +1 -1
- package/dist/request-context-BtQ87VYb.js +40 -0
- package/dist/request-context-BtQ87VYb.js.map +1 -0
- package/dist/response-edge-Bc1-C_Cx.js +327 -0
- package/dist/response-edge-Bc1-C_Cx.js.map +1 -0
- package/dist/response-writer-B7FoJjEE.js +289 -0
- package/dist/response-writer-B7FoJjEE.js.map +1 -0
- package/dist/script-hashes-hqUk6kG7.js +53 -0
- package/dist/script-hashes-hqUk6kG7.js.map +1 -0
- package/dist/{serve-Cleo8RMO.js → serve-CDNgThjk.js} +3 -3
- package/dist/{serve-Cleo8RMO.js.map → serve-CDNgThjk.js.map} +1 -1
- package/dist/{start-CINALHxy.js → start-TLIprD74.js} +14 -19
- package/dist/start-TLIprD74.js.map +1 -0
- package/dist/static-files-Beju9riB.js +302 -0
- package/dist/static-files-Beju9riB.js.map +1 -0
- package/dist/tanstack-start-vite.d.ts +6 -5
- package/dist/tanstack-start-vite.js +2 -23
- package/dist/tanstack-start.d.ts +19 -2
- package/dist/tanstack-start.js +5 -14
- package/dist/tanstack-start.js.map +1 -1
- package/dist/{tcp-C-9AmFuM.js → tcp-Dd1Mt6sN.js} +6 -5
- package/dist/{tcp-C-9AmFuM.js.map → tcp-Dd1Mt6sN.js.map} +1 -1
- package/dist/trailing-slash-DX7NB88H.d.ts +36 -0
- package/dist/types-DLYxYS6M.d.ts +392 -0
- package/dist/vercel-vite.d.ts +35 -0
- package/dist/vercel-vite.js +142 -0
- package/dist/vercel-vite.js.map +1 -0
- package/dist/vercel.d.ts +35 -0
- package/dist/vercel.js +89 -0
- package/dist/vercel.js.map +1 -0
- package/dist/vite-B-GfswoH.js +22 -0
- package/dist/vite-B-GfswoH.js.map +1 -0
- package/dist/vite-D4hfj3ph.js +19 -0
- package/dist/vite-D4hfj3ph.js.map +1 -0
- package/dist/vite-DyrhyKEr.js +25 -0
- package/dist/vite-DyrhyKEr.js.map +1 -0
- package/dist/vite-iioAoxSt.js +752 -0
- package/dist/vite-iioAoxSt.js.map +1 -0
- package/dist/vite.d.ts +2 -2
- package/dist/vite.js +1 -1
- package/package.json +24 -4
- package/dist/build-manifest-8NfD1wnO.js.map +0 -1
- package/dist/deno-DNRgzHrk.js.map +0 -1
- package/dist/entry-BkdUub2S.js +0 -638
- package/dist/entry-BkdUub2S.js.map +0 -1
- package/dist/log-CsjaKM8U.js +0 -59
- package/dist/log-CsjaKM8U.js.map +0 -1
- package/dist/node-CG7qXuWZ.js +0 -58
- package/dist/node-CG7qXuWZ.js.map +0 -1
- package/dist/node-YWPGmzAk.js +0 -215
- package/dist/node-YWPGmzAk.js.map +0 -1
- package/dist/node-ZMowKZDB.js +0 -3
- package/dist/node-vite.js.map +0 -1
- package/dist/react-router-vite.js.map +0 -1
- package/dist/start-CINALHxy.js.map +0 -1
- package/dist/tanstack-start-vite.js.map +0 -1
- package/dist/types-BfCkS7kQ.d.ts +0 -203
- package/dist/vite-mYZ2Y69u.js +0 -144
- package/dist/vite-mYZ2Y69u.js.map +0 -1
|
@@ -0,0 +1,622 @@
|
|
|
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.
|
|
355
|
+
*
|
|
356
|
+
* - A request that prefers markdown gets the twin, with the twin's
|
|
357
|
+
* captured headers. `rewrite` does not run for it.
|
|
358
|
+
* - Each answer for a path with a twin gets `Vary: Accept`: the twin, the
|
|
359
|
+
* prerendered HTML, and the framework's answer. The server adds
|
|
360
|
+
* `Accept` to the `Vary` header and keeps the values in it.
|
|
361
|
+
* - Each answer for a path with a twin, except the twin, gets
|
|
362
|
+
* `Link: <twin>; rel="alternate"; type="text/markdown"`, so a client can
|
|
363
|
+
* find the twin.
|
|
364
|
+
* - A path with no twin gets no `Vary: Accept` and no `Link`, so a request
|
|
365
|
+
* for the twin's own URL gets none.
|
|
366
|
+
* - In development, the client build has no twins. A request that prefers
|
|
367
|
+
* markdown gets the framework's answer for the twin's URL, so an edit
|
|
368
|
+
* shows at once. When the framework knows the paths that the build will
|
|
369
|
+
* prerender, as React Router does, only those twins count. An error, or
|
|
370
|
+
* an answer that is not markdown, gives the HTML.
|
|
371
|
+
* - A plugin after `prerendered` does not see a twin, as it does not see
|
|
372
|
+
* a prerendered file.
|
|
373
|
+
*
|
|
374
|
+
* `true` uses the default `twinOf`: the path with no trailing slash plus
|
|
375
|
+
* `.md`, and `/index.md` for `/`. The returned path follows the rules of a
|
|
376
|
+
* request path.
|
|
377
|
+
*
|
|
378
|
+
* @example
|
|
379
|
+
* prerendered({ markdownTwins: { twinOf: (path) => `/markdown${path}.md` } });
|
|
380
|
+
*/
|
|
381
|
+
markdownTwins?: boolean | {
|
|
382
|
+
twinOf: (path: string) => string | undefined;
|
|
383
|
+
};
|
|
384
|
+
/**
|
|
385
|
+
* Sends a request path to the next stage, with no file lookup. Use it for
|
|
386
|
+
* private pages, so the auth check in the app or the framework runs for
|
|
387
|
+
* them. A data request has its own path, such as `/app.data` in React
|
|
388
|
+
* Router.
|
|
389
|
+
*
|
|
390
|
+
* @example
|
|
391
|
+
* prerendered({ skip: (path) => path === "/app" || path.startsWith("/app/") || path.startsWith("/app.") });
|
|
392
|
+
*/
|
|
393
|
+
skip?: (path: string) => boolean;
|
|
394
|
+
/**
|
|
395
|
+
* The `Cache-Control` of a served file, by the file's URL path, such as
|
|
396
|
+
* `/about/index.html`. `undefined` sends none. A header that the build
|
|
397
|
+
* captured, and the `headers` option, win over it.
|
|
398
|
+
*
|
|
399
|
+
* The default gives an HTML page, a markdown file, and a data file of the
|
|
400
|
+
* framework `public, max-age=0, must-revalidate`, so a visitor always sees
|
|
401
|
+
* the newest page and its markdown twin, and a 304 keeps it fast. It gives every other file
|
|
402
|
+
* `public, max-age=3600, stale-while-revalidate=86400`.
|
|
403
|
+
*
|
|
404
|
+
* @example
|
|
405
|
+
* prerendered({ cacheControl: (path) => (path.startsWith("/images/") ? "public, max-age=86400" : undefined) });
|
|
406
|
+
*/
|
|
407
|
+
cacheControl?: (path: string) => string | undefined;
|
|
408
|
+
};
|
|
409
|
+
/**
|
|
410
|
+
* Serves the client build: prerendered pages at their own URL with a 200,
|
|
411
|
+
* plus every other file in it. It sends no redirect. The `trailingSlash`
|
|
412
|
+
* plugin does. Each response gets
|
|
413
|
+
* the headers its loader sent at build time (the `appServer` Vite plugin
|
|
414
|
+
* captures them), a `Cache-Control` (see `cacheControl`), an ETag, and a 304
|
|
415
|
+
* for a matching `If-None-Match`. A GET with one byte range gets a 206. A path
|
|
416
|
+
* with no file goes on to the framework. In development, only
|
|
417
|
+
* `markdownTwins` runs.
|
|
418
|
+
*
|
|
419
|
+
* At startup, it warns about each prerendered path that has no file.
|
|
420
|
+
*
|
|
421
|
+
* @example
|
|
422
|
+
* prerendered({
|
|
423
|
+
* headers: (path) => (path.startsWith("/api/") ? { "Access-Control-Allow-Origin": "*" } : undefined),
|
|
424
|
+
* });
|
|
425
|
+
*/
|
|
426
|
+
declare function prerendered(options?: PrerenderedOptions): Plugin;
|
|
427
|
+
/** A Hono app from {@link createServer}. Add routes to it before you export it. */
|
|
428
|
+
type AppServer = Hono<AppServerEnv>;
|
|
429
|
+
/** A server that listens. */
|
|
430
|
+
type RunningServer = {
|
|
431
|
+
/** The URL of each listener. */
|
|
432
|
+
urls: readonly string[];
|
|
433
|
+
/**
|
|
434
|
+
* Marks the server as not ready, and waits for the shutdown delay. Then it
|
|
435
|
+
* aborts `shutdownSignal()` and runs each plugin's `onShutdown` while the
|
|
436
|
+
* listeners stop and drain open requests. Both stop at the deadline.
|
|
437
|
+
*/
|
|
438
|
+
shutdown: () => Promise<void>;
|
|
439
|
+
};
|
|
440
|
+
/** Options for {@link defaultPlugins}. */
|
|
441
|
+
type DefaultPluginsOptions = {
|
|
442
|
+
/**
|
|
443
|
+
* The options of the liveness and readiness probes. `false` turns them
|
|
444
|
+
* off, such as for an app with its own `/livez` route. See {@link health}.
|
|
445
|
+
* @default {}
|
|
446
|
+
*/
|
|
447
|
+
health?: HealthOptions | false;
|
|
448
|
+
requestId?: RequestIdOptions;
|
|
449
|
+
accessLog?: AccessLogOptions;
|
|
450
|
+
prerendered?: PrerenderedOptions;
|
|
451
|
+
/**
|
|
452
|
+
* Redirects from old URL paths to new URLs. They run before
|
|
453
|
+
* `trailingSlash`, so an old URL gets one redirect. See {@link redirects}.
|
|
454
|
+
*/
|
|
455
|
+
redirects?: readonly RedirectRule[];
|
|
456
|
+
/**
|
|
457
|
+
* How a page URL ends. Set the same mode in the framework's router when it
|
|
458
|
+
* has one, else the redirects loop. See {@link trailingSlash}.
|
|
459
|
+
* @default "never"
|
|
460
|
+
*/
|
|
461
|
+
trailingSlash?: TrailingSlash;
|
|
462
|
+
/**
|
|
463
|
+
* The largest request body, in bytes. A larger body gets a 413. `false`
|
|
464
|
+
* turns the limit off. See {@link bodyLimit}.
|
|
465
|
+
* @default 10485760 (10 MiB)
|
|
466
|
+
*/
|
|
467
|
+
bodyLimit?: number | false;
|
|
468
|
+
/**
|
|
469
|
+
* The options of the security headers. `false` turns them off. See
|
|
470
|
+
* {@link securityHeaders}.
|
|
471
|
+
*/
|
|
472
|
+
securityHeaders?: SecurityHeadersOptions | false;
|
|
473
|
+
/**
|
|
474
|
+
* Sets `X-Robots-Tag: noindex, nofollow` on each response, such as on a
|
|
475
|
+
* preview deploy. See {@link noindex}.
|
|
476
|
+
* @default false
|
|
477
|
+
*/
|
|
478
|
+
noindex?: boolean;
|
|
479
|
+
/**
|
|
480
|
+
* The options of the build ID on each document and data response. `false`
|
|
481
|
+
* turns it off. See {@link buildId}.
|
|
482
|
+
* @default {}, with the ID that the `appServer` Vite plugin derives from the client build
|
|
483
|
+
*/
|
|
484
|
+
buildId?: BuildIdOptions | false;
|
|
485
|
+
/**
|
|
486
|
+
* The options of the `Content-Security-Policy` of each HTML document. It
|
|
487
|
+
* has no default. See {@link contentSecurityPolicy}.
|
|
488
|
+
*/
|
|
489
|
+
contentSecurityPolicy?: ContentSecurityPolicyOptions;
|
|
490
|
+
/**
|
|
491
|
+
* The plugin from `runtimeEnv(schema)`. It writes the public values into
|
|
492
|
+
* each HTML document, prerendered pages included.
|
|
493
|
+
*/
|
|
494
|
+
env?: RuntimeEnv<unknown>;
|
|
495
|
+
/**
|
|
496
|
+
* The app's own plugins that see every response, prerendered pages
|
|
497
|
+
* included, such as an auth check. They go after the plugins of the
|
|
498
|
+
* options above and before the static stages.
|
|
499
|
+
*/
|
|
500
|
+
beforeStatic?: readonly Plugin[];
|
|
501
|
+
};
|
|
502
|
+
/**
|
|
503
|
+
* The default pipeline, in order: `health`, `requestId`, `accessLog`,
|
|
504
|
+
* `streamingCompress`, `securityHeaders`, `bodyLimit`, `noindex` (when
|
|
505
|
+
* set), `buildId`, `contentSecurityPolicy` (when set), `env` (when set), the
|
|
506
|
+
* `beforeStatic` plugins, `assets`, `redirects` (when the option has rules),
|
|
507
|
+
* `trailingSlash`, `prerendered`, and `privateDocuments`. It is a plain
|
|
508
|
+
* array, so an app can filter it or splice into it.
|
|
509
|
+
*
|
|
510
|
+
* @example
|
|
511
|
+
* createServer({
|
|
512
|
+
* plugins: defaultPlugins({ env, noindex: process.env.PREVIEW === "1", health: { ready: async () => db.ping() } }),
|
|
513
|
+
* });
|
|
514
|
+
*/
|
|
515
|
+
declare function defaultPlugins(options?: DefaultPluginsOptions): Plugin[];
|
|
516
|
+
/** Options for {@link createServer}. */
|
|
517
|
+
type CreateServerOptions = {
|
|
518
|
+
/** @default defaultPlugins() */
|
|
519
|
+
plugins?: readonly Plugin[];
|
|
520
|
+
/** @default jsonSink() */
|
|
521
|
+
logger?: LogSink;
|
|
522
|
+
/** @default the host's listeners, such as `[tcp()]` on the node host */
|
|
523
|
+
listeners?: readonly Listener[];
|
|
524
|
+
/**
|
|
525
|
+
* Read the request scheme from `X-Forwarded-Proto`. Set it only behind a
|
|
526
|
+
* proxy that overwrites that header, else a client can spoof it.
|
|
527
|
+
* @default false
|
|
528
|
+
*/
|
|
529
|
+
trustForwardedProto?: boolean;
|
|
530
|
+
/**
|
|
531
|
+
* How many proxies in front of the server add the address they got a
|
|
532
|
+
* request from to `X-Forwarded-For`. With N, the client address is the
|
|
533
|
+
* Nth address from the right of that header. A header with fewer
|
|
534
|
+
* addresses gives its leftmost address. Set it only to the number of
|
|
535
|
+
* proxies that you run, else a client can spoof its address.
|
|
536
|
+
* @default 0, the address of the socket
|
|
537
|
+
*/
|
|
538
|
+
trustedProxyHops?: number;
|
|
539
|
+
/**
|
|
540
|
+
* How long the listeners serve on after a stop signal, before the drain
|
|
541
|
+
* starts. During this time, the `health` plugin's readiness probe answers
|
|
542
|
+
* 503, so a load balancer stops sending requests first. The drain deadline
|
|
543
|
+
* starts after the delay.
|
|
544
|
+
* @default 0
|
|
545
|
+
*/
|
|
546
|
+
shutdownDelayMs?: number;
|
|
547
|
+
/**
|
|
548
|
+
* How long open requests get to finish after the drain starts.
|
|
549
|
+
* @default 10000
|
|
550
|
+
*/
|
|
551
|
+
shutdownDeadlineMs?: number;
|
|
552
|
+
};
|
|
553
|
+
/**
|
|
554
|
+
* Builds an app server: a Hono app that runs the plugins in list order, then
|
|
555
|
+
* the app's own routes, then the framework. It does not listen; the
|
|
556
|
+
* `app-server` CLI starts it.
|
|
557
|
+
*
|
|
558
|
+
* Two plugins of one option of `defaultPlugins()`, such as two `buildId()`,
|
|
559
|
+
* stop startup.
|
|
560
|
+
*
|
|
561
|
+
* @example
|
|
562
|
+
* // server.ts
|
|
563
|
+
* const app = createServer({ logger: slogSink, plugins: defaultPlugins({ env }) });
|
|
564
|
+
* app.get("/api/status", (c) => c.json({ ok: true }));
|
|
565
|
+
* export default app;
|
|
566
|
+
*/
|
|
567
|
+
declare function createServer({ plugins, logger, listeners, trustForwardedProto, trustedProxyHops, shutdownDelayMs, shutdownDeadlineMs }?: CreateServerOptions): AppServer;
|
|
568
|
+
/** The version of the contract between the CLI and the `appServer` export of a build. */
|
|
569
|
+
declare const ENTRY_PROTOCOL = 2;
|
|
570
|
+
/**
|
|
571
|
+
* What a server build exports as `appServer`. The CLI calls it, so the copy
|
|
572
|
+
* of this package in the build runs the server, and the CLI's copy runs
|
|
573
|
+
* nothing.
|
|
574
|
+
*/
|
|
575
|
+
type AppServerEntry = {
|
|
576
|
+
/** The CLI refuses an entry with another version. */
|
|
577
|
+
protocol: typeof ENTRY_PROTOCOL;
|
|
578
|
+
/** The app. Two entries with the same app share its plugins. */
|
|
579
|
+
app: AppServer;
|
|
580
|
+
/**
|
|
581
|
+
* Production: runs each plugin's `setup` and listens. When the host's
|
|
582
|
+
* lifecycle stops, such as on `SIGTERM`, it shuts down.
|
|
583
|
+
*/
|
|
584
|
+
start: () => Promise<void>;
|
|
585
|
+
/**
|
|
586
|
+
* Production, for a serverless host: answers one request, and does not
|
|
587
|
+
* listen. The first call runs each plugin's `setup`.
|
|
588
|
+
*/
|
|
589
|
+
fetch: FetchHandler;
|
|
590
|
+
/** Development: answers one request with the dev server inside the pipeline. */
|
|
591
|
+
fetchDev: (request: Request, bindings: ListenerBindings, devServer: MiddlewareHandler<AppServerEnv>) => Promise<Response>;
|
|
592
|
+
/** Runs each plugin's `onShutdown` once, up to the shutdown deadline. */
|
|
593
|
+
stopPlugins: () => Promise<void>;
|
|
594
|
+
/** Aborts `shutdownSignal()` of this copy of the package. */
|
|
595
|
+
abortShutdownSignal: () => void;
|
|
596
|
+
};
|
|
597
|
+
/** Options for {@link createEntry}. */
|
|
598
|
+
type CreateEntryOptions = {
|
|
599
|
+
/** The app from `createServer`. */
|
|
600
|
+
app: AppServer;
|
|
601
|
+
/** The run side of the host adapter, such as `host` from `@ngrok/app-server/node`. */
|
|
602
|
+
host: HostRuntime;
|
|
603
|
+
/** Makes the run side of the framework adapter for a mode. */
|
|
604
|
+
framework: (mode: Mode) => FrameworkRuntime;
|
|
605
|
+
/**
|
|
606
|
+
* The client build, as a file path or a `file:` URL. The entry that the
|
|
607
|
+
* Vite plugin generates sets it.
|
|
608
|
+
* @default the framework's `clientDirectory`
|
|
609
|
+
*/
|
|
610
|
+
clientDirectory?: string;
|
|
611
|
+
};
|
|
612
|
+
/**
|
|
613
|
+
* The `appServer` export of a server build: an app from `createServer`, the
|
|
614
|
+
* host, and the framework adapter for each mode. The `appServer` Vite plugin
|
|
615
|
+
* generates this export. Call this for a build without the plugin.
|
|
616
|
+
*
|
|
617
|
+
* @example
|
|
618
|
+
* export const appServer = createEntry({ app, host, framework: (mode) => runtime(build, { mode }) });
|
|
619
|
+
*/
|
|
620
|
+
declare function createEntry({ app, host, framework, clientDirectory }: CreateEntryOptions): AppServerEntry;
|
|
621
|
+
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 };
|
|
622
|
+
//# sourceMappingURL=entry-DmJEqVfd.d.ts.map
|