@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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fabrika/app",
|
|
3
|
-
"version": "0.9.0-
|
|
3
|
+
"version": "0.9.0-dev.10",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -109,14 +109,14 @@
|
|
|
109
109
|
"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
|
|
110
110
|
},
|
|
111
111
|
"dependencies": {
|
|
112
|
-
"@fabrika/auth": "0.9.0-
|
|
113
|
-
"@fabrika/auth-core": "0.9.0-
|
|
114
|
-
"@fabrika/db": "0.9.0-
|
|
115
|
-
"@fabrika/email": "0.9.0-
|
|
116
|
-
"@fabrika/jwks": "0.9.0-
|
|
117
|
-
"@fabrika/platform": "0.9.0-
|
|
118
|
-
"@fabrika/platform-node": "0.9.0-
|
|
119
|
-
"@fabrika/proxy-core": "0.9.0-
|
|
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",
|
|
120
120
|
"altcha-lib": "2.6.0",
|
|
121
121
|
"jose": "^5.9.0"
|
|
122
122
|
},
|
package/skill/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fabrika-app
|
|
3
|
-
version: 0.9.0-
|
|
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
|
|
|
@@ -231,7 +232,6 @@ the access check. `references/spa.md` shows the stack.
|
|
|
231
232
|
| e-mail (a cron job only) | `mailer: 'installation'` | `ctx.mail.send` |
|
|
232
233
|
| a file from a public procedure | `file('<kind>')` input, `admission` with `bytesPerHour` | a reference the handler writes into a file column |
|
|
233
234
|
| an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to exactly those origins |
|
|
234
|
-
| any public website (a job) | `egress: 'public'` | `fetch` to public hosts, never the installation |
|
|
235
235
|
| a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
|
|
236
236
|
| a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
|
|
237
237
|
| a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
|
|
@@ -257,7 +257,10 @@ Which promise the types, the checker, boot, the runtime or the approver keeps, a
|
|
|
257
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
|
|
258
258
|
starts that job once its transaction committed. The job declares `mailer` and sends with `ctx.mail`, under a key
|
|
259
259
|
derived from the row, and sends again only where `ctx.mail.mayRetry(error)` allows it (`references/jobs.md`).
|
|
260
|
-
- 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.
|
|
261
264
|
- Never log an error object, a request, headers or the environment.
|
|
262
265
|
- Never edit a generated file (`src/db/schema.generated.ts`, the generated tests, `fabrika/entry.generated.ts`,
|
|
263
266
|
`fabrika/migrations.generated.ts`, `fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
|
|
@@ -19,20 +19,20 @@ the SPA is added with it.
|
|
|
19
19
|
"test": "bun test --isolate"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@fabrika/app": "0.9.0-
|
|
23
|
-
"@fabrika/db": "0.9.0-
|
|
24
|
-
"@fabrika/provider-zerops": "0.9.0-
|
|
25
|
-
"@fabrika/proxy-core": "0.9.0-
|
|
26
|
-
"@fabrika/ui": "0.9.0-
|
|
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-
|
|
34
|
-
"@fabrika/cli": "0.9.0-
|
|
35
|
-
"@fabrika/platform": "0.9.0-
|
|
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
37
|
"@types/bun": "^1.4.3",
|
|
38
38
|
"@types/react": "^19.0.0",
|
package/skill/references/dev.md
CHANGED
|
@@ -53,7 +53,9 @@ export default seed
|
|
|
53
53
|
- Check every call the seed makes: an endpoint that refuses answers a status, and the seed goes on without its data.
|
|
54
54
|
Throw when one does: a seed that throws stops `app dev` and prints its error with the stack.
|
|
55
55
|
- `dev.runJob('<job>')` runs a cron job from the seed (`app dev` runs none on its schedule). A job's `ctx.links` works:
|
|
56
|
-
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).
|
|
57
59
|
|
|
58
60
|
## Outside the application
|
|
59
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>`,
|
|
@@ -420,7 +425,7 @@ 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`
|
|
428
|
+
Raw SQL is legitimate for a join, a report, an `OR` filter, or a bulk write. Declare it on the endpoint;
|
|
424
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
|
|
@@ -658,11 +663,6 @@ On Cloudflare a procedure waits for its outside call inside the object's transac
|
|
|
658
663
|
with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
|
|
659
664
|
`ctx.transaction` (`references/jobs.md`).
|
|
660
665
|
|
|
661
|
-
A cron job that calls hosts nobody knows when the contract is written (the websites its operators enter: a crawler, an
|
|
662
|
-
auditor, a link checker) declares `egress: 'public'` instead of a list (`references/jobs.md`). Only a cron job may: a
|
|
663
|
-
procedure, a mutation and a webhook name their origins. Never keep `fetch` from before boot or open sockets to get past
|
|
664
|
-
the list; that is hidden reach.
|
|
665
|
-
|
|
666
666
|
## Links to your own procedures: `ctx.url`
|
|
667
667
|
|
|
668
668
|
`ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
|
|
@@ -8,33 +8,37 @@ architecture, and a refusal's allowed form is the one fix that passes. There is
|
|
|
8
8
|
|
|
9
9
|
The refusals agents meet most, and their fix:
|
|
10
10
|
|
|
11
|
-
| Rule | Means | Fix
|
|
12
|
-
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
13
|
-
| `literal` | the shell (contract, vocabulary, tables, groups, schemas) holds a computed value or call | literal objects, `z.*` calls and imported literal consts; move logic into `.handle(…)`
|
|
14
|
-
| `contract` | the contract does not compile (a reserved role, an unknown action, a wrong field) | the message names the field
|
|
15
|
-
| `package-replacement` | `package.json` names the app under `@fabrika/*`, or a dependency is `workspace:*` | another name; a registry range such as `^0.0.4`
|
|
16
|
-
| `generated-test-hash` | a generated test is missing, edited or stale | `bunx fabrika db test-scaffold`, and commit what it writes
|
|
17
|
-
| `endpoint-fixture` | an endpoint's input cannot be sampled, a fixture or seed names no endpoint, a member, invitation or link field no endpoint that reads, cancels or revokes one, a file names no file field or a path outside the application, or a refusal is `validation` | a literal in `src/__tests__/endpoint-access.fixtures.ts` (`references/tests.md`)
|
|
18
|
-
| `raw-sql` | a driver's `sql` (imported from `bun`, Kysely, `postgres`) | the handles, or `sql: 'read'` and `ctx.sql`
|
|
19
|
-
| `forbidden-import` | a driver, an S3 client, `jose`, `node:http`, `child_process` | the handles, a file column with `ctx.files`, a connector
|
|
20
|
-
| `forbidden-global` | `Bun.sql`, `Bun.serve`, `Bun.spawn`; `globalThis`, `window`, `self`, `global` or `Bun` in a server module | the handles; state lives in a table, not in a global; `crypto.randomUUID()` for an id
|
|
21
|
-
| `env-read` | `process.env`, `Bun.env` | `defineDeps(build)`, which receives the application's variables
|
|
22
|
-
| `client-identity` | an input field `userId`, `ownerId`, `createdBy`, `tenantId`, `workspaceId` | the access form's `from`, `ctx.principal.id`, or `createdBy` in the policy
|
|
23
|
-
| `type-assertion` | `as T` (other than `as const`), `<T>x` | fix the type; `fromRow` parses a row into a schema's type
|
|
24
|
-
| `sensitive-log` | a log of an error object, a request, headers or the environment | log a short fixed message
|
|
25
|
-
| `migration-name` | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC) | `bunx fabrika db new <slug>`
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
31
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
| `cloudflare-
|
|
37
|
-
| `cloudflare-
|
|
11
|
+
| Rule | Means | Fix |
|
|
12
|
+
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| `literal` | the shell (contract, vocabulary, tables, groups, schemas) holds a computed value or call | literal objects, `z.*` calls and imported literal consts; move logic into `.handle(…)` |
|
|
14
|
+
| `contract` | the contract does not compile (a reserved role, an unknown action, a wrong field) | the message names the field |
|
|
15
|
+
| `package-replacement` | `package.json` names the app under `@fabrika/*`, or a dependency is `workspace:*` | another name; a registry range such as `^0.0.4` |
|
|
16
|
+
| `generated-test-hash` | a generated test is missing, edited or stale | `bunx fabrika db test-scaffold`, and commit what it writes |
|
|
17
|
+
| `endpoint-fixture` | an endpoint's input cannot be sampled, a fixture or seed names no endpoint, a member, invitation or link field no endpoint that reads, cancels or revokes one, a file names no file field or a path outside the application, or a refusal is `validation` | a literal in `src/__tests__/endpoint-access.fixtures.ts` (`references/tests.md`) |
|
|
18
|
+
| `raw-sql` | a driver's `sql` (imported from `bun`, Kysely, `postgres`) | the handles, or `sql: 'read'` and `ctx.sql` |
|
|
19
|
+
| `forbidden-import` | a driver, an S3 client, `jose`, `node:http`, `child_process` | the handles, a file column with `ctx.files`, a connector |
|
|
20
|
+
| `forbidden-global` | `Bun.sql`, `Bun.serve`, `Bun.spawn`; `globalThis`, `window`, `self`, `global` or `Bun` in a server module | the handles; state lives in a table, not in a global; `crypto.randomUUID()` for an id |
|
|
21
|
+
| `env-read` | `process.env`, `Bun.env` | `defineDeps(build)`, which receives the application's variables |
|
|
22
|
+
| `client-identity` | an input field `userId`, `ownerId`, `createdBy`, `tenantId`, `workspaceId` | the access form's `from`, `ctx.principal.id`, or `createdBy` in the policy |
|
|
23
|
+
| `type-assertion` | `as T` (other than `as const`), `<T>x` | fix the type; `fromRow` parses a row into a schema's type |
|
|
24
|
+
| `sensitive-log` | a log of an error object, a request, headers or the environment | log a short fixed message |
|
|
25
|
+
| `migration-name` | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC) | `bunx fabrika db new <slug>` |
|
|
26
|
+
| `migration-edited` | a migration already on the main branch, edited (even a comment), renamed or deleted | restore the file; put the change in a new migration (`bunx fabrika db new <slug>`) |
|
|
27
|
+
| `test-only-import` | `@fabrika/app/testing`, `@fabrika/app/react/testing`, `@fabrika/db/testing` or `@fabrika/db/testing-sqlite` outside a test file | import them only from `*.test.ts` or `__tests__/` |
|
|
28
|
+
| `spa-server-import` | the SPA loads a server module | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
|
|
29
|
+
| `shared-import` | a module under `src/shared/` loads a slice, `src/db/`, `@fabrika/*` or a builtin | a shared module imports `zod/v4` and other shared modules only |
|
|
30
|
+
| `tool-import` | a module outside `tools/` loads a developer's tool under `tools/` | move what both need under `src/` (`src/shared/`) and import it from the tool |
|
|
31
|
+
| `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
|
|
32
|
+
| `file-column-migration` | a file column without `REFERENCES fabrika_files (id)` or without an index it leads | both, in a new migration (`references/table-and-migration.md`) |
|
|
33
|
+
| `on-conflict-index` | `insert(…, { onConflict: { columns } })` whose columns are no unique index the migrations create | a `UNIQUE` constraint or a `CREATE UNIQUE INDEX` without `WHERE` on exactly those columns |
|
|
34
|
+
| `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress` | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
|
|
35
|
+
| `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
|
|
36
|
+
| `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
|
|
37
|
+
| `cloudflare-job-segment` | on Cloudflare, a job whose `limits.timeoutMs` exceeds one 14-minute segment | at most 14 minutes: claim a bounded batch per run, and the next run takes the rest |
|
|
38
|
+
| `cloudflare-current-timestamp` | on Cloudflare, `DEFAULT CURRENT_TIMESTAMP` in a migration: SQLite stores `YYYY-MM-DD HH:MM:SS`, which every read of the table refuses | `DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`, in a new migration |
|
|
39
|
+
| `cloudflare-framework-name` | on Cloudflare, a `fabrika_*` name in a migration, quoted or not | your own tables, and `REFERENCES fabrika_files (id)` for a file column |
|
|
40
|
+
| `migration-refused` | a migration statement Control refuses (a function, an object or a form the platform does not admit) | a new migration that does without it; a key in a SQLite backfill: the UUID expression in `table-and-migration.md` |
|
|
41
|
+
| `backup-schema` | on Cloudflare, a schema the backup cannot copy: a key back into its own table that a `CHECK` reads, or that is `NOT NULL` | a nullable key no `CHECK` names, or no such key; a new migration, before any further one deploys |
|
|
38
42
|
|
|
39
43
|
The hints:
|
|
40
44
|
|
|
@@ -70,6 +74,7 @@ A kit error lands on the line of the mistake, in one or two lines that name the
|
|
|
70
74
|
| `'member.label' is possibly 'null'` | a nullable column or output; only `directory: 'labels'` makes it text |
|
|
71
75
|
| `admin is a role IAM defines itself for every application (reserved: admin)` | another role name |
|
|
72
76
|
| `Property 'id' does not exist on type 'Ref<…>'` | `ctx.target.value` |
|
|
77
|
+
| `Property 'taskId' does not exist on type '{ … }'` on `input` | `ctx.target.value`, or `ctx.capabilities.<name>.value` |
|
|
73
78
|
| `Property 'margin' does not exist on type 'Omit<DealsTable, "margin">'` | the column has its own read action, which this capability lacks |
|
|
74
79
|
| `Type 'Date' is not assignable to type 'string'` on a `date` column | a `YYYY-MM-DD` string |
|
|
75
80
|
| `Cannot find module '@fabrika/…'` and implicit `any`s everywhere | `bun install` (at the repository root in a monorepo) |
|
|
@@ -102,13 +107,16 @@ with its message; throw the three business errors for the application's own refu
|
|
|
102
107
|
|
|
103
108
|
A 500 answers a fixed message; the server log has one line, `fabrika: <endpoint>: <code>: <reason>: <text>`, with a
|
|
104
109
|
fixed failure code and, for a framework refusal, its reason and the reason's fixed text, never a value or your error's
|
|
105
|
-
message. The
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
|
111
|
-
|
|
|
110
|
+
message. The refusal's own message names the place (`'sqlite_master' at line 2`, the column, the function): for every
|
|
111
|
+
5xx, `fabrika app dev` prints what was thrown after that line, and a test sees it when it passes a sink to the kit
|
|
112
|
+
(`references/tests.md`). The codes
|
|
113
|
+
you meet most:
|
|
114
|
+
|
|
115
|
+
| Code | Means |
|
|
116
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `query_refused` | the data layer refused a statement or an operation: `undeclared_reach`, `sql_read_only`, `unknown_column`, `read_only`, `sql_outside_transaction`, `sql_scope`, `sql_name` …; the reason's text names the rule |
|
|
118
|
+
| `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), or one kept past its request (`ended`, `foreign_work`) |
|
|
119
|
+
| `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it |
|
|
112
120
|
|
|
113
121
|
With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
|
|
114
122
|
threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
|
|
@@ -76,7 +76,8 @@ task_attachments: {
|
|
|
76
76
|
cascade) or clearing a nullable column removes the reference; the framework's sweep deletes a file no column
|
|
77
77
|
references.
|
|
78
78
|
- A file column takes only a file reference: an input file (`file('<kind>')`), a `ctx.files.put` of this request, or a
|
|
79
|
-
reference this request read from a file column under that table's `read` action
|
|
79
|
+
reference this request read from a file column under that table's `read` action (or claimed with its queue row while
|
|
80
|
+
the job declares that action). A string id is refused.
|
|
80
81
|
|
|
81
82
|
```ts src/attachments/endpoints.ts
|
|
82
83
|
import { file } from '@fabrika/app/contract'
|
|
@@ -209,7 +210,8 @@ a view that maps them.
|
|
|
209
210
|
| `put(kind, bytes, { type, name? })` | stores a new file of the kind and answers its reference; it is pending until a column holds it |
|
|
210
211
|
| `open(ref, { maxBytes? })` | `{ id, name, type, size, bytes }` of a live file, read whole |
|
|
211
212
|
|
|
212
|
-
`open` takes a reference the site read from a file column under that table's `read` action
|
|
213
|
+
`open` takes a reference the site read from a file column under that table's `read` action, or a queue row a job
|
|
214
|
+
claimed while it also declares that action (`references/jobs.md`). It answers 409
|
|
213
215
|
`file_not_ready` until the scan called the file clean, 409 `file_rejected` for a rejected one, and 413 for a file over
|
|
214
216
|
`maxBytes` (the kind's by default), before any byte is read. Pass the size you hold in memory.
|
|
215
217
|
|
package/skill/references/jobs.md
CHANGED
|
@@ -144,20 +144,11 @@ export const contract = app.contract((c) => ({
|
|
|
144
144
|
- A job may also declare `kicks` (another job; the edges never form a cycle), `signs` (`ctx.tokens.sign`),
|
|
145
145
|
`egress` (the HTTPS origins its `fetch` calls) and `issues` (`references/endpoint.md`). `ctx.url('<endpoint id>', …)`
|
|
146
146
|
builds an absolute link to one of the application's procedures, for an e-mail.
|
|
147
|
-
- A job that calls the websites its operators enter (a crawler, an auditor) declares `egress: 'public'`:
|
|
148
|
-
`app.cron('*/5 * * * *', { actions: ['sites.read'], egress: 'public' })`. Its `fetch` reaches any public host over
|
|
149
|
-
HTTPS or HTTP on the default port. It is refused (`capability_refused: refused_egress`) for an IP address, a name of
|
|
150
|
-
one label (`localhost`, an internal service), a name under `.local`, `.internal`, `.workers.dev`, `.zerops.app` and similar, a port,
|
|
151
|
-
the installation's own hosts (IAM, Control, Operations, every application's domain) and, on Bun (Zerops), a name
|
|
152
|
-
that resolves to a private address. Every redirect is checked again: `redirect: 'manual'` gets the redirect, the default
|
|
153
|
-
follows at most 10. A request has 60 s, a response body at most 16 MiB (`oversized_egress`); pass `ctx.signal`, or
|
|
154
|
-
`AbortSignal.any([ctx.signal, AbortSignal.timeout(8_000)])` for a shorter bound per page. The approver reviews it
|
|
155
|
-
closely, as reach to anywhere public. Keep the sites operators enter in a table the job reads.
|
|
156
147
|
- `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
|
|
157
148
|
each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
|
|
158
|
-
- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework
|
|
159
|
-
with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action
|
|
160
|
-
or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
|
|
149
|
+
- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework failure
|
|
150
|
+
with its reason (`query_refused: undeclared_reach`, `capability_refused: undeclared_action`,
|
|
151
|
+
`framework_fault: url_unbuildable`; `references/errors.md`), or `mail_failed` with the transport's code (`mail_failed: provider_rejected`).
|
|
161
152
|
|
|
162
153
|
## E-mail: `mailer` and `ctx.mail`
|
|
163
154
|
|
|
@@ -229,9 +220,24 @@ for (const row of await ctx.db.app('mail.send').outbox.claim({ limit: 50 })) {
|
|
|
229
220
|
has come and whose attempts are below `maxAttempts` (10 by default), `for update skip locked`. It adds one attempt
|
|
230
221
|
and moves `<due>` by the backoff: the job's schedule period (60 s without one), doubled per attempt, at most 30
|
|
231
222
|
days. Each row answers its columns, its new `version` and `ref`.
|
|
223
|
+
- `where` takes the conditions of a `list` (`references/endpoint.md`), a null test included: `[['result', 'is', null]]`
|
|
224
|
+
claims only the rows without a result.
|
|
232
225
|
- Claim through the capability you read the table with: `ctx.db.app('<action>').<table>` for an application table,
|
|
233
226
|
`ctx.db.over(ctx.within('<action>', '<dimension>')).<table>` for a scoped one. The action is the table's `update`
|
|
234
227
|
action. `claim` runs only in a job and never inside `ctx.transaction`.
|
|
228
|
+
- A claimed row's file column is a reference the job opens (`ctx.files.open`) only when the job also declares the
|
|
229
|
+
table's `read` action. With only the update action it carries the metadata, and `open` refuses it. A column with
|
|
230
|
+
its own read action is in the claim's answer only when that action is the claim's own, and is then readable.
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
// uploads: read 'uploads.read', update 'uploads.process', files: { file: 'documents' }
|
|
234
|
+
app.cron('*/5 * * * *', { actions: ['uploads.read', 'uploads.process'] }).handle(async ({ ctx }) => {
|
|
235
|
+
for (const row of await ctx.db.app('uploads.process').uploads.claim({ limit: 5 })) {
|
|
236
|
+
const document = await ctx.files.open(row.file)
|
|
237
|
+
…
|
|
238
|
+
}
|
|
239
|
+
})
|
|
240
|
+
```
|
|
235
241
|
- Finish each row in its own transaction through `tx.db.on(row.ref)`: `.update(values, { expectVersion, done: true })`
|
|
236
242
|
writes and clears `<due>`; `.remove({ expectVersion })` deletes the row (the table's delete action);
|
|
237
243
|
`.requeue({ at? })` makes it due again at `at` (now by default) with no attempts, for a dead row or a reminder moved
|
|
@@ -147,7 +147,21 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
|
|
|
147
147
|
- A column with a fixed set of values is an `ENUM` type, not a `CHECK` on text: the generated tests fill text columns
|
|
148
148
|
with markers, which a `CHECK` refuses.
|
|
149
149
|
- Codegen types: `date` is a `YYYY-MM-DD` string; `timestamptz` reads a `Date` and takes a `Date` or a strict ISO 8601 string with `Z` or an offset;
|
|
150
|
-
`int8` and `numeric` are strings; an enum is its literal union.
|
|
150
|
+
`int8` and `numeric` are strings; an enum is its literal union. `bytea`, arrays and domains are refused.
|
|
151
|
+
- A column of JSON is `jsonb` (`json` is refused: it keeps whitespace and duplicate keys). It reads as `unknown`: parse it
|
|
152
|
+
with a zod schema in the handler, never trust its shape. A write takes a JSON value (plain objects and arrays, strings,
|
|
153
|
+
finite numbers, booleans; a `Date`, a `Map` or a class instance is refused), and `null` is SQL NULL. Type a value you
|
|
154
|
+
write with a `type` alias or a zod-inferred type: an `interface` has no index signature, so it is not a
|
|
155
|
+
`JsonColumnValue`. Postgres reorders an object's keys; compare values, not their `JSON.stringify` text. A `where`,
|
|
156
|
+
`orderBy` or aggregate never names a JSON column: read a path of it with `ctx.sql` (`details ->> 'kind'`), and write
|
|
157
|
+
one there as `${JSON.stringify(value)}`.
|
|
158
|
+
- A generated column (`GENERATED ALWAYS AS (…) STORED`) of any type codegen does not type (a `tsvector` for full-text
|
|
159
|
+
search, a `json`, an array, a range) is left out of the generated types instead: every `fabrika db codegen` run,
|
|
160
|
+
`--verify` too, prints `<table>.<column> (<type>, generated) is left out`, and `schema.generated.ts` has a comment
|
|
161
|
+
where the column would stand. No `ctx.db` handle reads or writes it, a policy cannot name it, and only `ctx.sql`
|
|
162
|
+
reaches it. An identity column and a generated column of a type codegen does type are never left out. A left-out
|
|
163
|
+
column in the primary key, a unique key or a foreign key is refused, and so is a table whose every column would be
|
|
164
|
+
left out.
|
|
151
165
|
- Plain SQL of the application's own schema only. Refused: another schema (`public.`, `app_…`), any `fabrika_*`
|
|
152
166
|
object (a file column references `fabrika_files (id)`, `references/files.md`), `GRANT`, roles, `CREATE EXTENSION`, `COPY`,
|
|
153
167
|
`SET`, transaction control, `SECURITY DEFINER`, a domain, `serial` and sequences (use `GENERATED ALWAYS AS IDENTITY`),
|
|
@@ -164,13 +178,26 @@ no URL. The rules above for keys, chains, composite foreign keys, `version` and
|
|
|
164
178
|
database enforces foreign keys.
|
|
165
179
|
|
|
166
180
|
- The declared types codegen reads: `TEXT` (a UUID too), `INTEGER`, `REAL`, `BLOB`; `BOOLEAN`, stored as 0 or 1 and
|
|
167
|
-
read as a boolean; `TIMESTAMP`, stored as UTC ISO text and read as a `Date`; `DATE`, `YYYY-MM-DD` text
|
|
168
|
-
|
|
169
|
-
|
|
181
|
+
read as a boolean; `TIMESTAMP`, stored as UTC ISO text and read as a `Date`; `DATE`, `YYYY-MM-DD` text; `JSONB`,
|
|
182
|
+
stored as JSON text and handled as Postgres's `jsonb` above (`JSON` is refused). Any other declared type is refused.
|
|
183
|
+
A generated column of another declared type (`JSON`) is left out as on Postgres; one with no declared type is
|
|
184
|
+
refused, so declare it. A `STRICT` table admits only `INTEGER`, `REAL`, `TEXT` and `BLOB`, so a table with a
|
|
185
|
+
`BOOLEAN`, `TIMESTAMP`, `DATE` or `JSONB` column is not `STRICT`. `ctx.sql` reads a `JSONB` column as its text, or
|
|
186
|
+
as a number when the value is one; parse the text with `JSON.parse`.
|
|
170
187
|
- SQLite has no `ENUM`: a column with a fixed set of values is `TEXT` with `CHECK (<column> IN ('a', 'b'))`. The
|
|
171
188
|
generated tests write its first value.
|
|
172
189
|
- No transaction control (`BEGIN`, `COMMIT`, `SAVEPOINT`) and no Postgres syntax (`timestamptz`, `::` casts,
|
|
173
190
|
`GENERATED ALWAYS AS IDENTITY`, `CREATE TYPE`).
|
|
191
|
+
- SQLite has no `gen_random_uuid()`. A backfill that inserts rows gives each one a key with this expression, a UUID v4
|
|
192
|
+
that `z.uuid()` accepts (`hex(randomblob(16))` alone is not one). It is random, not time-ordered like the UUIDv7 an
|
|
193
|
+
insert of the data layer stamps, so nothing may depend on the order of these keys.
|
|
194
|
+
|
|
195
|
+
```sql
|
|
196
|
+
INSERT INTO deal_tags (id, deal_id, tag)
|
|
197
|
+
SELECT lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)), 2) || '-'
|
|
198
|
+
|| substr('89ab', 1 + (random() & 3), 1) || substr(hex(randomblob(2)), 2) || '-' || hex(randomblob(6))), id, label
|
|
199
|
+
FROM deals WHERE label IS NOT NULL;
|
|
200
|
+
```
|
|
174
201
|
|
|
175
202
|
## Database code is a declared deviation
|
|
176
203
|
|
|
@@ -10,9 +10,11 @@ longer writes. Commit them; never edit, format or import them (`generated-test-h
|
|
|
10
10
|
every `on` and `over` endpoint, and every `in` endpoint that declares `sql`, answers nothing of another scope; a
|
|
11
11
|
caller with only an endpoint's write action, plus what IAM requires of it (below), reaches its own object (200). An
|
|
12
12
|
`app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder. An
|
|
13
|
-
endpoint of several `capabilities` adds a denied case per capability
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
endpoint of several `capabilities` adds a denied case per capability (none for an `over` one whose action another one
|
|
14
|
+
needs on its dimension, a container of it or a dimension inside it, which gets a `// Not checked:` line instead). A
|
|
15
|
+
public procedure answers anyone without a credential, or, behind a challenge, refuses a caller without a solved one.
|
|
16
|
+
A file input is sent as a generated file of its kind, or as the file the fixtures name (`files`, below); a `GET`
|
|
17
|
+
procedure's input goes in its URL.
|
|
16
18
|
- Their kit stands in for IAM, as `testKit` does (below): it creates a scope, assigns or invites a member and issues a
|
|
17
19
|
link under IAM's rules for the caller's grants. A repeated invitation answers the open one, `resend` restarts its
|
|
18
20
|
7 days, and an organization's address is refused for an external role (`internal_mailbox`). So the caller of an endpoint with the dimension's `members.manage`
|
|
@@ -90,13 +92,19 @@ export const members = { 'api.tasks.assign': ['assignee'] }
|
|
|
90
92
|
other 400 fails the case, and the checker refuses `validation`, an input the schema refuses (`endpoint-fixture`).
|
|
91
93
|
- The endpoint id is `<mount>.<group>.<endpoint>` (`api.tasks.close`).
|
|
92
94
|
- The seed of the tests fills every text column with a marker and every other required column with a sample of its
|
|
93
|
-
type: an enum's first label, `1`, `false`, today. A column
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
95
|
+
type: an enum's first label, `1`, `false`, today. A number column that a `UNIQUE` index or the primary key covers
|
|
96
|
+
gets the next number above the largest among the rows that share the index's other columns with it instead (`1`
|
|
97
|
+
under a fresh parent, `2` for the insert case beside the seeded row; the whole column for a one-column index), so
|
|
98
|
+
the row collides with no row of the table. A column with a `DEFAULT` keeps it (`status` is `open`). A column a
|
|
99
|
+
`CHECK` names gets the first value of an `IN (…)` list, or `null` where it is nullable. A foreign key outside the
|
|
100
|
+
containment chain is `null` where it is nullable, and otherwise references an existing or a seeded row of a
|
|
101
|
+
reference or application table. What the seed cannot satisfy (another `CHECK` on a required text column, a unique
|
|
102
|
+
number column whose type holds no larger number, a `UNIQUE` index whose sampled values another row holds, such as a
|
|
103
|
+
date, an enum or a boolean unique on its own, a required key to a dimension or child table outside the chain) fails
|
|
104
|
+
the test with a `SeedLimitError` that names the constraint: a limit of the generator, not a bug of the handler. The
|
|
105
|
+
numbering reads only a `UNIQUE` index of plain columns with no `WHERE`. A collision the seed does not write itself (a
|
|
106
|
+
non-number column unique within the parent, which the insert case's row shares with the seeded one) answers 500 in
|
|
107
|
+
the insert case. Keep the column as the domain needs it, and ask the human when the limit blocks the tests.
|
|
100
108
|
- A generated case's input is a sample of the schema: no optional field, `null` for a nullable one, an enum's first
|
|
101
109
|
value, the shortest string its bounds admit (`'x'`), the smallest number, `false`, a fixed value for a format
|
|
102
110
|
(`uuid`, `email`, `iso.date`). When that input meets a precondition (`close` of an `open` task is 409), seed the
|
|
@@ -313,6 +321,10 @@ if (postgres !== null) {
|
|
|
313
321
|
- `testKit(app, { membership })` replaces the stand-in with your own `IamMembershipRpc`; that kit accepts no
|
|
314
322
|
invitation. `@fabrika/app/testing` exports the types of the options: `IamMembershipRpc` (`membership`),
|
|
315
323
|
`ChallengeFetch` (`challengeFetch`) and `FileScanner` (`scanner`). Import them from there, beside `testKit`.
|
|
324
|
+
- A 5xx or a failed `kit.runJob` names only its code and reason. To see what was thrown (your handler's error, or a
|
|
325
|
+
refusal's own message: a refused `ctx.sql` names its line, a refused column its name), pass a sink while you debug:
|
|
326
|
+
`testKit(app, { database: postgres.database, revealHandlerErrors: (where, error) => console.error(where, error) })`
|
|
327
|
+
(`HandlerErrorSink`). It is off unless passed.
|
|
316
328
|
- `kit.testCaller(grants, { disabled: true })` is a person an operator disabled: the directory lists and finds them
|
|
317
329
|
with `disabled: true`, so an assignment of them answers your handler's 400, and their own requests are refused (401 for
|
|
318
330
|
a session, 403 for a key).
|
package/src/bun.ts
CHANGED
|
@@ -14,7 +14,6 @@ import { directoryEmailProvider } from '@fabrika/email/directory'
|
|
|
14
14
|
import { parseJwks } from '@fabrika/jwks'
|
|
15
15
|
import type { FileObjectStore } from '@fabrika/platform'
|
|
16
16
|
import { applicationRuntimeUrl, S3BlobStore } from '@fabrika/platform-node'
|
|
17
|
-
import { lookup } from 'node:dns/promises'
|
|
18
17
|
import { diskAssets } from './disk-assets.js'
|
|
19
18
|
import type { FetchService, RequestExecutionContext } from './fetch.js'
|
|
20
19
|
import { clamscanScanner } from './files/clamscan.js'
|
|
@@ -551,7 +550,6 @@ async function startContractServer(
|
|
|
551
550
|
membership,
|
|
552
551
|
terminals,
|
|
553
552
|
workloadTokens,
|
|
554
|
-
resolveHost,
|
|
555
553
|
requireProxySecret: true,
|
|
556
554
|
localEmailProviders: LOCAL_EMAIL_PROVIDERS,
|
|
557
555
|
connections: databaseConnections(environment.framework[DATABASE_CONNECTIONS]) ?? DEFAULT_DATABASE_CONNECTIONS,
|
|
@@ -587,13 +585,6 @@ async function startContractServer(
|
|
|
587
585
|
return { port: server.port ?? port, stop }
|
|
588
586
|
}
|
|
589
587
|
|
|
590
|
-
/**
|
|
591
|
-
* Every address `hostname` resolves to, as the operating system's resolver answers Bun's own `fetch`: a cron job's public
|
|
592
|
-
* egress refuses a hop whose name resolves to any private one (ADR-0071).
|
|
593
|
-
*/
|
|
594
|
-
const resolveHost = async (hostname: string): Promise<readonly string[]> =>
|
|
595
|
-
(await lookup(hostname, { all: true, verbatim: true })).map((entry) => entry.address)
|
|
596
|
-
|
|
597
588
|
/** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
|
|
598
589
|
export function implementationAt(path: string): ImplementationLoader {
|
|
599
590
|
return async () => {
|
|
@@ -640,7 +631,6 @@ export async function runContractJob(
|
|
|
640
631
|
membership,
|
|
641
632
|
terminals,
|
|
642
633
|
workloadTokens,
|
|
643
|
-
resolveHost,
|
|
644
634
|
requireProxySecret: true,
|
|
645
635
|
localEmailProviders: LOCAL_EMAIL_PROVIDERS,
|
|
646
636
|
// ClamAV on PATH, as the provider's build installs it for a `scan: true` file kind; missing, the scan fails closed.
|