@fabrika/app 0.9.0-dev.1 → 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 +32 -26
- package/skill/SKILL.md +46 -15
- package/skill/references/app-setup.md +43 -12
- package/skill/references/dev.md +5 -2
- package/skill/references/endpoint.md +39 -28
- package/skill/references/errors.md +50 -37
- package/skill/references/files.md +8 -4
- package/skill/references/jobs.md +39 -7
- package/skill/references/table-and-migration.md +47 -3
- package/skill/references/tests.md +61 -10
- package/skill/references/webhooks-links-connectors.md +1 -1
- package/src/build-recipe.ts +198 -0
- package/src/build.ts +60 -4
- package/src/bun.ts +181 -13
- package/src/cloudflare/application.ts +822 -0
- package/src/cloudflare/bindings.ts +159 -0
- package/src/cloudflare/export.ts +621 -0
- package/src/cloudflare/import.ts +888 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +16 -0
- package/src/cloudflare/ops.ts +375 -0
- package/src/cloudflare/r2-files.ts +172 -0
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +100 -146
- package/src/contract/app-id.ts +5 -0
- package/src/contract/artifact-schema.ts +9 -1
- package/src/contract/build.ts +40 -2
- package/src/contract/capability-cases.ts +30 -0
- package/src/contract/compile.ts +1 -0
- package/src/contract/containers.ts +19 -0
- package/src/contract/context.ts +35 -9
- package/src/contract/declaration.ts +2 -0
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +29 -3
- package/src/contract/index.ts +1 -0
- package/src/contract/kit.ts +4 -1
- package/src/contract/platform.ts +3 -2
- package/src/contract/vocabulary.ts +26 -8
- package/src/dev/changes.ts +5 -43
- package/src/dev/contract-digest.ts +17 -0
- package/src/dev/index.ts +1 -1
- package/src/dev/launcher.ts +197 -41
- package/src/dev/output.ts +13 -3
- package/src/dev/wire.ts +11 -1
- package/src/disk-assets.ts +8 -3
- package/src/files/archive.ts +2 -2
- package/src/files/handle.ts +2 -1
- package/src/files/job-names.ts +12 -0
- package/src/files/kinds.ts +74 -32
- package/src/files/scan.ts +3 -4
- package/src/files/streams.ts +3 -1
- package/src/implement/anonymous.ts +12 -11
- package/src/implement/boot.ts +84 -27
- package/src/implement/bounded.ts +21 -2
- package/src/implement/capability.ts +16 -4
- package/src/implement/dispatch.ts +423 -178
- package/src/implement/failures.ts +59 -4
- package/src/implement/faults.ts +5 -1
- package/src/implement/index.ts +1 -0
- package/src/implement/invocation.ts +62 -11
- package/src/implement/principal.ts +25 -2
- package/src/implement/terminals.ts +93 -0
- package/src/implement/tokens.ts +4 -2
- package/src/implement/types.ts +22 -4
- package/src/implement/workload.ts +42 -16
- package/src/jobs/mail.ts +8 -0
- package/src/jobs/report.ts +5 -1
- package/src/jobs/runner.ts +702 -126
- package/src/jobs/schedule.ts +7 -1
- package/src/jobs/scrub.ts +14 -1
- package/src/jobs/types.ts +6 -0
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +331 -169
- package/src/testing/index.ts +1 -1
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +86 -4
- package/src/testing/policy-isolation.ts +2 -2
- package/src/testing/proxy.ts +15 -10
- package/types/src/agent-skill.d.ts +29 -0
- package/types/src/build-recipe.d.ts +70 -0
- package/types/src/build.d.ts +29 -0
- package/types/src/bun.d.ts +99 -0
- package/types/src/client/caller.d.ts +19 -0
- package/types/src/client/contract.d.ts +131 -0
- package/types/src/client/error-reporting.d.ts +66 -0
- package/types/src/client/index.d.ts +4 -0
- package/types/src/client/rpc.d.ts +14 -0
- package/types/src/client/share.d.ts +2 -0
- package/types/src/client/transport.d.ts +42 -0
- package/types/src/cloudflare/application.d.ts +73 -0
- package/types/src/cloudflare/bindings.d.ts +33 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +47 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +11 -0
- package/types/src/cloudflare/ops.d.ts +81 -0
- package/types/src/cloudflare/r2-files.d.ts +9 -0
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +43 -0
- package/types/src/contract/app-id.d.ts +2 -0
- package/types/src/contract/artifact-schema.d.ts +10 -0
- package/types/src/contract/attachment.d.ts +41 -0
- package/types/src/contract/build.d.ts +12 -0
- package/types/src/contract/capability-cases.d.ts +9 -0
- package/types/src/contract/compile.d.ts +11 -0
- package/types/src/contract/connect.d.ts +51 -0
- package/types/src/contract/containers.d.ts +3 -0
- package/types/src/contract/context.d.ts +525 -0
- package/types/src/contract/declaration.d.ts +307 -0
- package/types/src/contract/defaults.d.ts +226 -0
- package/types/src/contract/define.d.ts +376 -0
- package/types/src/contract/file.d.ts +44 -0
- package/types/src/contract/group.d.ts +274 -0
- package/types/src/contract/handled.d.ts +18 -0
- package/types/src/contract/index.d.ts +20 -0
- package/types/src/contract/kit.d.ts +211 -0
- package/types/src/contract/platform.d.ts +9 -0
- package/types/src/contract/problems.d.ts +14 -0
- package/types/src/contract/redirect.d.ts +25 -0
- package/types/src/contract/schema-from-shape.d.ts +10 -0
- package/types/src/contract/schema-shape.d.ts +5 -0
- package/types/src/contract/snapshot-source.d.ts +15 -0
- package/types/src/contract/token.d.ts +58 -0
- package/types/src/contract/vocabulary.d.ts +32 -0
- package/types/src/contract/webhook-binding.d.ts +24 -0
- package/types/src/contract/webhook-scheme.d.ts +23 -0
- package/types/src/dev/changes.d.ts +7 -0
- package/types/src/dev/contract-digest.d.ts +1 -0
- package/types/src/dev/index.d.ts +2 -0
- package/types/src/dev/launcher.d.ts +32 -0
- package/types/src/dev/output.d.ts +28 -0
- package/types/src/dev/wire.d.ts +126 -0
- package/types/src/disk-assets.d.ts +6 -0
- package/types/src/errors.d.ts +46 -0
- package/types/src/fetch.d.ts +7 -0
- package/types/src/files/archive.d.ts +26 -0
- package/types/src/files/clamscan.d.ts +32 -0
- package/types/src/files/handle.d.ts +107 -0
- package/types/src/files/job-names.d.ts +9 -0
- package/types/src/files/kinds.d.ts +112 -0
- package/types/src/files/scan.d.ts +78 -0
- package/types/src/files/sniff.d.ts +7 -0
- package/types/src/files/streams.d.ts +17 -0
- package/types/src/files/treatment.d.ts +18 -0
- package/types/src/from-row.d.ts +20 -0
- package/types/src/honeypot.d.ts +2 -0
- package/types/src/implement/anonymous.d.ts +24 -0
- package/types/src/implement/attachment.d.ts +14 -0
- package/types/src/implement/boot.d.ts +128 -0
- package/types/src/implement/bounded.d.ts +32 -0
- package/types/src/implement/browser-config.d.ts +19 -0
- package/types/src/implement/capability.d.ts +142 -0
- package/types/src/implement/challenge.d.ts +75 -0
- package/types/src/implement/client-address.d.ts +11 -0
- package/types/src/implement/connect.d.ts +67 -0
- package/types/src/implement/crashes.d.ts +31 -0
- package/types/src/implement/dispatch.d.ts +251 -0
- package/types/src/implement/egress.d.ts +14 -0
- package/types/src/implement/environment.d.ts +14 -0
- package/types/src/implement/failures.d.ts +58 -0
- package/types/src/implement/faults.d.ts +48 -0
- package/types/src/implement/headers.d.ts +7 -0
- package/types/src/implement/implement.d.ts +58 -0
- package/types/src/implement/index.d.ts +25 -0
- package/types/src/implement/invocation.d.ts +136 -0
- package/types/src/implement/membership.d.ts +201 -0
- package/types/src/implement/multipart.d.ts +36 -0
- package/types/src/implement/params.d.ts +7 -0
- package/types/src/implement/principal.d.ts +57 -0
- package/types/src/implement/project.d.ts +11 -0
- package/types/src/implement/public.d.ts +61 -0
- package/types/src/implement/serve.d.ts +25 -0
- package/types/src/implement/terminals.d.ts +33 -0
- package/types/src/implement/tokens.d.ts +49 -0
- package/types/src/implement/types.d.ts +263 -0
- package/types/src/implement/urls.d.ts +15 -0
- package/types/src/implement/verifiers.d.ts +19 -0
- package/types/src/implement/webhook.d.ts +55 -0
- package/types/src/implement/workload.d.ts +61 -0
- package/types/src/implement/xlsx.d.ts +6 -0
- package/types/src/index.d.ts +12 -0
- package/types/src/jobs/exception.d.ts +40 -0
- package/types/src/jobs/mail.d.ts +67 -0
- package/types/src/jobs/report.d.ts +56 -0
- package/types/src/jobs/runner.d.ts +218 -0
- package/types/src/jobs/schedule.d.ts +17 -0
- package/types/src/jobs/scrub.d.ts +12 -0
- package/types/src/jobs/types.d.ts +98 -0
- package/types/src/react/caller.d.ts +30 -0
- package/types/src/react/errors.d.ts +40 -0
- package/types/src/react/hooks.d.ts +110 -0
- package/types/src/react/index.d.ts +5 -0
- package/types/src/react/provider.d.ts +58 -0
- package/types/src/react/store.d.ts +68 -0
- package/types/src/react/testing.d.ts +28 -0
- package/types/src/react/types.d.ts +33 -0
- package/types/src/rpc/builder.d.ts +52 -0
- package/types/src/rpc/contract.d.ts +23 -0
- package/types/src/rpc/dispatcher.d.ts +11 -0
- package/types/src/rpc/types.d.ts +62 -0
- package/types/src/service/define.d.ts +42 -0
- package/types/src/service/index.d.ts +3 -0
- package/types/src/service/serve.d.ts +28 -0
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/standard-schema.d.ts +55 -0
- package/types/src/testing/caller.d.ts +95 -0
- package/types/src/testing/challenge.d.ts +11 -0
- package/types/src/testing/dev.d.ts +97 -0
- package/types/src/testing/endpoint-access.d.ts +132 -0
- package/types/src/testing/index.d.ts +12 -0
- package/types/src/testing/isolation.d.ts +3 -0
- package/types/src/testing/kit.d.ts +207 -0
- package/types/src/testing/membership.d.ts +132 -0
- package/types/src/testing/policy-isolation.d.ts +113 -0
- package/types/src/testing/preload.d.ts +1 -0
- package/types/src/testing/proxy.d.ts +40 -0
- package/types/src/testing/runner.d.ts +8 -0
- package/types/src/testing/sample-file.d.ts +5 -0
- package/types/src/testing/status.d.ts +4 -0
- package/types/src/undumpable.d.ts +5 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fabrika/app",
|
|
3
|
-
"version": "0.9.0-dev.
|
|
3
|
+
"version": "0.9.0-dev.10",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -14,87 +14,93 @@
|
|
|
14
14
|
"files": [
|
|
15
15
|
"src",
|
|
16
16
|
"skill",
|
|
17
|
-
"!src/**/__tests__/**"
|
|
17
|
+
"!src/**/__tests__/**",
|
|
18
|
+
"types"
|
|
18
19
|
],
|
|
19
20
|
"exports": {
|
|
20
21
|
".": {
|
|
21
22
|
"bun": "./src/index.ts",
|
|
22
|
-
"types": "./src/index.ts",
|
|
23
|
+
"types": "./types/src/index.d.ts",
|
|
23
24
|
"default": "./src/index.ts"
|
|
24
25
|
},
|
|
25
26
|
"./bun": {
|
|
26
27
|
"bun": "./src/bun.ts",
|
|
27
|
-
"types": "./src/bun.ts",
|
|
28
|
+
"types": "./types/src/bun.d.ts",
|
|
28
29
|
"default": "./src/bun.ts"
|
|
29
30
|
},
|
|
30
31
|
"./cloudflare": {
|
|
31
32
|
"bun": "./src/cloudflare.ts",
|
|
32
|
-
"types": "./src/cloudflare.ts",
|
|
33
|
+
"types": "./types/src/cloudflare.d.ts",
|
|
33
34
|
"default": "./src/cloudflare.ts"
|
|
34
35
|
},
|
|
35
36
|
"./contract": {
|
|
36
37
|
"bun": "./src/contract/index.ts",
|
|
37
|
-
"types": "./src/contract/index.ts",
|
|
38
|
+
"types": "./types/src/contract/index.d.ts",
|
|
38
39
|
"default": "./src/contract/index.ts"
|
|
39
40
|
},
|
|
40
41
|
"./client": {
|
|
41
42
|
"bun": "./src/client/index.ts",
|
|
42
|
-
"types": "./src/client/index.ts",
|
|
43
|
+
"types": "./types/src/client/index.d.ts",
|
|
43
44
|
"default": "./src/client/index.ts"
|
|
44
45
|
},
|
|
45
46
|
"./react": {
|
|
46
47
|
"bun": "./src/react/index.ts",
|
|
47
|
-
"types": "./src/react/index.ts",
|
|
48
|
+
"types": "./types/src/react/index.d.ts",
|
|
48
49
|
"default": "./src/react/index.ts"
|
|
49
50
|
},
|
|
50
51
|
"./react/testing": {
|
|
51
52
|
"bun": "./src/react/testing.ts",
|
|
52
|
-
"types": "./src/react/testing.ts",
|
|
53
|
+
"types": "./types/src/react/testing.d.ts",
|
|
53
54
|
"default": "./src/react/testing.ts"
|
|
54
55
|
},
|
|
55
56
|
"./implement": {
|
|
56
57
|
"bun": "./src/implement/index.ts",
|
|
57
|
-
"types": "./src/implement/index.ts",
|
|
58
|
+
"types": "./types/src/implement/index.d.ts",
|
|
58
59
|
"default": "./src/implement/index.ts"
|
|
59
60
|
},
|
|
60
61
|
"./service": {
|
|
61
62
|
"bun": "./src/service/index.ts",
|
|
62
|
-
"types": "./src/service/index.ts",
|
|
63
|
+
"types": "./types/src/service/index.d.ts",
|
|
63
64
|
"default": "./src/service/index.ts"
|
|
64
65
|
},
|
|
65
66
|
"./build": {
|
|
66
67
|
"bun": "./src/build.ts",
|
|
67
|
-
"types": "./src/build.ts",
|
|
68
|
+
"types": "./types/src/build.d.ts",
|
|
68
69
|
"default": "./src/build.ts"
|
|
69
70
|
},
|
|
70
71
|
"./testing": {
|
|
71
72
|
"bun": "./src/testing/index.ts",
|
|
72
|
-
"types": "./src/testing/index.ts",
|
|
73
|
+
"types": "./types/src/testing/index.d.ts",
|
|
73
74
|
"default": "./src/testing/index.ts"
|
|
74
75
|
},
|
|
75
76
|
"./testing/isolation": {
|
|
76
77
|
"bun": "./src/testing/isolation.ts",
|
|
77
|
-
"types": "./src/testing/isolation.ts",
|
|
78
|
+
"types": "./types/src/testing/isolation.d.ts",
|
|
78
79
|
"default": "./src/testing/isolation.ts"
|
|
79
80
|
},
|
|
80
81
|
"./testing/preload": {
|
|
81
82
|
"bun": "./src/testing/preload.ts",
|
|
82
|
-
"types": "./src/testing/preload.ts",
|
|
83
|
+
"types": "./types/src/testing/preload.d.ts",
|
|
83
84
|
"default": "./src/testing/preload.ts"
|
|
84
85
|
},
|
|
85
86
|
"./dev": {
|
|
86
87
|
"bun": "./src/dev/index.ts",
|
|
87
|
-
"types": "./src/dev/index.ts",
|
|
88
|
+
"types": "./types/src/dev/index.d.ts",
|
|
88
89
|
"default": "./src/dev/index.ts"
|
|
89
90
|
},
|
|
90
91
|
"./dev/wire": {
|
|
91
92
|
"bun": "./src/dev/wire.ts",
|
|
92
|
-
"types": "./src/dev/wire.ts",
|
|
93
|
+
"types": "./types/src/dev/wire.d.ts",
|
|
93
94
|
"default": "./src/dev/wire.ts"
|
|
94
95
|
},
|
|
96
|
+
"./dev/changes": {
|
|
97
|
+
"bun": "./src/dev/changes.ts",
|
|
98
|
+
"types": "./types/src/dev/changes.d.ts",
|
|
99
|
+
"default": "./src/dev/changes.ts"
|
|
100
|
+
},
|
|
95
101
|
"./agent-skill": {
|
|
96
102
|
"bun": "./src/agent-skill.ts",
|
|
97
|
-
"types": "./src/agent-skill.ts",
|
|
103
|
+
"types": "./types/src/agent-skill.d.ts",
|
|
98
104
|
"default": "./src/agent-skill.ts"
|
|
99
105
|
}
|
|
100
106
|
},
|
|
@@ -103,14 +109,14 @@
|
|
|
103
109
|
"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
|
|
104
110
|
},
|
|
105
111
|
"dependencies": {
|
|
106
|
-
"@fabrika/auth": "0.9.0-dev.
|
|
107
|
-
"@fabrika/auth-core": "0.9.0-dev.
|
|
108
|
-
"@fabrika/db": "0.9.0-dev.
|
|
109
|
-
"@fabrika/email": "0.9.0-dev.
|
|
110
|
-
"@fabrika/jwks": "0.9.0-dev.
|
|
111
|
-
"@fabrika/platform": "0.9.0-dev.
|
|
112
|
-
"@fabrika/platform-node": "0.9.0-dev.
|
|
113
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
112
|
+
"@fabrika/auth": "0.9.0-dev.10",
|
|
113
|
+
"@fabrika/auth-core": "0.9.0-dev.10",
|
|
114
|
+
"@fabrika/db": "0.9.0-dev.10",
|
|
115
|
+
"@fabrika/email": "0.9.0-dev.10",
|
|
116
|
+
"@fabrika/jwks": "0.9.0-dev.10",
|
|
117
|
+
"@fabrika/platform": "0.9.0-dev.10",
|
|
118
|
+
"@fabrika/platform-node": "0.9.0-dev.10",
|
|
119
|
+
"@fabrika/proxy-core": "0.9.0-dev.10",
|
|
114
120
|
"altcha-lib": "2.6.0",
|
|
115
121
|
"jose": "^5.9.0"
|
|
116
122
|
},
|
package/skill/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fabrika-app
|
|
3
|
-
version: 0.9.0-dev.
|
|
3
|
+
version: 0.9.0-dev.10
|
|
4
4
|
description: >
|
|
5
5
|
How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
|
|
6
6
|
slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
|
|
@@ -30,6 +30,7 @@ below. When it does not reach far enough, declare the step off it. A declared st
|
|
|
30
30
|
| `fabrika.contract.ts` | `app.contract((c) => ({ api: c.rpc('/api', { … }), … }))`: mounts the groups |
|
|
31
31
|
| `src/app.ts` | `export default serve(contract, { database: scoped(tables) })` and nothing else |
|
|
32
32
|
| `web/` | the SPA: React over `@fabrika/app/react` and `@fabrika/ui`, never a server module |
|
|
33
|
+
| `tools/` | a developer's tools, such as a command line; the application never loads them |
|
|
33
34
|
|
|
34
35
|
## The paved road
|
|
35
36
|
|
|
@@ -233,14 +234,15 @@ the access check. `references/spa.md` shows the stack.
|
|
|
233
234
|
| an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to exactly those origins |
|
|
234
235
|
| a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
|
|
235
236
|
| a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
|
|
236
|
-
| a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`
|
|
237
|
+
| a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
|
|
237
238
|
| a trigger, function or view | its migration | — |
|
|
238
239
|
|
|
239
|
-
Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', '<alias>')}`,
|
|
240
|
-
of its WHERE or JOIN … ON (`where (<filter>) and ${…}`): `ctx.target` for `on` and `in`, `ctx.within` for
|
|
241
|
-
job's minted `Ref` or `Within` with `tx.sql.scope`. It binds the capability's whole predicate, chain
|
|
242
|
-
handles apply it
|
|
243
|
-
|
|
240
|
+
Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', { alias: '<alias>' })}`,
|
|
241
|
+
a conjunct of its WHERE or JOIN … ON (`where (<filter>) and ${…}`): `ctx.target` for `on` and `in`, `ctx.within` for
|
|
242
|
+
`over`, a job's minted `Ref` or `Within` with `tx.sql.scope`. It binds the capability's whole predicate, chain
|
|
243
|
+
included, as the handles apply it. The table an `update` or `delete` writes takes `{ use: 'update' }` or
|
|
244
|
+
`{ use: 'delete' }`, which needs that operation's action; a reference table needs none. The runtime does not check
|
|
245
|
+
where you put a fragment: the approver reads it. A deviation is fine: declare it, and do not contort the code to avoid it. The approver sees every declaration
|
|
244
246
|
marked "needs closer review". Do not hide reach in a helper; the runtime builds `ctx.sql` and `ctx.db.unscoped` only
|
|
245
247
|
where they are declared. A query or an export declares only `'read'`.
|
|
246
248
|
|
|
@@ -255,10 +257,13 @@ Which promise the types, the checker, boot, the runtime or the approver keeps, a
|
|
|
255
257
|
- An endpoint never sends e-mail; it has no `ctx.mail`. It records an outbox row, declares `kicks: ['<job>']` and calls `ctx.kick('<job>')`, which
|
|
256
258
|
starts that job once its transaction committed. The job declares `mailer` and sends with `ctx.mail`, under a key
|
|
257
259
|
derived from the row, and sends again only where `ctx.mail.mayRetry(error)` allows it (`references/jobs.md`).
|
|
258
|
-
- No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`.
|
|
260
|
+
- No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`. A developer's tool
|
|
261
|
+
under `tools/` (a command line that calls a deployed environment with a service key) may read the environment and
|
|
262
|
+
spawn a process; it still has no `as`, `any` or key literal, the application never imports it, and `tools/` holds
|
|
263
|
+
no `package.json`. Its tests run in the platform build, so they test its logic, without a keychain or a network.
|
|
259
264
|
- Never log an error object, a request, headers or the environment.
|
|
260
265
|
- Never edit a generated file (`src/db/schema.generated.ts`, the generated tests, `fabrika/entry.generated.ts`,
|
|
261
|
-
`fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
|
|
266
|
+
`fabrika/migrations.generated.ts`, `fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
|
|
262
267
|
|
|
263
268
|
## Ask the human first
|
|
264
269
|
|
|
@@ -295,11 +300,36 @@ bunx tsc --noEmit # once, at the end
|
|
|
295
300
|
bunx fabrika-check . # once, after tsc; refusals fail; hints print below them
|
|
296
301
|
```
|
|
297
302
|
|
|
303
|
+
**On Cloudflare** (`fabrika.config.ts` imports `defineApp` from `@fabrika/provider-cloudflare`, as
|
|
304
|
+
`references/app-setup.md` shows) the application runs in one Durable Object over SQLite. Its `db/migrations/*.sql` are SQLite (`references/table-and-migration.md`), and the
|
|
305
|
+
object applies them when it boots, so there is no `migrate` and no command needs a database URL or `FABRIKA_APP_ID`.
|
|
306
|
+
The tests run on `@fabrika/db/testing-sqlite` (`references/tests.md`), in memory, and never skip. A handler holds the
|
|
307
|
+
object's transaction, so its `limits.timeoutMs` is at most 25 s. A job's is at most 14 minutes, its default: longer
|
|
308
|
+
work claims a bounded batch per run, and the next run takes the rest (`references/jobs.md`). `ctx.sql` is SQLite there
|
|
309
|
+
(`references/endpoint.md`). No `scan: true`: the checker, the deploy and the boot refuse it. A migration names no
|
|
310
|
+
`fabrika_*` table but `REFERENCES fabrika_files (id)`. The deploy serves each SPA mount's
|
|
311
|
+
built `dir` itself; declare no `assets` on the Worker (`references/app-setup.md`).
|
|
312
|
+
|
|
313
|
+
The object runs one transaction at a time, so every `await` in a handler that may write holds the whole environment:
|
|
314
|
+
IAM, R2, a `fetch`, a `ctx.connect` call, a binding. One 2 s call caps the environment at half a request a second. A
|
|
315
|
+
query holds no transaction: each of its statements runs on its own, so two of its reads may see different committed
|
|
316
|
+
states. Inside a
|
|
317
|
+
mutation keep I/O to the framework's own: IAM, and the file it writes. A slow outside call goes into a row, the
|
|
318
|
+
mutation calls `ctx.kick('<job>')`, and the job makes the call outside `ctx.transaction` (`references/jobs.md`). The
|
|
319
|
+
checker hints on a mutation that declares `egress` or `connect` (`cloudflare-held-call`), and refuses
|
|
320
|
+
`DEFAULT CURRENT_TIMESTAMP` in a migration (`cloudflare-current-timestamp`).
|
|
321
|
+
|
|
322
|
+
```bash
|
|
323
|
+
bunx fabrika db new <slug> # a new SQLite migration file
|
|
324
|
+
bunx fabrika db codegen # applies the migrations in memory; writes src/db/schema.generated.ts
|
|
325
|
+
bunx fabrika db test-scaffold # the generated tests, on @fabrika/db/testing-sqlite
|
|
326
|
+
bun test --isolate # no database URL; then tsc and fabrika-check as above
|
|
327
|
+
```
|
|
328
|
+
|
|
298
329
|
A generated file changes only through its command (`codegen`, `test-scaffold`); running it is the loop, not an edit.
|
|
299
330
|
Format and lint only the files you wrote, with the repository's own tools: in the fabrika-platform repository
|
|
300
|
-
`bunx dprint fmt <files>` and `bunx
|
|
301
|
-
|
|
302
|
-
repository configures, or none, and never add a configuration unasked; tsc and `fabrika-check` are its gates. `FABRIKA_APP_ID` is lowercase letters, digits and `-`. An applied file is immutable: while you still
|
|
331
|
+
`bunx dprint fmt <files>` and `bunx oxlint <files>`, and never a generated file. An application outside that
|
|
332
|
+
repository has neither configuration: use the formatter its own repository configures, or none, and never add a configuration unasked; tsc and `fabrika-check` are its gates. `FABRIKA_APP_ID` is lowercase letters, digits and `-`. An applied file is immutable: while you still
|
|
303
333
|
change an uncommitted migration, migrate into a fresh schema with another `FABRIKA_APP_ID`. Read a refusal's
|
|
304
334
|
"allowed form" and use it; fix hints too. `references/errors.md` explains the findings and the type errors.
|
|
305
335
|
|
|
@@ -326,9 +356,10 @@ e-mails them, a link holder's files, HR's review with its history.
|
|
|
326
356
|
|
|
327
357
|
## Not built yet
|
|
328
358
|
|
|
329
|
-
-
|
|
330
|
-
|
|
331
|
-
|
|
359
|
+
- On Cloudflare, where the application runs in one Durable Object over its SQLite and its `db/migrations/*.sql` are
|
|
360
|
+
SQLite, a file kind with `scan: true` is refused. Everything else on the road runs there.
|
|
361
|
+
- Jobs are cron only and app-wide: no `ctx.jobs.enqueue`, no job per scope. A `ctx.kick` starts a run of its job, now
|
|
362
|
+
or at `{ at }`; it carries nothing, and the job finds its work in a queue table with `claim`. A list write is off the road (`sql`).
|
|
332
363
|
- A read across tables (a join, a filter over a related table, an aggregate over several) is off the road (`sql`).
|
|
333
364
|
- An MCP workspace has no shell, so `codegen` and `test-scaffold` cannot run there. Tell the human; never write a
|
|
334
365
|
generated file by hand.
|
|
@@ -19,22 +19,22 @@ the SPA is added with it.
|
|
|
19
19
|
"test": "bun test --isolate"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@fabrika/app": "0.9.0-dev.
|
|
23
|
-
"@fabrika/db": "0.9.0-dev.
|
|
24
|
-
"@fabrika/provider-zerops": "0.9.0-dev.
|
|
25
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
26
|
-
"@fabrika/ui": "0.9.0-dev.
|
|
22
|
+
"@fabrika/app": "0.9.0-dev.10",
|
|
23
|
+
"@fabrika/db": "0.9.0-dev.10",
|
|
24
|
+
"@fabrika/provider-zerops": "0.9.0-dev.10",
|
|
25
|
+
"@fabrika/proxy-core": "0.9.0-dev.10",
|
|
26
|
+
"@fabrika/ui": "0.9.0-dev.10",
|
|
27
27
|
"kysely": "0.29.6",
|
|
28
28
|
"react": "^19.0.0",
|
|
29
29
|
"react-dom": "^19.0.0",
|
|
30
30
|
"zod": "^3.25.76"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
|
-
"@fabrika/check": "0.9.0-dev.
|
|
34
|
-
"@fabrika/cli": "0.9.0-dev.
|
|
35
|
-
"@fabrika/platform": "0.9.0-dev.
|
|
33
|
+
"@fabrika/check": "0.9.0-dev.10",
|
|
34
|
+
"@fabrika/cli": "0.9.0-dev.10",
|
|
35
|
+
"@fabrika/platform": "0.9.0-dev.10",
|
|
36
36
|
"@happy-dom/global-registrator": "^20.11.2",
|
|
37
|
-
"@types/bun": "
|
|
37
|
+
"@types/bun": "^1.4.3",
|
|
38
38
|
"@types/react": "^19.0.0",
|
|
39
39
|
"@types/react-dom": "^19.0.0",
|
|
40
40
|
"typescript": "^5.9.3"
|
|
@@ -249,6 +249,35 @@ The platform's build runs the tests, writes the entrypoint, runs `fabrika-check`
|
|
|
249
249
|
run `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server starts: a
|
|
250
250
|
version does not go live until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
|
|
251
251
|
|
|
252
|
+
## The deploy surface (Cloudflare)
|
|
253
|
+
|
|
254
|
+
```ts fabrika.config.ts
|
|
255
|
+
import { defineApp } from '@fabrika/provider-cloudflare'
|
|
256
|
+
|
|
257
|
+
export default defineApp({ id: 'tasks' })
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
That is the whole config. `defineApp` builds the application Worker: named after the id, running
|
|
261
|
+
`fabrika/entry.generated.ts`, with no route and no public URL, and IAM bound at its application entrypoint. The deploy
|
|
262
|
+
builds the proxy Worker from `fabrika.contract.ts` and writes the application's Durable Object, its files bucket, its
|
|
263
|
+
cron trigger and every `FABRIKA_*` variable; Control writes the IAM schema from the approved contract. Declare none of
|
|
264
|
+
them: a config that does is refused. Write no `resources`, `schema` or `pipeline.workerDir` (the config's directory is
|
|
265
|
+
the default). A binding of the application's own, or another `compatibility_date` or `compatibility_flags`, goes in
|
|
266
|
+
`worker: { bindings, compatibility_date, compatibility_flags }`; `IAM` stays the platform's. `package.json` names
|
|
267
|
+
`@fabrika/provider-cloudflare` where the Zerops one names `@fabrika/provider-zerops`, the entry is written by
|
|
268
|
+
`fabrika app build --provider=cloudflare` (the deploy runs it again from the pinned commit), and there is no
|
|
269
|
+
`zerops.yaml`.
|
|
270
|
+
|
|
271
|
+
It also serves the SPA: the deploy copies the build directory of each SPA and
|
|
272
|
+
link mount (`dir`, a link's `spa`) into `fabrika/assets/` at the mount's prefix (`/admin` into `fabrika/assets/admin/`)
|
|
273
|
+
after `pipeline.build`, and binds it as `ASSETS`. A `.assetsignore` at the root of a mount's directory excludes files
|
|
274
|
+
as it does for wrangler (gitignore syntax, relative to that directory); `.git`, `.hg`, `.svn` and `.bzr` are never
|
|
275
|
+
copied. A deploy whose mount directory the build did not write fails and
|
|
276
|
+
names the mount. A config that composes its own Worker with `resources` and declares `assets` keeps them instead, and the object reads each
|
|
277
|
+
request path from that directory as it is (`/admin/app.js` is `admin/app.js` there), so a hand-written `assets` works
|
|
278
|
+
only for a root mount, or for mounts whose directories nest like their prefixes; it needs `binding: 'ASSETS'` and
|
|
279
|
+
`run_worker_first: true`.
|
|
280
|
+
|
|
252
281
|
## The SPA (added when the application has one)
|
|
253
282
|
|
|
254
283
|
The SPA is React, built from the screens and hooks of the framework: `@fabrika/app/react` runs the typed client's
|
|
@@ -379,8 +408,9 @@ await Bun.write(
|
|
|
379
408
|
`src/schemas.ts`, `src/shared/` and its own modules; never a slice, `src/db/` or a Bun or Node module. The plugin loads the
|
|
380
409
|
contract without its handlers. A row type the screen declares (`Task` above) is checked against the answer where
|
|
381
410
|
the rows are passed in.
|
|
382
|
-
- The last step points the page's assets at the SPA's prefix (`/`): the mount answers `index.html` for every
|
|
383
|
-
under it, so a deep link such as `/tasks/<id>` renders
|
|
411
|
+
- The last step points the page's assets at the SPA's prefix (`/`): the mount answers `index.html` for every page
|
|
412
|
+
route under it (a path without an extension, or a navigation), so a deep link such as `/tasks/<id>` renders; a
|
|
413
|
+
missing asset such as an old `chunk-….js` is 404. `define` gives React's production build.
|
|
384
414
|
- `sourcemap: 'external'` writes each script's map beside it, and the page names none. The platform build uploads the
|
|
385
415
|
maps to Operations for the release the page reports, so an error's frames show the original source; the mount
|
|
386
416
|
never serves a `.map` file (404). Keep the maps external: `inline` would ship the source to every visitor.
|
|
@@ -397,4 +427,5 @@ await Bun.write(
|
|
|
397
427
|
|
|
398
428
|
## Ignored files
|
|
399
429
|
|
|
400
|
-
`.gitignore`: `node_modules/`, `fabrika.manifest.json`, `/fabrika/entry.generated.ts`, `/dist
|
|
430
|
+
`.gitignore`: `node_modules/`, `fabrika.manifest.json`, `/fabrika/entry.generated.ts`, `/dist/`, and on Cloudflare
|
|
431
|
+
`/fabrika/assets/`, where a deploy stages the SPA's files.
|
package/skill/references/dev.md
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# references/dev.md — previewing the application with `fabrika app dev`
|
|
2
2
|
|
|
3
3
|
`bunx fabrika app dev` serves the application on `http://127.0.0.1:3000/` through its test kit: the proxy decision,
|
|
4
|
-
the stand-in IAM, a throwaway schema of `FABRIKA_TEST_POSTGRES_URL
|
|
4
|
+
the stand-in IAM, a throwaway schema of `FABRIKA_TEST_POSTGRES_URL` (on Cloudflare an in-memory SQLite database,
|
|
5
|
+
without a URL), and each SPA from its build (run
|
|
5
6
|
`bun run build:web` first). Use it to look at the screens, never in place of a test.
|
|
6
7
|
|
|
7
8
|
## The seed
|
|
@@ -52,7 +53,9 @@ export default seed
|
|
|
52
53
|
- Check every call the seed makes: an endpoint that refuses answers a status, and the seed goes on without its data.
|
|
53
54
|
Throw when one does: a seed that throws stops `app dev` and prints its error with the stack.
|
|
54
55
|
- `dev.runJob('<job>')` runs a cron job from the seed (`app dev` runs none on its schedule). A job's `ctx.links` works:
|
|
55
|
-
the stand-in IAM takes the job's own key. What a
|
|
56
|
+
the stand-in IAM takes the job's own key. What a request's 5xx or a job attempt threw is printed with its stack, here
|
|
57
|
+
only, after the log line that names its code and reason: your handler's own error, or a framework refusal with its
|
|
58
|
+
own message (a refused `ctx.sql` names its line).
|
|
56
59
|
|
|
57
60
|
## Outside the application
|
|
58
61
|
|
|
@@ -144,7 +144,11 @@ copyToTask: r.mutation({
|
|
|
144
144
|
(`on` 404, `in` and `over` 403).
|
|
145
145
|
- The handler binds each with `ctx.db.on(…)`, `ctx.db.in(…)` or `ctx.db.over(…)`. It has no `ctx.target`,
|
|
146
146
|
`ctx.within`, `ctx.db.app`, `ctx.members` or `ctx.links`.
|
|
147
|
-
- The
|
|
147
|
+
- The `from` fields are gone from `input`, as under a single `on` or `in`: `input.toTaskId` is a type error. Each id
|
|
148
|
+
is its capability's value, `ctx.capabilities.to.value`.
|
|
149
|
+
- The generated tests add a denied case per capability, except an `over` one whose action another one needs on its
|
|
150
|
+
dimension, a container of it or a dimension inside it: every caller that passes that one is answered the list. Two
|
|
151
|
+
capabilities may share an action. A join or a lock over many rows still needs `sql`.
|
|
148
152
|
|
|
149
153
|
### The methods of each handle
|
|
150
154
|
|
|
@@ -188,9 +192,10 @@ picker of the org a new project goes into; an `'all'` caller types the org inste
|
|
|
188
192
|
- `list({ where, orderBy, limit, after })` answers `{ items, next }`: a keyset page of at most `limit` rows (50 by
|
|
189
193
|
default, 500 at most). Pass `next` back as `after`; it is `null` on the last page.
|
|
190
194
|
- `where` is AND of `[column, operator, value]`: `=`, `<>`, `<`, `<=`, `>`, `>=`, `in` and `not in` (a list),
|
|
191
|
-
`like`, `ilike`, `not like`, `not ilike`, `contains
|
|
195
|
+
`like`, `ilike`, `not like`, `not ilike`, `contains`, and `is` and `is not` with `null` on a nullable column
|
|
196
|
+
(`['processed_at', 'is', null]`). Optional filters are conditional spreads, each tuple
|
|
192
197
|
`as const` (`list` in `SKILL.md`): `...(input.status === undefined ? [] : [['status', '=', input.status] as const])`.
|
|
193
|
-
There is no
|
|
198
|
+
There is no OR: write that in `ctx.sql`. `count` and a queue table's `claim` (`references/jobs.md`) take the same `where`.
|
|
194
199
|
- `orderBy` is `[[column, 'asc' | 'desc']]`; the key is added last as the tiebreak.
|
|
195
200
|
- `count({ where })` answers a number. `aggregate({ groupBy, count, sum, min, max })` takes lists of column names
|
|
196
201
|
and answers one row per group: the `groupBy` columns, `count` as a string (Postgres `bigint`), and `sum_<column>`,
|
|
@@ -406,7 +411,7 @@ export const workloadRows = (
|
|
|
406
411
|
count(*) filter (where t.status <> 'done')::int as open,
|
|
407
412
|
count(*) filter (where t.status <> 'done' and t.due_on < current_date)::int as overdue
|
|
408
413
|
from tasks t
|
|
409
|
-
where ${sql.scope(org, 'tasks', 't')}
|
|
414
|
+
where ${sql.scope(org, 'tasks', { alias: 't' })}
|
|
410
415
|
and (${status}::text is null or t.status::text = ${status})
|
|
411
416
|
group by t.assignee
|
|
412
417
|
order by t.assignee`
|
|
@@ -420,8 +425,8 @@ export const workloadRows = (
|
|
|
420
425
|
|
|
421
426
|
## Raw SQL: `sql: 'read'`
|
|
422
427
|
|
|
423
|
-
Raw SQL is legitimate for a join, a report, an `OR`
|
|
424
|
-
`ctx.sql` exists only there.
|
|
428
|
+
Raw SQL is legitimate for a join, a report, an `OR` filter, or a bulk write. Declare it on the endpoint;
|
|
429
|
+
`ctx.sql` exists only there. It runs on Postgres and, on Cloudflare, on SQLite (the rules of each are below).
|
|
425
430
|
|
|
426
431
|
```ts src/reports/endpoints.ts
|
|
427
432
|
import { attachment } from '@fabrika/app/contract'
|
|
@@ -475,7 +480,7 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
|
|
|
475
480
|
const rows = await ctx.sql(TaskExportRow)`
|
|
476
481
|
select t.title, t.status, t.assignee, t.due_on::text as due_on
|
|
477
482
|
from tasks t
|
|
478
|
-
where ${ctx.sql.scope(ctx.target, 'tasks', 't')}
|
|
483
|
+
where ${ctx.sql.scope(ctx.target, 'tasks', { alias: 't' })}
|
|
479
484
|
order by t.title
|
|
480
485
|
limit 10000`
|
|
481
486
|
await ctx.db.target.project_exports.insert({ row_count: rows.length })
|
|
@@ -487,7 +492,7 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
|
|
|
487
492
|
- Every `${…}` of a value is a bound parameter, never SQL text. The one exception is `${ctx.sql.scope(…)}`: it is SQL
|
|
488
493
|
(the predicate) around its own bound values, and it may have no value at all (`(true)`, `(false)`). Put no
|
|
489
494
|
interpolation inside quotes, a quoted name, a dollar body or a comment: the tag refuses it.
|
|
490
|
-
- **Scope every scoped table the statement reads with `${ctx.sql.scope(capability, '<table>', '<alias>')}`.**
|
|
495
|
+
- **Scope every scoped table the statement reads with `${ctx.sql.scope(capability, '<table>', { alias: '<alias>' })}`.**
|
|
491
496
|
`ctx.sql` has no scope predicate of its own. The fragment is the capability's whole predicate on that table: for a
|
|
492
497
|
`Ref` the object's column and every link of its chain, so a project moved to another org is out; for a `Within` its
|
|
493
498
|
values, each container grant on its own column, every row for a global grant and none for an empty one. The
|
|
@@ -495,29 +500,31 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
|
|
|
495
500
|
`Within` it minted to `tx.sql.scope`. A table the capability does not reach is a type error at the table name. A
|
|
496
501
|
reference table is shared by every scope and needs no fragment, and no statement writes it. An application table
|
|
497
502
|
needs none either (the intake job of `references/public-intake.md`).
|
|
498
|
-
- **A fragment
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
endpoint with `sql` leaks nothing of another scope.
|
|
503
|
+
- **A fragment states what it scopes.** `use` is `'read'` by default; the table an `update` or `delete` writes takes
|
|
504
|
+
`{ use: 'update' }` or `{ use: 'delete' }`, which needs the table's own update or delete action
|
|
505
|
+
(`ctx.within('tasks.write', 'project')` for `update tasks`) on a `'write'` site, so a read action never scopes a
|
|
506
|
+
write. A column's own write action (`columns: { assignee: { write: 'tasks.assign' } }`) is enough for `use: 'update'`
|
|
507
|
+
too; set only the columns it writes. `insert … on conflict do update … where ${…}` scopes the inserted table with
|
|
508
|
+
`use: 'update'`. Each block takes its own fragment: a CTE that updates and a statement that deletes take one
|
|
509
|
+
capability each, and another occurrence of the written table (a subquery, `from tasks other`) reads under its own
|
|
510
|
+
alias. A refused fragment fails the call before anything is sent.
|
|
511
|
+
- **A fragment is a conjunct.** Put it alone, joined by AND, at the top level of a WHERE or JOIN … ON clause whose top
|
|
512
|
+
level holds no OR: `where (<the whole filter>) and ${…}`, `join projects p on p.id = t.project_id and ${…}`. The tag
|
|
513
|
+
does not read where it stands, which relation it filters or which columns a `set` assigns: the approver does, and a
|
|
514
|
+
fragment under an `or` widens the statement to every row. Never scope by hand with `ctx.target.value` alone: it drops
|
|
515
|
+
the chain. The generated tests check that an `in` endpoint with `sql` leaks nothing of another scope.
|
|
512
516
|
- Rows are parsed like `fromRow` (snake_case to camelCase), then by the schema. Postgres sends `bigint` and `numeric`
|
|
513
517
|
as text: cast a count (`count(*)::int`), and a sum to the type its output declares (`::int` for an integer sum that
|
|
514
518
|
fits, `::float8` for a fractional one), or keep it a string. A sum over no rows is `null`: `coalesce(sum(…), 0)`.
|
|
515
519
|
- An optional filter is `(${value}::text is null or <column> = ${value})`.
|
|
516
520
|
- One statement: `select`, `with`, `values`, plus `insert`, `update` and `delete` on a `'write'` site (a mutation, a
|
|
517
|
-
job or a webhook). Refused before anything is sent: DDL, `SET`, `COPY`, transaction control,
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
-
|
|
521
|
+
job or a webhook). Refused before anything is sent: DDL, `SET`, `COPY`, transaction control, and any `fabrika_*`
|
|
522
|
+
name. On Postgres also another schema, any `pg_*` name, and calls outside the reviewed built-ins; a function your migrations declare is refused too: call it from a view. On SQLite also any `sqlite_*`
|
|
523
|
+
name, `PRAGMA`, `ATTACH`, and a parameter you write yourself (`?`, `:x`, `@x`, `$x`): interpolate every value.
|
|
524
|
+
- On SQLite write SQLite: `count(*)` is already an integer, there is no `::` cast (`cast(x as text)`), and a list value
|
|
525
|
+
binds as JSON (`t.status in (select value from json_each(${list}))`).
|
|
526
|
+
- A query runs in a read-only transaction; a mutation's `ctx.sql` runs in the same transaction as its handles. A
|
|
527
|
+
`'read'` statement writes nothing, even in a mutation: one that tries fails the call.
|
|
521
528
|
|
|
522
529
|
## A file download: `attachment`
|
|
523
530
|
|
|
@@ -564,7 +571,7 @@ Every procedure takes `admission` (who may send it, how often) and `limits` (how
|
|
|
564
571
|
| `admission.origins` | `'same-origin'` (default) or `'listed'` | `'same-origin'`, `'listed'` or `'any'` |
|
|
565
572
|
| `admission.challenge` | none | `{ provider: 'altcha', secret, action?, cost?, maxAgeMs? }`, or `{ provider: 'turnstile', secret, siteKey, action? }` |
|
|
566
573
|
| `limits.maxBytes` | 64 KiB, at most 1 MiB; with file fields 64 KiB plus each file at its kind's `maxBytes`, at most 48 MiB | the same |
|
|
567
|
-
| `limits.timeoutMs` | 10 s, at most 60 s
|
|
574
|
+
| `limits.timeoutMs` | 10 s, at most 60 s; at most 25 s on Cloudflare | the same |
|
|
568
575
|
|
|
569
576
|
- A declared `rate` merges into the default; `null` turns one bucket off. Past a bucket the answer is 429.
|
|
570
577
|
- Every bucket is charged before the body is read and stays charged whatever the handler does. A bucket is a database
|
|
@@ -642,7 +649,7 @@ export const app = defineApp(vocabulary, tables, {
|
|
|
642
649
|
- A public procedure updates or removes a row only by an id a verified token of its request carries, with
|
|
643
650
|
`expectVersion`.
|
|
644
651
|
- Single use and revocation are your state (a row the token names). The keys are the platform's: Control generates
|
|
645
|
-
and rotates them, and an old key verifies until its last token expires.
|
|
652
|
+
and rotates them, and an old key verifies until its last token expires.
|
|
646
653
|
|
|
647
654
|
## Outside calls: `egress`
|
|
648
655
|
|
|
@@ -652,6 +659,10 @@ refused while the site runs (`capability_refused: undeclared_egress`). A public,
|
|
|
652
659
|
none. The checker's `cross-app-fetch` accepts an absolute URL only under an origin some site declares. The approver
|
|
653
660
|
sees every origin. The guard stops mistakes; it is no sandbox.
|
|
654
661
|
|
|
662
|
+
On Cloudflare a procedure waits for its outside call inside the object's transaction, so the whole environment waits
|
|
663
|
+
with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
|
|
664
|
+
`ctx.transaction` (`references/jobs.md`).
|
|
665
|
+
|
|
655
666
|
## Links to your own procedures: `ctx.url`
|
|
656
667
|
|
|
657
668
|
`ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
|