@fabrika/app 0.9.0-cloudflare.3 → 0.9.0-dev.10
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/package.json +9 -9
- package/skill/SKILL.md +6 -3
- package/skill/references/app-setup.md +8 -8
- package/skill/references/dev.md +3 -1
- package/skill/references/endpoint.md +9 -9
- package/skill/references/errors.md +42 -34
- package/skill/references/files.md +4 -2
- package/skill/references/jobs.md +18 -12
- package/skill/references/table-and-migration.md +31 -4
- package/skill/references/tests.md +22 -10
- package/src/bun.ts +0 -10
- package/src/cloudflare/import.ts +3 -212
- package/src/contract/artifact-schema.ts +1 -6
- package/src/contract/build.ts +10 -33
- package/src/contract/capability-cases.ts +30 -0
- package/src/contract/containers.ts +19 -0
- package/src/contract/group.ts +1 -10
- package/src/contract/index.ts +1 -0
- package/src/contract/kit.ts +1 -2
- package/src/files/handle.ts +2 -1
- package/src/files/kinds.ts +1 -1
- package/src/implement/boot.ts +12 -30
- package/src/implement/capability.ts +1 -4
- package/src/implement/dispatch.ts +8 -5
- package/src/implement/egress.ts +8 -367
- package/src/implement/failures.ts +42 -3
- package/src/implement/faults.ts +4 -1
- package/src/implement/invocation.ts +13 -11
- package/src/implement/tokens.ts +4 -2
- package/src/implement/types.ts +22 -4
- package/src/jobs/runner.ts +32 -20
- package/src/testing/endpoint-access.ts +30 -23
- package/src/testing/index.ts +1 -1
- package/src/testing/kit.ts +6 -2
- package/src/testing/policy-isolation.ts +2 -2
- package/types/src/cloudflare/import.d.ts +1 -12
- package/types/src/contract/capability-cases.d.ts +9 -0
- package/types/src/contract/containers.d.ts +3 -0
- package/types/src/contract/group.d.ts +1 -9
- package/types/src/contract/index.d.ts +1 -0
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/files/handle.d.ts +2 -1
- package/types/src/implement/boot.d.ts +6 -9
- package/types/src/implement/capability.d.ts +1 -3
- package/types/src/implement/dispatch.d.ts +1 -2
- package/types/src/implement/egress.d.ts +1 -36
- package/types/src/implement/failures.d.ts +21 -2
- package/types/src/implement/faults.d.ts +4 -1
- package/types/src/implement/invocation.d.ts +6 -5
- package/types/src/implement/types.d.ts +25 -5
- package/types/src/jobs/runner.d.ts +14 -8
- package/types/src/testing/endpoint-access.d.ts +4 -3
- package/types/src/testing/index.d.ts +1 -1
- package/types/src/testing/kit.d.ts +6 -2
|
@@ -87,7 +87,7 @@ import {
|
|
|
87
87
|
} from './capability'
|
|
88
88
|
import type { ChallengeIssuer, ChallengeVerifier } from './challenge'
|
|
89
89
|
import { connectContext, type ImportWire } from './connect'
|
|
90
|
-
import { runAsSite
|
|
90
|
+
import { runAsSite } from './egress'
|
|
91
91
|
import type { FailureReports } from './failures'
|
|
92
92
|
import { ServerFault } from './faults'
|
|
93
93
|
import { type HeaderPolicy, withHeaderPolicy } from './headers'
|
|
@@ -250,7 +250,7 @@ export type ServedEndpoint =
|
|
|
250
250
|
/** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
|
|
251
251
|
readonly site?: ServedSite
|
|
252
252
|
/** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
|
|
253
|
-
readonly egress?:
|
|
253
|
+
readonly egress?: readonly string[]
|
|
254
254
|
/** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
|
|
255
255
|
readonly admission?: ProcedureAdmission
|
|
256
256
|
/** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */
|
|
@@ -426,6 +426,7 @@ export class ContractRuntime {
|
|
|
426
426
|
|
|
427
427
|
async #answer(request: Request, plan: EndpointPlan, exec: RequestExecutionContext | undefined): Promise<Response | FileDownload> {
|
|
428
428
|
let where = 'request'
|
|
429
|
+
let selected = false
|
|
429
430
|
try {
|
|
430
431
|
const served = plan.outcome === 'endpoint' ? this.#parts.endpoints.get(plan.endpoint.id) : undefined
|
|
431
432
|
// Before any other answer: a direct dial learns nothing, not even whether its path exists.
|
|
@@ -439,6 +440,7 @@ export class ContractRuntime {
|
|
|
439
440
|
throw new NotFoundError(`No endpoint serves ${request.method} ${rawRequestTarget(request.url).pathname}`)
|
|
440
441
|
}
|
|
441
442
|
where = served.row.id
|
|
443
|
+
selected = true
|
|
442
444
|
this.#checkEndpoint(served, request)
|
|
443
445
|
// Counted from here, while it authorizes and uploads too, until it settled.
|
|
444
446
|
const admission = admitInvocation(invocationKind(served))
|
|
@@ -457,7 +459,7 @@ export class ContractRuntime {
|
|
|
457
459
|
}
|
|
458
460
|
const response = errorResponse(error, where)
|
|
459
461
|
if (response.status >= 500) {
|
|
460
|
-
const failure = { endpoint: where, requestId: request.headers.get(REQUEST_ID_HEADER), status: response.status, error }
|
|
462
|
+
const failure = { endpoint: where, selected, requestId: request.headers.get(REQUEST_ID_HEADER), status: response.status, error }
|
|
461
463
|
const delivery = this.#parts.failures.record(failure)
|
|
462
464
|
exec?.waitUntil(delivery)
|
|
463
465
|
}
|
|
@@ -961,6 +963,7 @@ export class ContractRuntime {
|
|
|
961
963
|
/**
|
|
962
964
|
* Several capabilities, each minted as its single access form mints it, in their declared order, so the first one
|
|
963
965
|
* refused answers. Each reads its value from the input as the caller sent it; the fields they read are removed after.
|
|
966
|
+
* `HandlerInput` (`types.ts`) removes the same fields from the handler's input type.
|
|
964
967
|
*/
|
|
965
968
|
async #capabilities(
|
|
966
969
|
requirement: CapabilitiesRequirement,
|
|
@@ -1216,7 +1219,7 @@ export class ContractRuntime {
|
|
|
1216
1219
|
kick: kicks.kick,
|
|
1217
1220
|
})
|
|
1218
1221
|
const args = { input, ctx, ...(query === undefined ? {} : { query }) }
|
|
1219
|
-
return await runAsSite(`'${served.row.id}'`,
|
|
1222
|
+
return await runAsSite(`'${served.row.id}'`, served.site.declaration.egress, async () => await served.handler(args))
|
|
1220
1223
|
})
|
|
1221
1224
|
} finally {
|
|
1222
1225
|
frame.end()
|
|
@@ -1370,7 +1373,7 @@ export class ContractRuntime {
|
|
|
1370
1373
|
if (site === undefined) {
|
|
1371
1374
|
await served.handler(args)
|
|
1372
1375
|
} else {
|
|
1373
|
-
await runAsSite(`webhook '${served.webhook}'`,
|
|
1376
|
+
await runAsSite(`webhook '${served.webhook}'`, site.egress, async () => await served.handler(args))
|
|
1374
1377
|
}
|
|
1375
1378
|
})
|
|
1376
1379
|
} finally {
|
package/src/implement/egress.ts
CHANGED
|
@@ -1,107 +1,23 @@
|
|
|
1
|
-
// `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
// scope, under their own declarations.
|
|
1
|
+
// `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares. It stops a
|
|
2
|
+
// mistake and makes a bypass conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before
|
|
3
|
+
// boot, or opens its own sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store)
|
|
4
|
+
// run outside the site's scope, under their own declarations.
|
|
6
5
|
|
|
7
|
-
import {
|
|
8
|
-
type DeclaredEgress,
|
|
9
|
-
FABRIKA_EGRESS_REFUSED_HOSTS,
|
|
10
|
-
isPublicAddress,
|
|
11
|
-
normalizedHost,
|
|
12
|
-
PUBLIC_EGRESS,
|
|
13
|
-
publicEgressRefusal,
|
|
14
|
-
} from '@fabrika/auth-core'
|
|
15
6
|
import { AsyncLocalStorage } from 'node:async_hooks'
|
|
16
7
|
import { CapabilityRefusedError } from './capability'
|
|
17
8
|
|
|
18
|
-
/** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
|
|
19
|
-
export type HostResolver = (hostname: string) => Promise<readonly string[]>
|
|
20
|
-
|
|
21
|
-
/** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
|
|
22
|
-
export interface PublicEgressRules {
|
|
23
|
-
/** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
|
|
24
|
-
readonly refusedHosts: ReadonlySet<string>
|
|
25
|
-
/** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
|
|
26
|
-
readonly resolve: HostResolver | null
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
/** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
|
|
30
|
-
export type SiteEgress = readonly string[] | PublicEgressRules
|
|
31
|
-
|
|
32
|
-
/**
|
|
33
|
-
* The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
|
|
34
|
-
* aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
|
|
35
|
-
*/
|
|
36
|
-
export const PUBLIC_EGRESS_LIMITS = {
|
|
37
|
-
/** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
|
|
38
|
-
timeoutMs: 60_000,
|
|
39
|
-
/** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
|
|
40
|
-
maxResponseBytes: 16 * 1024 * 1024,
|
|
41
|
-
/** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
|
|
42
|
-
maxRedirects: 10,
|
|
43
|
-
} as const
|
|
44
|
-
|
|
45
9
|
interface EgressScope {
|
|
46
10
|
/** The site, as a refusal names it. */
|
|
47
11
|
readonly site: string
|
|
48
12
|
readonly origins: ReadonlySet<string>
|
|
49
|
-
/** Public egress: `null` for a site that declares origins, or none. */
|
|
50
|
-
readonly open: PublicEgressRules | null
|
|
51
13
|
}
|
|
52
14
|
|
|
53
15
|
const scope = new AsyncLocalStorage<EgressScope>()
|
|
54
16
|
const guards = new WeakSet<object>()
|
|
55
17
|
|
|
56
18
|
/** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
|
|
57
|
-
export function runAsSite<T>(site: string, egress:
|
|
58
|
-
return
|
|
59
|
-
? scope.run({ site, origins: new Set(egress), open: null }, work)
|
|
60
|
-
: scope.run({ site, origins: new Set(), open: egress }, work)
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
/**
|
|
64
|
-
* The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
|
|
65
|
-
* site run without them reaches nothing, though the build lets no other site declare `'public'`.
|
|
66
|
-
*/
|
|
67
|
-
export function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress {
|
|
68
|
-
return declared === PUBLIC_EGRESS ? (rules ?? []) : declared
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
function isOrigins(egress: SiteEgress): egress is readonly string[] {
|
|
72
|
-
return Array.isArray(egress)
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
/**
|
|
76
|
-
* The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
|
|
77
|
-
* origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
|
|
78
|
-
* runtime adapter supplies.
|
|
79
|
-
*/
|
|
80
|
-
export function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules {
|
|
81
|
-
const hosts = new Set<string>()
|
|
82
|
-
for (const [name, value] of Object.entries(framework)) {
|
|
83
|
-
if (name === FABRIKA_EGRESS_REFUSED_HOSTS) {
|
|
84
|
-
for (const host of value.split(',')) {
|
|
85
|
-
const normalized = normalizedHost(host.trim())
|
|
86
|
-
if (normalized !== '') hosts.add(normalized)
|
|
87
|
-
}
|
|
88
|
-
continue
|
|
89
|
-
}
|
|
90
|
-
const host = urlHost(value)
|
|
91
|
-
if (host !== null) hosts.add(host)
|
|
92
|
-
}
|
|
93
|
-
return { refusedHosts: hosts, resolve }
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
/** The host of a framework variable's value when it is an http(s) URL, such as an origin or a DSN; `null` otherwise. */
|
|
97
|
-
function urlHost(value: string): string | null {
|
|
98
|
-
const text = value.trim()
|
|
99
|
-
if (!/^https?:\/\//i.test(text)) return null
|
|
100
|
-
try {
|
|
101
|
-
return normalizedHost(new URL(text).hostname)
|
|
102
|
-
} catch {
|
|
103
|
-
return null
|
|
104
|
-
}
|
|
19
|
+
export function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T> {
|
|
20
|
+
return scope.run({ site, origins: new Set(egress) }, work)
|
|
105
21
|
}
|
|
106
22
|
|
|
107
23
|
/**
|
|
@@ -125,8 +41,6 @@ export function platformCall<T>(work: () => T): T {
|
|
|
125
41
|
return scope.exit(work)
|
|
126
42
|
}
|
|
127
43
|
|
|
128
|
-
type Fetch = (input: string, init: RequestInit) => Promise<Response>
|
|
129
|
-
|
|
130
44
|
/**
|
|
131
45
|
* Wraps the global `fetch` in the guard, once: a `fetch` that is already a guard stays. A test that replaces `fetch`
|
|
132
46
|
* after boot replaces the guard with it.
|
|
@@ -136,20 +50,15 @@ export function installEgressGuard(): void {
|
|
|
136
50
|
if (guards.has(current)) {
|
|
137
51
|
return
|
|
138
52
|
}
|
|
139
|
-
const send: Fetch = (input, init) => current(input, init)
|
|
140
53
|
const guarded = Object.assign(
|
|
141
54
|
(input: string | URL | Request, init?: RequestInit): Promise<Response> => {
|
|
142
55
|
const running = scope.getStore()
|
|
143
56
|
if (running === undefined) {
|
|
144
57
|
return current(input, init)
|
|
145
58
|
}
|
|
146
|
-
if (running.open !== null) {
|
|
147
|
-
return publicFetch(send, running.site, running.open, input, init)
|
|
148
|
-
}
|
|
149
59
|
const origin = originOf(input)
|
|
150
60
|
if (origin !== null && running.origins.has(origin)) {
|
|
151
|
-
|
|
152
|
-
return current(input, standardInit(init))
|
|
61
|
+
return current(input, init)
|
|
153
62
|
}
|
|
154
63
|
return Promise.reject(
|
|
155
64
|
new CapabilityRefusedError(
|
|
@@ -160,47 +69,12 @@ export function installEgressGuard(): void {
|
|
|
160
69
|
),
|
|
161
70
|
)
|
|
162
71
|
},
|
|
163
|
-
{
|
|
164
|
-
// Inside a site's scope a preconnect reaches only a declared origin; public egress, which cannot check a hop
|
|
165
|
-
// before it connects, refuses every one.
|
|
166
|
-
preconnect: (...args: Parameters<typeof current.preconnect>): void => {
|
|
167
|
-
const running = scope.getStore()
|
|
168
|
-
if (running !== undefined) {
|
|
169
|
-
const origin = originOf(args[0])
|
|
170
|
-
if (running.open !== null || origin === null || !running.origins.has(origin)) {
|
|
171
|
-
throw new CapabilityRefusedError(
|
|
172
|
-
running.open === null ? 'undeclared_egress' : 'refused_egress',
|
|
173
|
-
`${running.site} preconnects to ${origin ?? 'a URL that is not absolute'}, which its egress does not reach`,
|
|
174
|
-
)
|
|
175
|
-
}
|
|
176
|
-
}
|
|
177
|
-
if (typeof current.preconnect === 'function') current.preconnect(...args)
|
|
178
|
-
},
|
|
179
|
-
},
|
|
72
|
+
{ preconnect: current.preconnect },
|
|
180
73
|
)
|
|
181
74
|
guards.add(guarded)
|
|
182
75
|
globalThis.fetch = guarded
|
|
183
76
|
}
|
|
184
77
|
|
|
185
|
-
/** `init` with the fields of the Fetch standard only. */
|
|
186
|
-
function standardInit(init: RequestInit | undefined): RequestInit | undefined {
|
|
187
|
-
if (init === undefined) return undefined
|
|
188
|
-
return {
|
|
189
|
-
...(init.method === undefined ? {} : { method: init.method }),
|
|
190
|
-
...(init.headers === undefined ? {} : { headers: init.headers }),
|
|
191
|
-
...(init.body === undefined ? {} : { body: init.body }),
|
|
192
|
-
...(init.redirect === undefined ? {} : { redirect: init.redirect }),
|
|
193
|
-
...(init.signal === undefined ? {} : { signal: init.signal }),
|
|
194
|
-
...(init.keepalive === undefined ? {} : { keepalive: init.keepalive }),
|
|
195
|
-
...(init.integrity === undefined ? {} : { integrity: init.integrity }),
|
|
196
|
-
...(init.referrer === undefined ? {} : { referrer: init.referrer }),
|
|
197
|
-
...(init.referrerPolicy === undefined ? {} : { referrerPolicy: init.referrerPolicy }),
|
|
198
|
-
...(init.cache === undefined ? {} : { cache: init.cache }),
|
|
199
|
-
...(init.credentials === undefined ? {} : { credentials: init.credentials }),
|
|
200
|
-
...(init.mode === undefined ? {} : { mode: init.mode }),
|
|
201
|
-
}
|
|
202
|
-
}
|
|
203
|
-
|
|
204
78
|
function originOf(input: string | URL | Request): string | null {
|
|
205
79
|
try {
|
|
206
80
|
return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).origin
|
|
@@ -208,236 +82,3 @@ function originOf(input: string | URL | Request): string | null {
|
|
|
208
82
|
return null
|
|
209
83
|
}
|
|
210
84
|
}
|
|
211
|
-
|
|
212
|
-
const REDIRECTS: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
|
|
213
|
-
/** The headers a redirect that turns a request into a `GET` drops with its body (Fetch, "HTTP-redirect fetch"). */
|
|
214
|
-
const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']
|
|
215
|
-
/**
|
|
216
|
-
* The request headers public egress never sends, on any hop: the Fetch standard's forbidden request headers (`Host`
|
|
217
|
-
* among them, which would route a request for a public name to another site at the same address), the forwarding
|
|
218
|
-
* headers a proxy trusts, and the platform's own `X-Fabrika-*`.
|
|
219
|
-
*/
|
|
220
|
-
const FORBIDDEN_HEADERS = [
|
|
221
|
-
'accept-charset',
|
|
222
|
-
'accept-encoding',
|
|
223
|
-
'access-control-request-headers',
|
|
224
|
-
'access-control-request-method',
|
|
225
|
-
'connection',
|
|
226
|
-
'content-length',
|
|
227
|
-
'cookie2',
|
|
228
|
-
'date',
|
|
229
|
-
'dnt',
|
|
230
|
-
'expect',
|
|
231
|
-
'forwarded',
|
|
232
|
-
'host',
|
|
233
|
-
'keep-alive',
|
|
234
|
-
'origin',
|
|
235
|
-
'referer',
|
|
236
|
-
'set-cookie',
|
|
237
|
-
'te',
|
|
238
|
-
'trailer',
|
|
239
|
-
'transfer-encoding',
|
|
240
|
-
'upgrade',
|
|
241
|
-
'via',
|
|
242
|
-
'x-http-method',
|
|
243
|
-
'x-http-method-override',
|
|
244
|
-
'x-method-override',
|
|
245
|
-
'x-real-ip',
|
|
246
|
-
]
|
|
247
|
-
const FORBIDDEN_HEADER_PREFIXES = ['proxy-', 'sec-', 'x-forwarded-', 'x-fabrika-']
|
|
248
|
-
|
|
249
|
-
function withoutForbiddenHeaders(headers: Headers): Headers {
|
|
250
|
-
for (const name of [...headers.keys()]) {
|
|
251
|
-
if (FORBIDDEN_HEADERS.includes(name) || FORBIDDEN_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
|
|
252
|
-
headers.delete(name)
|
|
253
|
-
}
|
|
254
|
-
}
|
|
255
|
-
return headers
|
|
256
|
-
}
|
|
257
|
-
|
|
258
|
-
/** The credentials a redirect to another origin drops. */
|
|
259
|
-
const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie']
|
|
260
|
-
|
|
261
|
-
/**
|
|
262
|
-
* One request under public egress. Every hop is sent with `redirect: 'manual'`, so the runtime follows no redirect the
|
|
263
|
-
* guard has not checked: the caller's `follow` is done here, at most `maxRedirects` hops, each host checked again;
|
|
264
|
-
* `manual` hands the caller the redirect, whose next `fetch` passes the guard again; `error` refuses one. The request
|
|
265
|
-
* is bounded in time and its answer's body in size.
|
|
266
|
-
*/
|
|
267
|
-
async function publicFetch(
|
|
268
|
-
send: Fetch,
|
|
269
|
-
site: string,
|
|
270
|
-
rules: PublicEgressRules,
|
|
271
|
-
input: string | URL | Request,
|
|
272
|
-
init?: RequestInit,
|
|
273
|
-
): Promise<Response> {
|
|
274
|
-
const request = new Request(input, init)
|
|
275
|
-
// A timer the guard clears once the body is read, not `AbortSignal.timeout`: on workerd an uncleared timer keeps the
|
|
276
|
-
// Durable Object awake until it fires.
|
|
277
|
-
const deadline = new AbortController()
|
|
278
|
-
const timer = setTimeout(() => deadline.abort(new DOMException('public egress request timed out', 'TimeoutError')), PUBLIC_EGRESS_LIMITS.timeoutMs)
|
|
279
|
-
const done = (): void => clearTimeout(timer)
|
|
280
|
-
try {
|
|
281
|
-
return await follow(send, site, rules, request, AbortSignal.any([request.signal, deadline.signal]), done)
|
|
282
|
-
} catch (error) {
|
|
283
|
-
done()
|
|
284
|
-
throw error
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
|
|
288
|
-
/** The hops of one request; `done` clears its deadline once its last answer's body is read. */
|
|
289
|
-
async function follow(
|
|
290
|
-
send: Fetch,
|
|
291
|
-
site: string,
|
|
292
|
-
rules: PublicEgressRules,
|
|
293
|
-
request: Request,
|
|
294
|
-
signal: AbortSignal,
|
|
295
|
-
done: () => void,
|
|
296
|
-
): Promise<Response> {
|
|
297
|
-
const mode = request.redirect
|
|
298
|
-
let url = new URL(request.url)
|
|
299
|
-
let method = request.method
|
|
300
|
-
const headers = withoutForbiddenHeaders(new Headers(request.headers))
|
|
301
|
-
// Read once, so that a 307 or a 308 sends it again.
|
|
302
|
-
let body: ArrayBuffer | null = request.body === null ? null : await untilAborted(signal, request.arrayBuffer())
|
|
303
|
-
for (let hop = 0;; hop++) {
|
|
304
|
-
await admit(site, rules, url, signal)
|
|
305
|
-
const response = await send(url.href, { method, headers: new Headers(headers), body, redirect: 'manual', signal })
|
|
306
|
-
const location = REDIRECTS.has(response.status) ? response.headers.get('location') : null
|
|
307
|
-
if (location === null || mode === 'manual') {
|
|
308
|
-
return await capped(site, response, url, hop > 0, signal, done)
|
|
309
|
-
}
|
|
310
|
-
await response.body?.cancel()
|
|
311
|
-
if (mode === 'error') {
|
|
312
|
-
throw new TypeError(`${site}: ${url.origin} redirects, and the request's redirect mode is 'error'`)
|
|
313
|
-
}
|
|
314
|
-
if (hop >= PUBLIC_EGRESS_LIMITS.maxRedirects) {
|
|
315
|
-
throw new TypeError(`${site}: more than ${PUBLIC_EGRESS_LIMITS.maxRedirects} redirects, the last from ${url.origin}`)
|
|
316
|
-
}
|
|
317
|
-
const next = new URL(location, url)
|
|
318
|
-
const toGet = (response.status === 303 && method !== 'GET' && method !== 'HEAD')
|
|
319
|
-
|| ((response.status === 301 || response.status === 302) && method === 'POST')
|
|
320
|
-
if (toGet) {
|
|
321
|
-
method = 'GET'
|
|
322
|
-
body = null
|
|
323
|
-
for (const name of BODY_HEADERS) headers.delete(name)
|
|
324
|
-
}
|
|
325
|
-
if (next.origin !== url.origin) {
|
|
326
|
-
for (const name of CREDENTIAL_HEADERS) headers.delete(name)
|
|
327
|
-
}
|
|
328
|
-
url = next
|
|
329
|
-
}
|
|
330
|
-
}
|
|
331
|
-
|
|
332
|
-
/** Refuses a hop public egress does not reach: by the URL, by the installation's hosts, by what its name resolves to. */
|
|
333
|
-
async function admit(site: string, rules: PublicEgressRules, url: URL, signal: AbortSignal): Promise<void> {
|
|
334
|
-
const refusal = publicEgressRefusal(url, rules.refusedHosts)
|
|
335
|
-
if (refusal !== null) {
|
|
336
|
-
throw new CapabilityRefusedError('refused_egress', `${site} calls ${url.origin}, which public egress refuses: ${refusal}`)
|
|
337
|
-
}
|
|
338
|
-
const resolve = rules.resolve
|
|
339
|
-
if (resolve === null) {
|
|
340
|
-
return
|
|
341
|
-
}
|
|
342
|
-
const host = normalizedHost(url.hostname)
|
|
343
|
-
const addresses = await untilAborted(signal, platformCall(() => resolve(host)))
|
|
344
|
-
const internal = addresses.find((address) => !isPublicAddress(address))
|
|
345
|
-
if (addresses.length === 0 || internal !== undefined) {
|
|
346
|
-
throw new CapabilityRefusedError(
|
|
347
|
-
'refused_egress',
|
|
348
|
-
`${site} calls ${url.origin}, which public egress refuses: ${
|
|
349
|
-
internal === undefined ? `${host} resolves to no address` : `${host} resolves to ${internal}, which is not a public address`
|
|
350
|
-
}`,
|
|
351
|
-
)
|
|
352
|
-
}
|
|
353
|
-
}
|
|
354
|
-
|
|
355
|
-
/**
|
|
356
|
-
* `response` with its body bounded by `maxResponseBytes`, and the URL and redirect flag of the request it answers,
|
|
357
|
-
* which a response the guard builds would otherwise lose.
|
|
358
|
-
*/
|
|
359
|
-
async function capped(
|
|
360
|
-
site: string,
|
|
361
|
-
response: Response,
|
|
362
|
-
url: URL,
|
|
363
|
-
redirected: boolean,
|
|
364
|
-
signal: AbortSignal,
|
|
365
|
-
done: () => void,
|
|
366
|
-
): Promise<Response> {
|
|
367
|
-
const max = PUBLIC_EGRESS_LIMITS.maxResponseBytes
|
|
368
|
-
const tooLarge = () =>
|
|
369
|
-
new CapabilityRefusedError(
|
|
370
|
-
'oversized_egress',
|
|
371
|
-
`${site}: ${url.origin} answers more than ${max} bytes, the most public egress reads of one response`,
|
|
372
|
-
)
|
|
373
|
-
const declared = Number(response.headers.get('content-length') ?? '0')
|
|
374
|
-
if (Number.isFinite(declared) && declared > max) {
|
|
375
|
-
await response.body?.cancel()
|
|
376
|
-
throw tooLarge()
|
|
377
|
-
}
|
|
378
|
-
if (response.body === null || response.status < 200 || response.status > 599) {
|
|
379
|
-
done()
|
|
380
|
-
return withRequestUrl(response, url, redirected)
|
|
381
|
-
}
|
|
382
|
-
const reader = response.body.getReader()
|
|
383
|
-
let seen = 0
|
|
384
|
-
const bound = new ReadableStream<Uint8Array>({
|
|
385
|
-
async pull(controller) {
|
|
386
|
-
const read = await untilAborted(signal, reader.read()).catch(async (error: unknown) => {
|
|
387
|
-
done()
|
|
388
|
-
await reader.cancel(error).catch(() => undefined)
|
|
389
|
-
throw error
|
|
390
|
-
})
|
|
391
|
-
if (read.done) {
|
|
392
|
-
done()
|
|
393
|
-
controller.close()
|
|
394
|
-
return
|
|
395
|
-
}
|
|
396
|
-
seen += read.value.byteLength
|
|
397
|
-
if (seen > max) {
|
|
398
|
-
done()
|
|
399
|
-
await reader.cancel()
|
|
400
|
-
controller.error(tooLarge())
|
|
401
|
-
return
|
|
402
|
-
}
|
|
403
|
-
controller.enqueue(read.value)
|
|
404
|
-
},
|
|
405
|
-
async cancel(reason) {
|
|
406
|
-
done()
|
|
407
|
-
await reader.cancel(reason)
|
|
408
|
-
},
|
|
409
|
-
})
|
|
410
|
-
const answer = new Response(bound, {
|
|
411
|
-
status: response.status,
|
|
412
|
-
statusText: response.statusText,
|
|
413
|
-
headers: response.headers,
|
|
414
|
-
})
|
|
415
|
-
return withRequestUrl(answer, url, redirected)
|
|
416
|
-
}
|
|
417
|
-
|
|
418
|
-
/**
|
|
419
|
-
* `work`, or the signal's reason once it aborts, whichever comes first: a stage the runtime does not abort by the
|
|
420
|
-
* signal (a resolver, a body read) still ends at the deadline. The work itself is left to settle unobserved.
|
|
421
|
-
*/
|
|
422
|
-
async function untilAborted<T>(signal: AbortSignal, work: Promise<T>): Promise<T> {
|
|
423
|
-
signal.throwIfAborted()
|
|
424
|
-
let abort = (): void => {}
|
|
425
|
-
const aborted = new Promise<never>((_resolve, reject) => {
|
|
426
|
-
abort = () => reject(signal.reason)
|
|
427
|
-
})
|
|
428
|
-
signal.addEventListener('abort', abort, { once: true })
|
|
429
|
-
try {
|
|
430
|
-
return await Promise.race([work, aborted])
|
|
431
|
-
} finally {
|
|
432
|
-
signal.removeEventListener('abort', abort)
|
|
433
|
-
}
|
|
434
|
-
}
|
|
435
|
-
|
|
436
|
-
function withRequestUrl(response: Response, url: URL, redirected: boolean): Response {
|
|
437
|
-
try {
|
|
438
|
-
Object.defineProperties(response, { url: { value: url.href }, redirected: { value: redirected } })
|
|
439
|
-
} catch {
|
|
440
|
-
// A runtime whose responses refuse own properties keeps its own `url`; the body bound holds either way.
|
|
441
|
-
}
|
|
442
|
-
return response
|
|
443
|
-
}
|
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
// framework's own refusals can put request data there. The event adds what was thrown as its cause chain, scrubbed of
|
|
4
4
|
// the environment's secrets and of credential patterns, a framework failure's message replaced by its catalog text
|
|
5
5
|
// (ADR-0059). A writing invocation that held its Durable Object's transaction too long is an event on the same budget.
|
|
6
|
+
// The author's own run (`fabrika app dev`, a test that passes `revealHandlerErrors`) also sees what was thrown, whole,
|
|
7
|
+
// beside the log line; no deployed application sets that sink.
|
|
6
8
|
|
|
7
9
|
import { CAPABILITY_ERRORS, CapabilityError, QUERY_REFUSALS, QueryRefusedError } from '@fabrika/db/framework'
|
|
8
10
|
import { isStructuralError } from '../errors'
|
|
@@ -18,6 +20,27 @@ export type RequestFailureCode =
|
|
|
18
20
|
| 'handler_status'
|
|
19
21
|
| 'handler_failed'
|
|
20
22
|
|
|
23
|
+
/**
|
|
24
|
+
* Where the author's own run shows what a request's 5xx or a job attempt threw, whole, with where it happened:
|
|
25
|
+
* `fabrika app dev` sets one, and a test may pass one to the kit. No deployed application has one.
|
|
26
|
+
*/
|
|
27
|
+
export type HandlerErrorSink = (where: string, error: unknown) => void
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Hands `error` to the author's sink, if there is one. A sink that throws (a test's `expect` inside it) changes nothing
|
|
31
|
+
* of the failure it was shown: the failure is classified, logged and reported as without it.
|
|
32
|
+
*/
|
|
33
|
+
export function reveal(sink: HandlerErrorSink | null, where: string, error: unknown): void {
|
|
34
|
+
if (sink === null) {
|
|
35
|
+
return
|
|
36
|
+
}
|
|
37
|
+
try {
|
|
38
|
+
sink(where, error)
|
|
39
|
+
} catch {
|
|
40
|
+
console.error(`fabrika: revealHandlerErrors threw while it showed ${where}; the failure stands as it was`)
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
21
44
|
/** At most this many request failures per process and minute become Operations events; every one is logged. */
|
|
22
45
|
export const MAX_FAILURE_REPORTS_PER_MINUTE = 30
|
|
23
46
|
|
|
@@ -65,6 +88,8 @@ export function failureReason(error: unknown): FailureReason | null {
|
|
|
65
88
|
export interface RequestFailure {
|
|
66
89
|
/** The endpoint id the request selected, or `request` before one was selected. */
|
|
67
90
|
readonly endpoint: string
|
|
91
|
+
/** Whether the request selected an endpoint, so `endpoint` is its id and not the fallback. */
|
|
92
|
+
readonly selected: boolean
|
|
68
93
|
/** The proxy's `X-Request-Id`. */
|
|
69
94
|
readonly requestId: string | null
|
|
70
95
|
readonly status: number
|
|
@@ -94,14 +119,24 @@ export class MinuteBudget {
|
|
|
94
119
|
}
|
|
95
120
|
}
|
|
96
121
|
|
|
122
|
+
export interface FailureReportsOptions {
|
|
123
|
+
readonly now?: () => number
|
|
124
|
+
readonly reveal?: HandlerErrorSink | null
|
|
125
|
+
}
|
|
126
|
+
|
|
97
127
|
export class FailureReports {
|
|
98
128
|
readonly #reporter: OperationsReporter | null
|
|
99
129
|
readonly #budget: MinuteBudget
|
|
130
|
+
readonly #reveal: HandlerErrorSink | null
|
|
100
131
|
|
|
101
|
-
/**
|
|
102
|
-
|
|
132
|
+
/**
|
|
133
|
+
* `reporter` is `null` without an Operations DSN: the log line is then the only record. `reveal` is `boot`'s
|
|
134
|
+
* `revealHandlerErrors`, set on the author's own run only; `now` is the budget's clock.
|
|
135
|
+
*/
|
|
136
|
+
constructor(reporter: OperationsReporter | null, options: FailureReportsOptions = {}) {
|
|
103
137
|
this.#reporter = reporter
|
|
104
|
-
this.#budget = new MinuteBudget(MAX_FAILURE_REPORTS_PER_MINUTE, now)
|
|
138
|
+
this.#budget = new MinuteBudget(MAX_FAILURE_REPORTS_PER_MINUTE, options.now ?? Date.now)
|
|
139
|
+
this.#reveal = options.reveal ?? null
|
|
105
140
|
}
|
|
106
141
|
|
|
107
142
|
/** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
|
|
@@ -109,6 +144,10 @@ export class FailureReports {
|
|
|
109
144
|
const code = failureCode(failure.error)
|
|
110
145
|
const why = failureReason(failure.error)
|
|
111
146
|
console.error(`fabrika: ${failure.endpoint}: ${code}${why === null ? '' : `: ${why.reason}: ${why.text}`}`)
|
|
147
|
+
if (this.#reveal !== null) {
|
|
148
|
+
// What the line withholds (a refusal's message names the place: a column, a line of ctx.sql) on the author's own run.
|
|
149
|
+
reveal(this.#reveal, failure.selected ? `endpoint '${failure.endpoint}'` : 'a request', failure.error)
|
|
150
|
+
}
|
|
112
151
|
if (this.#reporter === null || !this.#budget.admit()) {
|
|
113
152
|
return Promise.resolve()
|
|
114
153
|
}
|
package/src/implement/faults.ts
CHANGED
|
@@ -43,7 +43,10 @@ export const SERVER_FAULTS = {
|
|
|
43
43
|
|
|
44
44
|
export type ServerFaultReason = keyof typeof SERVER_FAULTS
|
|
45
45
|
|
|
46
|
-
/**
|
|
46
|
+
/**
|
|
47
|
+
* A failure the framework itself describes. Its message is for the author's own run (`revealHandlerErrors`), never the
|
|
48
|
+
* response or a log.
|
|
49
|
+
*/
|
|
47
50
|
export class ServerFault extends Error {
|
|
48
51
|
override readonly name = 'ServerFault'
|
|
49
52
|
readonly reason: ServerFaultReason
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// commits it after the handler returned and its output passed validation, and rolls it back otherwise. Every handle
|
|
4
4
|
// is bound to the invocation: called from another request, another `boot`, or after it ended, it refuses.
|
|
5
5
|
|
|
6
|
-
import { type ContractArtifact,
|
|
6
|
+
import { type ContractArtifact, JOB_MAILERS, type JobMailer } from '@fabrika/auth-core'
|
|
7
7
|
import {
|
|
8
8
|
type DataAccess,
|
|
9
9
|
type DataHandles,
|
|
@@ -35,8 +35,8 @@ export interface SiteDeclaration {
|
|
|
35
35
|
readonly binds: string | null
|
|
36
36
|
/** The token purposes `ctx.tokens.sign` may sign. */
|
|
37
37
|
readonly signs: readonly string[]
|
|
38
|
-
/** The HTTPS origins the global `fetch` reaches while the site's handler runs
|
|
39
|
-
readonly egress:
|
|
38
|
+
/** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
|
|
39
|
+
readonly egress: readonly string[]
|
|
40
40
|
}
|
|
41
41
|
|
|
42
42
|
/** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
|
|
@@ -167,11 +167,10 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
|
|
|
167
167
|
problems.push(`${where}: signs is not a list of token purposes`)
|
|
168
168
|
}
|
|
169
169
|
const egressField = ownField(declared, 'egress')
|
|
170
|
-
const
|
|
171
|
-
if (egressField !== undefined &&
|
|
172
|
-
problems.push(`${where}: egress is not a list of origins
|
|
170
|
+
const egress = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
|
|
171
|
+
if (egressField !== undefined && (!Array.isArray(egressField) || egress.length !== egressField.length)) {
|
|
172
|
+
problems.push(`${where}: egress is not a list of origins`)
|
|
173
173
|
}
|
|
174
|
-
const egress: DeclaredEgress = egressField === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...new Set(origins)].sort())
|
|
175
174
|
return Object.freeze({
|
|
176
175
|
sql: sql === 'read' || sql === 'write' ? sql : null,
|
|
177
176
|
unscoped: Object.freeze(unscoped),
|
|
@@ -181,7 +180,7 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
|
|
|
181
180
|
kicks: Object.freeze([...new Set(kicks)].sort()),
|
|
182
181
|
binds: typeof binds === 'string' ? binds : null,
|
|
183
182
|
signs: Object.freeze([...new Set(signs)].sort()),
|
|
184
|
-
egress,
|
|
183
|
+
egress: Object.freeze([...new Set(egress)].sort()),
|
|
185
184
|
})
|
|
186
185
|
}
|
|
187
186
|
|
|
@@ -226,7 +225,7 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
|
|
|
226
225
|
kicks: Object.freeze([...(reach.kicks ?? [])]),
|
|
227
226
|
binds: reach.binds ?? null,
|
|
228
227
|
signs: Object.freeze([...(reach.signs ?? [])]),
|
|
229
|
-
egress:
|
|
228
|
+
egress: Object.freeze([...(reach.egress ?? [])]),
|
|
230
229
|
})
|
|
231
230
|
}
|
|
232
231
|
|
|
@@ -245,7 +244,7 @@ function describeDeclaration(declaration: SiteDeclaration): string {
|
|
|
245
244
|
...(declaration.kicks.length === 0 ? {} : { kicks: declaration.kicks }),
|
|
246
245
|
...(declaration.binds === null ? {} : { binds: declaration.binds }),
|
|
247
246
|
...(declaration.signs.length === 0 ? {} : { signs: declaration.signs }),
|
|
248
|
-
...(declaration.egress
|
|
247
|
+
...(declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
|
|
249
248
|
})
|
|
250
249
|
}
|
|
251
250
|
|
|
@@ -417,7 +416,8 @@ export function boundWebhookApp(webhook: string): (action: string) => never {
|
|
|
417
416
|
|
|
418
417
|
/**
|
|
419
418
|
* The handles of a job attempt, outside its fenced transaction (`'job'`, each read on its own) or inside it. `tickMs`,
|
|
420
|
-
* the job's schedule period, is a queue claim's first backoff
|
|
419
|
+
* the job's schedule period, is a queue claim's first backoff; `holds`, the actions the job holds, decide which file
|
|
420
|
+
* references of a claimed row it may open.
|
|
421
421
|
*/
|
|
422
422
|
export function jobHandles(
|
|
423
423
|
frame: RequestFrame,
|
|
@@ -429,6 +429,7 @@ export function jobHandles(
|
|
|
429
429
|
ended: () => boolean,
|
|
430
430
|
tickMs?: number,
|
|
431
431
|
files?: FileBinding,
|
|
432
|
+
holds?: readonly string[],
|
|
432
433
|
): DataHandles {
|
|
433
434
|
return data.handles({
|
|
434
435
|
kind,
|
|
@@ -438,6 +439,7 @@ export function jobHandles(
|
|
|
438
439
|
session,
|
|
439
440
|
...(tickMs === undefined ? {} : { tickMs }),
|
|
440
441
|
...(files === undefined ? {} : { files }),
|
|
442
|
+
...(holds === undefined ? {} : { holds }),
|
|
441
443
|
})
|
|
442
444
|
}
|
|
443
445
|
|