@fabrika/app 0.9.0-dev.12 → 0.9.0-dev.14
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 +7 -4
- package/skill/references/app-setup.md +15 -8
- package/skill/references/endpoint.md +7 -1
- package/skill/references/errors.md +7 -6
- package/skill/references/jobs.md +10 -0
- package/skill/references/relations.md +682 -0
- package/skill/references/table-and-migration.md +18 -7
- package/skill/references/webhooks-links-connectors.md +2 -1
- package/src/bun.ts +10 -0
- package/src/contract/artifact-schema.ts +82 -1
- package/src/contract/build.ts +142 -12
- package/src/contract/compile.ts +1 -0
- package/src/contract/declaration.ts +4 -0
- package/src/contract/define.ts +12 -0
- package/src/contract/group.ts +10 -1
- package/src/contract/kit.ts +3 -1
- package/src/contract/platform.ts +1 -0
- package/src/contract/vocabulary.ts +3 -0
- package/src/disk-assets.ts +15 -3
- package/src/implement/boot.ts +59 -5
- package/src/implement/capability.ts +91 -6
- package/src/implement/dispatch.ts +334 -17
- package/src/implement/egress.ts +409 -9
- package/src/implement/implement.ts +28 -1
- package/src/implement/invocation.ts +10 -9
- package/src/implement/types.ts +15 -4
- package/src/implement/webhook.ts +8 -0
- package/src/jobs/runner.ts +7 -2
- package/src/source-map-path.ts +21 -0
- package/src/testing/caller.ts +20 -2
- package/src/testing/membership.ts +9 -5
- package/types/src/contract/declaration.d.ts +6 -0
- package/types/src/contract/define.d.ts +15 -0
- package/types/src/contract/group.d.ts +9 -1
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/contract/vocabulary.d.ts +4 -1
- package/types/src/implement/boot.d.ts +6 -0
- package/types/src/implement/capability.d.ts +14 -5
- package/types/src/implement/dispatch.d.ts +20 -1
- package/types/src/implement/egress.d.ts +36 -1
- package/types/src/implement/implement.d.ts +24 -1
- package/types/src/implement/invocation.d.ts +3 -3
- package/types/src/implement/types.d.ts +13 -3
- package/types/src/jobs/runner.d.ts +3 -0
- package/types/src/source-map-path.d.ts +4 -0
- package/types/src/testing/caller.d.ts +6 -1
- package/types/src/testing/membership.d.ts +1 -1
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.14",
|
|
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-dev.
|
|
113
|
-
"@fabrika/auth-core": "0.9.0-dev.
|
|
114
|
-
"@fabrika/db": "0.9.0-dev.
|
|
115
|
-
"@fabrika/email": "0.9.0-dev.
|
|
116
|
-
"@fabrika/jwks": "0.9.0-dev.
|
|
117
|
-
"@fabrika/platform": "0.9.0-dev.
|
|
118
|
-
"@fabrika/platform-node": "0.9.0-dev.
|
|
119
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
112
|
+
"@fabrika/auth": "0.9.0-dev.14",
|
|
113
|
+
"@fabrika/auth-core": "0.9.0-dev.14",
|
|
114
|
+
"@fabrika/db": "0.9.0-dev.14",
|
|
115
|
+
"@fabrika/email": "0.9.0-dev.14",
|
|
116
|
+
"@fabrika/jwks": "0.9.0-dev.14",
|
|
117
|
+
"@fabrika/platform": "0.9.0-dev.14",
|
|
118
|
+
"@fabrika/platform-node": "0.9.0-dev.14",
|
|
119
|
+
"@fabrika/proxy-core": "0.9.0-dev.14",
|
|
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-dev.
|
|
3
|
+
version: 0.9.0-dev.14
|
|
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
|
|
@@ -232,6 +232,7 @@ the access check. `references/spa.md` shows the stack.
|
|
|
232
232
|
| e-mail (a cron job only) | `mailer: 'installation'` | `ctx.mail.send` |
|
|
233
233
|
| a file from a public procedure | `file('<kind>')` input, `admission` with `bytesPerHour` | a reference the handler writes into a file column |
|
|
234
234
|
| an outside HTTPS API | `egress: ['https://api.example.com']` | `fetch` to those (`https://*.<domain>`: one label) |
|
|
235
|
+
| any public website (a job) | `egress: 'public'` | `fetch` to public hosts, never the installation |
|
|
235
236
|
| a signed link (unsubscribe) | `signs: ['<purpose>']` | `ctx.tokens.sign` |
|
|
236
237
|
| a webhook binding | `binds: '<webhook>'` | `ctx.webhooks('<webhook>').bind` and `.unbind` |
|
|
237
238
|
| a job run after the commit | `kicks: ['<job>']` | `ctx.kick('<job>')`, `ctx.kick('<job>', { at })` |
|
|
@@ -349,10 +350,12 @@ their errors, the caller, the components, routing, theming, screen tests), `tabl
|
|
|
349
350
|
`ctx.url`, a mount's `compatibility`, another origin, members and labels), `tests.md` (generated tests, seeds, `testKit`, a reused scope, a caller's label, confirming a file ran),
|
|
350
351
|
`errors.md` (checker findings, type errors, runtime answers), `dev.md` (the seed and the preview), `jobs.md` (which dimension `ctx.within` names, the UTC
|
|
351
352
|
day, queue tables and `claim`, e-mail through `ctx.mail` with attachments and unsubscribe, the outbox and `kicks`),
|
|
352
|
-
`files.md` and `webhooks-links-connectors.md`, all under `references/`.
|
|
353
|
+
`files.md` and `webhooks-links-connectors.md`, all under `references/`. Three are applications of their own:
|
|
353
354
|
`start.md`, a new application before its first table (its first test, adding the first table, installing and updating
|
|
354
|
-
this skill),
|
|
355
|
-
e-mails them, a link holder's files, HR's review with its history.
|
|
355
|
+
this skill), `public-intake.md`, a public page, public procedures, a job that claims their rows, issues links and
|
|
356
|
+
e-mails them, a link holder's files, HR's review with its history, and `relations.md`, access that rows of the
|
|
357
|
+
application grant and narrow (a relation, a role's `via`, a source table's `confers` and `assign`, a table's `when`
|
|
358
|
+
conditions, `readThrough`, `reveals` and `memberReveals`).
|
|
356
359
|
|
|
357
360
|
## Not built yet
|
|
358
361
|
|
|
@@ -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-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.14",
|
|
23
|
+
"@fabrika/db": "0.9.0-dev.14",
|
|
24
|
+
"@fabrika/provider-zerops": "0.9.0-dev.14",
|
|
25
|
+
"@fabrika/proxy-core": "0.9.0-dev.14",
|
|
26
|
+
"@fabrika/ui": "0.9.0-dev.14",
|
|
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.14",
|
|
34
|
+
"@fabrika/cli": "0.9.0-dev.14",
|
|
35
|
+
"@fabrika/platform": "0.9.0-dev.14",
|
|
36
36
|
"@happy-dom/global-registrator": "^20.11.2",
|
|
37
37
|
"@types/bun": "^1.4.3",
|
|
38
38
|
"@types/react": "^19.0.0",
|
|
@@ -245,6 +245,13 @@ zerops:
|
|
|
245
245
|
- bun run build:web
|
|
246
246
|
```
|
|
247
247
|
|
|
248
|
+
`build.base` must be a Bun that reads the committed `bun.lock`: the build installs with `--frozen-lockfile`, and an
|
|
249
|
+
older Bun fails it with `Unknown lockfile version`. A `bun.lock` that Bun 1.4 creates or regenerates has
|
|
250
|
+
`"lockfileVersion": 2`, which needs `alpine/bun@1.4`; versions 0 and 1 build on `alpine/bun@1.3`, which is also the
|
|
251
|
+
base without `build.base`. Raise `build.base` to `alpine/bun@1.4` rather than regenerate the lockfile with Bun 1.3, which
|
|
252
|
+
resolves every dependency afresh. `fabrika app build` refuses a base that cannot read the lockfile and names the one to
|
|
253
|
+
use.
|
|
254
|
+
|
|
248
255
|
The platform's build runs the tests, writes the entrypoint, runs `fabrika-check` and the type check. Its init commands
|
|
249
256
|
run `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server starts: a
|
|
250
257
|
version does not go live until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
|
|
@@ -671,6 +671,11 @@ On Cloudflare a procedure waits for its outside call inside the object's transac
|
|
|
671
671
|
with it (`SKILL.md`). A mutation records a row and kicks a job, which declares the `egress` and calls outside
|
|
672
672
|
`ctx.transaction` (`references/jobs.md`).
|
|
673
673
|
|
|
674
|
+
A cron job that calls hosts nobody knows when the contract is written (the websites its operators enter: a crawler, an
|
|
675
|
+
auditor, a link checker) declares `egress: 'public'` instead of a list (`references/jobs.md`). Only a cron job may: a
|
|
676
|
+
procedure, a mutation and a webhook name their origins. Never keep `fetch` from before boot or open sockets to get past
|
|
677
|
+
the list; that is hidden reach.
|
|
678
|
+
|
|
674
679
|
## Links to your own procedures: `ctx.url`
|
|
675
680
|
|
|
676
681
|
`ctx.url('<endpoint id>', { input?, query? })` builds an absolute URL of one of the application's own procedures, on
|
|
@@ -698,7 +703,8 @@ containing it, that declares `members`: a task endpoint reads its org's. A dimen
|
|
|
698
703
|
`member.principalId` and `member.label`, never a label from the input.
|
|
699
704
|
- `disabled` is a person an operator disabled in IAM: still a member, but unable to sign in. Refuse to assign one
|
|
700
705
|
(`assign` in `SKILL.md`), and leave them out of a picker.
|
|
701
|
-
- The approver sees each endpoint that
|
|
706
|
+
- The approver sees each endpoint that can read a directory ("can look up one member of `org`"): the first one of an
|
|
707
|
+
action and its callers widens; another endpoint of the same action and callers is shown as unchanged.
|
|
702
708
|
- With the directory's `members.list` action (`tasks.read` here) also `ctx.members.list()`, answering
|
|
703
709
|
`{ principalId, label, roles, disabled }` per member, for an assignee picker. IAM checks that action on the org
|
|
704
710
|
itself too.
|
|
@@ -31,7 +31,8 @@ The refusals agents meet most, and their fix:
|
|
|
31
31
|
| `skipped-test` | `.skip`, `.only`, `.todo` | run the test |
|
|
32
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
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
|
-
| `
|
|
34
|
+
| `access-view-key` | a table that names an access view has no single-column primary or unique key on its key | a `PRIMARY KEY` or `UNIQUE` on that column alone (`references/relations.md`) |
|
|
35
|
+
| `cross-app-fetch` | a `fetch` of an absolute URL under no origin a site declares in `egress`, or one a job's `egress: 'public'` refuses (an IP address, `localhost`) | `egress: ['https://…']` on the site that calls it (`references/endpoint.md`) |
|
|
35
36
|
| `url-endpoint` | `ctx.url('<id>')` names no procedure of the contract | the endpoint id `<mount>.<group>.<procedure>` |
|
|
36
37
|
| `cloudflare-scan` | on Cloudflare, a file kind with `scan: true` | the kind without `scan`, and no public procedure that takes its files |
|
|
37
38
|
| `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 |
|
|
@@ -112,11 +113,11 @@ message. The refusal's own message names the place (`'sqlite_master' at line 2`,
|
|
|
112
113
|
(`references/tests.md`). The codes
|
|
113
114
|
you meet most:
|
|
114
115
|
|
|
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`),
|
|
119
|
-
| `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it
|
|
116
|
+
| Code | Means |
|
|
117
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
118
|
+
| `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 |
|
|
119
|
+
| `capability_refused` | a capability of another kind, dimension or action than the call takes (`wrong_capability`, `wrong_action`, `out_of_reach`), one kept past its request (`ended`, `foreign_work`), or a `fetch` its `egress` refuses (`undeclared_egress`, `refused_egress`, `oversized_egress`, `encoded_egress`) |
|
|
120
|
+
| `handler_failed` | your handler threw something else; the log has no more: the Operations issue has the stack, `app dev` prints it |
|
|
120
121
|
|
|
121
122
|
With an Operations DSN the same 500 is a `RequestFailed` issue in Operations. Its event also carries what your handler
|
|
122
123
|
threw: the error's type, its message, its stack and its `cause` chain. Read the stack there, not in the log. A crash
|
package/skill/references/jobs.md
CHANGED
|
@@ -144,6 +144,16 @@ 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`), read whole before `fetch` answers; a
|
|
154
|
+
compressed answer is refused (`encoded_egress`: the guard asks for `identity`); pass `ctx.signal`, or
|
|
155
|
+
`AbortSignal.any([ctx.signal, AbortSignal.timeout(8_000)])` for a shorter bound per page. The approver reviews it
|
|
156
|
+
closely, as reach to anywhere public. Keep the sites operators enter in a table the job reads.
|
|
147
157
|
- `ctx.signal` aborts when the attempt ends (its timeout, a lost lease). Call `ctx.signal.throwIfAborted()` before
|
|
148
158
|
each external effect and pass the signal to `fetch`, so a stale attempt starts nothing after its replacement.
|
|
149
159
|
- A failed attempt names its failure in `kit.runJob`'s answer and the log: `handler_failed`, a framework failure
|