@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.
Files changed (222) hide show
  1. package/package.json +32 -26
  2. package/skill/SKILL.md +46 -15
  3. package/skill/references/app-setup.md +43 -12
  4. package/skill/references/dev.md +5 -2
  5. package/skill/references/endpoint.md +39 -28
  6. package/skill/references/errors.md +50 -37
  7. package/skill/references/files.md +8 -4
  8. package/skill/references/jobs.md +39 -7
  9. package/skill/references/table-and-migration.md +47 -3
  10. package/skill/references/tests.md +61 -10
  11. package/skill/references/webhooks-links-connectors.md +1 -1
  12. package/src/build-recipe.ts +198 -0
  13. package/src/build.ts +60 -4
  14. package/src/bun.ts +181 -13
  15. package/src/cloudflare/application.ts +822 -0
  16. package/src/cloudflare/bindings.ts +159 -0
  17. package/src/cloudflare/export.ts +621 -0
  18. package/src/cloudflare/import.ts +888 -0
  19. package/src/cloudflare/maintenance.ts +518 -0
  20. package/src/cloudflare/names.ts +16 -0
  21. package/src/cloudflare/ops.ts +375 -0
  22. package/src/cloudflare/r2-files.ts +172 -0
  23. package/src/cloudflare/restore.ts +167 -0
  24. package/src/cloudflare/tracker.ts +192 -0
  25. package/src/cloudflare.ts +100 -146
  26. package/src/contract/app-id.ts +5 -0
  27. package/src/contract/artifact-schema.ts +9 -1
  28. package/src/contract/build.ts +40 -2
  29. package/src/contract/capability-cases.ts +30 -0
  30. package/src/contract/compile.ts +1 -0
  31. package/src/contract/containers.ts +19 -0
  32. package/src/contract/context.ts +35 -9
  33. package/src/contract/declaration.ts +2 -0
  34. package/src/contract/defaults.ts +22 -2
  35. package/src/contract/define.ts +29 -3
  36. package/src/contract/index.ts +1 -0
  37. package/src/contract/kit.ts +4 -1
  38. package/src/contract/platform.ts +3 -2
  39. package/src/contract/vocabulary.ts +26 -8
  40. package/src/dev/changes.ts +5 -43
  41. package/src/dev/contract-digest.ts +17 -0
  42. package/src/dev/index.ts +1 -1
  43. package/src/dev/launcher.ts +197 -41
  44. package/src/dev/output.ts +13 -3
  45. package/src/dev/wire.ts +11 -1
  46. package/src/disk-assets.ts +8 -3
  47. package/src/files/archive.ts +2 -2
  48. package/src/files/handle.ts +2 -1
  49. package/src/files/job-names.ts +12 -0
  50. package/src/files/kinds.ts +74 -32
  51. package/src/files/scan.ts +3 -4
  52. package/src/files/streams.ts +3 -1
  53. package/src/implement/anonymous.ts +12 -11
  54. package/src/implement/boot.ts +84 -27
  55. package/src/implement/bounded.ts +21 -2
  56. package/src/implement/capability.ts +16 -4
  57. package/src/implement/dispatch.ts +423 -178
  58. package/src/implement/failures.ts +59 -4
  59. package/src/implement/faults.ts +5 -1
  60. package/src/implement/index.ts +1 -0
  61. package/src/implement/invocation.ts +62 -11
  62. package/src/implement/principal.ts +25 -2
  63. package/src/implement/terminals.ts +93 -0
  64. package/src/implement/tokens.ts +4 -2
  65. package/src/implement/types.ts +22 -4
  66. package/src/implement/workload.ts +42 -16
  67. package/src/jobs/mail.ts +8 -0
  68. package/src/jobs/report.ts +5 -1
  69. package/src/jobs/runner.ts +702 -126
  70. package/src/jobs/schedule.ts +7 -1
  71. package/src/jobs/scrub.ts +14 -1
  72. package/src/jobs/types.ts +6 -0
  73. package/src/spa-fallback.ts +12 -0
  74. package/src/testing/endpoint-access.ts +331 -169
  75. package/src/testing/index.ts +1 -1
  76. package/src/testing/isolation.ts +8 -1
  77. package/src/testing/kit.ts +86 -4
  78. package/src/testing/policy-isolation.ts +2 -2
  79. package/src/testing/proxy.ts +15 -10
  80. package/types/src/agent-skill.d.ts +29 -0
  81. package/types/src/build-recipe.d.ts +70 -0
  82. package/types/src/build.d.ts +29 -0
  83. package/types/src/bun.d.ts +99 -0
  84. package/types/src/client/caller.d.ts +19 -0
  85. package/types/src/client/contract.d.ts +131 -0
  86. package/types/src/client/error-reporting.d.ts +66 -0
  87. package/types/src/client/index.d.ts +4 -0
  88. package/types/src/client/rpc.d.ts +14 -0
  89. package/types/src/client/share.d.ts +2 -0
  90. package/types/src/client/transport.d.ts +42 -0
  91. package/types/src/cloudflare/application.d.ts +73 -0
  92. package/types/src/cloudflare/bindings.d.ts +33 -0
  93. package/types/src/cloudflare/export.d.ts +16 -0
  94. package/types/src/cloudflare/import.d.ts +47 -0
  95. package/types/src/cloudflare/maintenance.d.ts +117 -0
  96. package/types/src/cloudflare/names.d.ts +11 -0
  97. package/types/src/cloudflare/ops.d.ts +81 -0
  98. package/types/src/cloudflare/r2-files.d.ts +9 -0
  99. package/types/src/cloudflare/restore.d.ts +9 -0
  100. package/types/src/cloudflare/tracker.d.ts +29 -0
  101. package/types/src/cloudflare.d.ts +43 -0
  102. package/types/src/contract/app-id.d.ts +2 -0
  103. package/types/src/contract/artifact-schema.d.ts +10 -0
  104. package/types/src/contract/attachment.d.ts +41 -0
  105. package/types/src/contract/build.d.ts +12 -0
  106. package/types/src/contract/capability-cases.d.ts +9 -0
  107. package/types/src/contract/compile.d.ts +11 -0
  108. package/types/src/contract/connect.d.ts +51 -0
  109. package/types/src/contract/containers.d.ts +3 -0
  110. package/types/src/contract/context.d.ts +525 -0
  111. package/types/src/contract/declaration.d.ts +307 -0
  112. package/types/src/contract/defaults.d.ts +226 -0
  113. package/types/src/contract/define.d.ts +376 -0
  114. package/types/src/contract/file.d.ts +44 -0
  115. package/types/src/contract/group.d.ts +274 -0
  116. package/types/src/contract/handled.d.ts +18 -0
  117. package/types/src/contract/index.d.ts +20 -0
  118. package/types/src/contract/kit.d.ts +211 -0
  119. package/types/src/contract/platform.d.ts +9 -0
  120. package/types/src/contract/problems.d.ts +14 -0
  121. package/types/src/contract/redirect.d.ts +25 -0
  122. package/types/src/contract/schema-from-shape.d.ts +10 -0
  123. package/types/src/contract/schema-shape.d.ts +5 -0
  124. package/types/src/contract/snapshot-source.d.ts +15 -0
  125. package/types/src/contract/token.d.ts +58 -0
  126. package/types/src/contract/vocabulary.d.ts +32 -0
  127. package/types/src/contract/webhook-binding.d.ts +24 -0
  128. package/types/src/contract/webhook-scheme.d.ts +23 -0
  129. package/types/src/dev/changes.d.ts +7 -0
  130. package/types/src/dev/contract-digest.d.ts +1 -0
  131. package/types/src/dev/index.d.ts +2 -0
  132. package/types/src/dev/launcher.d.ts +32 -0
  133. package/types/src/dev/output.d.ts +28 -0
  134. package/types/src/dev/wire.d.ts +126 -0
  135. package/types/src/disk-assets.d.ts +6 -0
  136. package/types/src/errors.d.ts +46 -0
  137. package/types/src/fetch.d.ts +7 -0
  138. package/types/src/files/archive.d.ts +26 -0
  139. package/types/src/files/clamscan.d.ts +32 -0
  140. package/types/src/files/handle.d.ts +107 -0
  141. package/types/src/files/job-names.d.ts +9 -0
  142. package/types/src/files/kinds.d.ts +112 -0
  143. package/types/src/files/scan.d.ts +78 -0
  144. package/types/src/files/sniff.d.ts +7 -0
  145. package/types/src/files/streams.d.ts +17 -0
  146. package/types/src/files/treatment.d.ts +18 -0
  147. package/types/src/from-row.d.ts +20 -0
  148. package/types/src/honeypot.d.ts +2 -0
  149. package/types/src/implement/anonymous.d.ts +24 -0
  150. package/types/src/implement/attachment.d.ts +14 -0
  151. package/types/src/implement/boot.d.ts +128 -0
  152. package/types/src/implement/bounded.d.ts +32 -0
  153. package/types/src/implement/browser-config.d.ts +19 -0
  154. package/types/src/implement/capability.d.ts +142 -0
  155. package/types/src/implement/challenge.d.ts +75 -0
  156. package/types/src/implement/client-address.d.ts +11 -0
  157. package/types/src/implement/connect.d.ts +67 -0
  158. package/types/src/implement/crashes.d.ts +31 -0
  159. package/types/src/implement/dispatch.d.ts +251 -0
  160. package/types/src/implement/egress.d.ts +14 -0
  161. package/types/src/implement/environment.d.ts +14 -0
  162. package/types/src/implement/failures.d.ts +58 -0
  163. package/types/src/implement/faults.d.ts +48 -0
  164. package/types/src/implement/headers.d.ts +7 -0
  165. package/types/src/implement/implement.d.ts +58 -0
  166. package/types/src/implement/index.d.ts +25 -0
  167. package/types/src/implement/invocation.d.ts +136 -0
  168. package/types/src/implement/membership.d.ts +201 -0
  169. package/types/src/implement/multipart.d.ts +36 -0
  170. package/types/src/implement/params.d.ts +7 -0
  171. package/types/src/implement/principal.d.ts +57 -0
  172. package/types/src/implement/project.d.ts +11 -0
  173. package/types/src/implement/public.d.ts +61 -0
  174. package/types/src/implement/serve.d.ts +25 -0
  175. package/types/src/implement/terminals.d.ts +33 -0
  176. package/types/src/implement/tokens.d.ts +49 -0
  177. package/types/src/implement/types.d.ts +263 -0
  178. package/types/src/implement/urls.d.ts +15 -0
  179. package/types/src/implement/verifiers.d.ts +19 -0
  180. package/types/src/implement/webhook.d.ts +55 -0
  181. package/types/src/implement/workload.d.ts +61 -0
  182. package/types/src/implement/xlsx.d.ts +6 -0
  183. package/types/src/index.d.ts +12 -0
  184. package/types/src/jobs/exception.d.ts +40 -0
  185. package/types/src/jobs/mail.d.ts +67 -0
  186. package/types/src/jobs/report.d.ts +56 -0
  187. package/types/src/jobs/runner.d.ts +218 -0
  188. package/types/src/jobs/schedule.d.ts +17 -0
  189. package/types/src/jobs/scrub.d.ts +12 -0
  190. package/types/src/jobs/types.d.ts +98 -0
  191. package/types/src/react/caller.d.ts +30 -0
  192. package/types/src/react/errors.d.ts +40 -0
  193. package/types/src/react/hooks.d.ts +110 -0
  194. package/types/src/react/index.d.ts +5 -0
  195. package/types/src/react/provider.d.ts +58 -0
  196. package/types/src/react/store.d.ts +68 -0
  197. package/types/src/react/testing.d.ts +28 -0
  198. package/types/src/react/types.d.ts +33 -0
  199. package/types/src/rpc/builder.d.ts +52 -0
  200. package/types/src/rpc/contract.d.ts +23 -0
  201. package/types/src/rpc/dispatcher.d.ts +11 -0
  202. package/types/src/rpc/types.d.ts +62 -0
  203. package/types/src/service/define.d.ts +42 -0
  204. package/types/src/service/index.d.ts +3 -0
  205. package/types/src/service/serve.d.ts +28 -0
  206. package/types/src/spa-fallback.d.ts +2 -0
  207. package/types/src/standard-schema.d.ts +55 -0
  208. package/types/src/testing/caller.d.ts +95 -0
  209. package/types/src/testing/challenge.d.ts +11 -0
  210. package/types/src/testing/dev.d.ts +97 -0
  211. package/types/src/testing/endpoint-access.d.ts +132 -0
  212. package/types/src/testing/index.d.ts +12 -0
  213. package/types/src/testing/isolation.d.ts +3 -0
  214. package/types/src/testing/kit.d.ts +207 -0
  215. package/types/src/testing/membership.d.ts +132 -0
  216. package/types/src/testing/policy-isolation.d.ts +113 -0
  217. package/types/src/testing/preload.d.ts +1 -0
  218. package/types/src/testing/proxy.d.ts +40 -0
  219. package/types/src/testing/runner.d.ts +8 -0
  220. package/types/src/testing/sample-file.d.ts +5 -0
  221. package/types/src/testing/status.d.ts +4 -0
  222. package/types/src/undumpable.d.ts +5 -0
@@ -0,0 +1,131 @@
1
+ import { z } from 'zod/v4';
2
+ import { type AttachmentBrand } from '../contract/attachment';
3
+ import { type ProcedureType } from '../contract/declaration';
4
+ import type { AnyContract, InputSchema, Procedure, Schema } from '../contract/define';
5
+ import { type ClientInput, type FileBrand } from '../contract/file';
6
+ import { type BounceOption, type RpcFetch } from './transport';
7
+ type SurfaceOf<C> = C extends {
8
+ readonly surface: infer S;
9
+ } ? S : never;
10
+ /** The mounts a client calls: RPC mounts and link mounts. */
11
+ export type ClientMount<C> = {
12
+ [M in keyof SurfaceOf<C>]: SurfaceOf<C>[M] extends {
13
+ readonly kind: 'rpc' | 'link';
14
+ } ? M : never;
15
+ }[keyof SurfaceOf<C>] & string;
16
+ /**
17
+ * One procedure: its input as the caller writes it (defaults optional), its output as parsed, and the output schema
18
+ * it parses with (`@fabrika/app/react` reads a cached answer back through it).
19
+ */
20
+ export type ProcedureCall<I, O extends Schema> = ([I] extends [InputSchema] ? (input: ClientInput<z.input<I>>) => Promise<z.output<O>> : (input?: Record<never, never>) => Promise<z.output<O>>) & {
21
+ readonly output: O;
22
+ };
23
+ export type ClientTree<T> = {
24
+ readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, unknown> ? O extends AttachmentBrand ? AttachmentProcedure<I> : O extends FileBrand<string> ? FileProcedure<I> : ProcedureCall<I, O> : ClientTree<T[K]>;
25
+ };
26
+ type MountOf<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>];
27
+ /** One function per procedure, and an `AttachmentProcedure` or `FileProcedure` per procedure that answers a file. */
28
+ export type ContractClient<C, M> = MountOf<C, M> extends {
29
+ readonly procedures: infer T;
30
+ } ? ClientTree<T> : never;
31
+ /** The answer of a client procedure: `ResultOf<typeof api.tasks.get>`; a procedure that answers a file, a `DownloadedFile`. */
32
+ export type ResultOf<F> = F extends (...args: never[]) => Promise<infer R> ? R : F extends AttachmentProcedure<unknown> | FileProcedure<unknown> ? DownloadedFile : never;
33
+ /** The input of a client procedure as the caller writes it: `InputOf<typeof api.tasks.create>`. */
34
+ export type InputOf<F> = F extends (...args: infer A) => Promise<unknown> ? A[0] : F extends AttachmentProcedure<infer I> | FileProcedure<infer I> ? DownloadInput<I>[0] : never;
35
+ export interface ClientOptions {
36
+ /** The application's origin; procedure paths are joined to it. Defaults to the page's own origin. */
37
+ readonly baseUrl?: string;
38
+ /** Override `fetch` (tests, a script). Defaults to the global `fetch`. */
39
+ readonly fetch?: RpcFetch;
40
+ /**
41
+ * A `px_` key, sent as `Authorization: Bearer`. A request with a key carries no cookie. In a browser the key goes
42
+ * only to the page's own origin.
43
+ */
44
+ readonly key?: string;
45
+ /** On a 401 that carries a login URL, send the browser to sign in instead of throwing. */
46
+ readonly bounceOnAuth?: BounceOption;
47
+ }
48
+ /** A link mount's caller is the holder of its share key, which every request presents. */
49
+ export interface LinkClientOptions extends ClientOptions {
50
+ readonly key: string;
51
+ }
52
+ type OptionsFor<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>] extends {
53
+ readonly kind: 'link';
54
+ } ? [options: LinkClientOptions] : [options?: ClientOptions];
55
+ /**
56
+ * What a value of a client tree is, kept beside it so the value stays a plain function or record: a procedure's
57
+ * `<mount>.<path>`, its type and input schema, or a group's prefix. `@fabrika/app/react` keys its cache by it.
58
+ */
59
+ export interface ClientNode {
60
+ readonly mount: string;
61
+ /** The dotted path below the mount; `''` for the client itself. */
62
+ readonly path: string;
63
+ readonly procedure: {
64
+ readonly type: ProcedureType;
65
+ readonly input: Schema | null;
66
+ } | null;
67
+ }
68
+ /** The node a value of a client tree is, or `null` for any other value. */
69
+ export declare function clientNodeOf(value: unknown): ClientNode | null;
70
+ /**
71
+ * The URL a page's ALTCHA widget fetches the challenge of `procedure` from (`GET /__fabrika/challenge/<action>`), on the
72
+ * client's `baseUrl`. Throws for a procedure whose `admission.challenge` is not `provider: 'altcha'`.
73
+ */
74
+ export declare function challengeUrl(procedure: object): string;
75
+ declare const attachmentInput: unique symbol;
76
+ /**
77
+ * An attachment procedure of a client: not a function, because its answer is a file. `download(api.<procedure>,
78
+ * input)` fetches and saves it.
79
+ */
80
+ export interface AttachmentProcedure<I> {
81
+ /** `<mount>.<path>` */
82
+ readonly id: string;
83
+ /** The file name the contract declares. */
84
+ readonly filename: string;
85
+ /** Carries the input schema for `download`; never present at runtime. */
86
+ readonly [attachmentInput]?: I;
87
+ }
88
+ /**
89
+ * A procedure whose output is a file (`file('<kind>')`): not a function, because its answer is a file.
90
+ * `download(api.<procedure>, input)` fetches it with the caller's credential, and a GET one's `url(input)` is where a
91
+ * same-origin page links to it (`<img src>`, `<a download>`).
92
+ */
93
+ export interface FileProcedure<I> {
94
+ /** `<mount>.<path>` */
95
+ readonly id: string;
96
+ /**
97
+ * The URL of the file a GET procedure answers, for a page signed in on the same origin. A client with a key has none:
98
+ * a key never goes into a URL, so it downloads instead.
99
+ */
100
+ url(...input: DownloadInput<I>): string;
101
+ /** Carries the input schema for `download`; never present at runtime. */
102
+ readonly [attachmentInput]?: I;
103
+ }
104
+ /** A downloaded file: a `File`, and the page's offer to save it. */
105
+ export declare class DownloadedFile extends File {
106
+ /** The file as a `Blob`. */
107
+ blob(): Blob;
108
+ /** Offers the file as a download under its name; nothing where there is no page. */
109
+ save(): void;
110
+ }
111
+ /** The mount and path of an attachment procedure of a client, or `null` for any other value. */
112
+ export declare function attachmentAt(value: unknown): {
113
+ readonly mount: string;
114
+ readonly path: string;
115
+ } | null;
116
+ /** The input `download` takes: the procedure's, or none. */
117
+ export type DownloadInput<I> = [I] extends [InputSchema] ? [input: z.input<I>] : [input?: Record<never, never>];
118
+ /**
119
+ * Calls a procedure that answers a file (an attachment, or a `file('<kind>')` output) with the caller's credential, and
120
+ * answers the file: `blob()`, `stream()`, `save()`. An attachment is also offered as a download in a browser, under the
121
+ * declared name. A refusal is an `RpcError`.
122
+ */
123
+ export declare function download<I>(procedure: AttachmentProcedure<I> | FileProcedure<I>, ...input: DownloadInput<I>): Promise<DownloadedFile>;
124
+ /** `download` of any file procedure of a client, its input unchecked: the provider's `useDownload` runs it. */
125
+ export declare function downloadFile(procedure: object, input: unknown): Promise<DownloadedFile>;
126
+ /**
127
+ * The client of mount `mount` of `contract`: one function per declared procedure. A link mount's client sends its
128
+ * share key as a bearer, so `options.key` is required there.
129
+ */
130
+ export declare function createClient<const C extends AnyContract, const M extends ClientMount<C>>(contract: C, mount: M, ...rest: OptionsFor<C, M>): ContractClient<C, M>;
131
+ export {};
@@ -0,0 +1,66 @@
1
+ import type { RpcFetch } from './transport';
2
+ /** One stack frame in Sentry's shape, the file a script URL. */
3
+ export interface BrowserFrame {
4
+ readonly filename: string;
5
+ readonly function?: string;
6
+ readonly lineno: number;
7
+ readonly colno: number;
8
+ /** A frame of a script of the page's own origin. */
9
+ readonly in_app: boolean;
10
+ }
11
+ /** Where the page reports, read from its browser config. */
12
+ export interface ReportingTarget {
13
+ /** The ingest's envelope endpoint, authenticated by the DSN's public key in its query, as the Sentry SDK sends it. */
14
+ readonly envelopeUrl: string;
15
+ readonly release: string | null;
16
+ readonly environment: string | null;
17
+ }
18
+ /** What the reporter listens on and reads the page's address from: `window` in a page. */
19
+ export interface ReportingPage {
20
+ addEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void;
21
+ removeEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void;
22
+ readonly location: {
23
+ readonly origin: string;
24
+ readonly pathname: string;
25
+ };
26
+ }
27
+ /** A page that keeps failing stops reporting here; Operations rate-limits the whole source, not one page. */
28
+ export declare const MAX_REPORTS_PER_PAGE = 20;
29
+ /**
30
+ * The envelope endpoint of an ingest DSN `https://<key>@<host>/<project>`, or `null` for any other value. The server's
31
+ * reporter parses the same DSN (`jobs/report.ts`); it is server code, so a page does not import it.
32
+ */
33
+ export declare function envelopeUrlOf(dsn: string): string | null;
34
+ /** The reporting target the browser config names, or `null` when it names no usable DSN. */
35
+ export declare function reportingTargetOf(config: unknown): ReportingTarget | null;
36
+ /**
37
+ * The frames of a V8, SpiderMonkey or JavaScriptCore `stack`, oldest call first as Sentry orders them, the
38
+ * `MAX_FRAMES` nearest the throw kept. A frame whose file is no URL (an `eval`, a native function) is left out.
39
+ */
40
+ export declare function parseBrowserStack(stack: string, origin: string): BrowserFrame[];
41
+ type Mechanism = 'onerror' | 'onunhandledrejection';
42
+ interface ReportedException {
43
+ readonly type: string;
44
+ readonly value: string;
45
+ readonly mechanism: {
46
+ readonly type: Mechanism;
47
+ readonly handled: false;
48
+ };
49
+ readonly stacktrace?: {
50
+ readonly frames: readonly BrowserFrame[];
51
+ };
52
+ }
53
+ /** The envelope of one error event. The page's address goes without its query and fragment, which may carry a key. */
54
+ export declare function browserEnvelope(exception: ReportedException, target: ReportingTarget, page: ReportingPage['location'], now: Date): string;
55
+ /**
56
+ * Listen for the page's uncaught errors and unhandled rejections and send each to `target`; answers the uninstall.
57
+ * An error equal to the one just sent is not sent again, and the page sends at most `MAX_REPORTS_PER_PAGE`. A failed
58
+ * delivery is dropped: reporting never throws into the page.
59
+ */
60
+ export declare function installErrorReporting(page: ReportingPage, target: ReportingTarget, send: RpcFetch): () => void;
61
+ /**
62
+ * Read the browser config at `configUrl` and install reporting when it names a DSN; answers the uninstall, or `null`
63
+ * when nothing was installed. A missing, refused or unreadable config (local development, a test) installs nothing.
64
+ */
65
+ export declare function startErrorReporting(configUrl: string, fetch: RpcFetch, page: ReportingPage): Promise<(() => void) | null>;
66
+ export {};
@@ -0,0 +1,4 @@
1
+ export { type PageCaller, parsePageCaller } from './caller';
2
+ export { type AttachmentProcedure, challengeUrl, type ClientMount, type ClientOptions, type ClientTree, type ContractClient, createClient, download, DownloadedFile, type DownloadInput, type FileProcedure, type InputOf, type LinkClientOptions, type ProcedureCall, type ResultOf, } from './contract';
3
+ export { shareKey } from './share';
4
+ export { type BounceOption, RpcError, type RpcFetch } from './transport';
@@ -0,0 +1,14 @@
1
+ import type { InferRpcClient } from '../rpc/contract.js';
2
+ import { type BounceOption, type RpcFetch } from './transport.js';
3
+ export interface RpcClientOptions {
4
+ /** Endpoint the RPC proxy POSTs to (e.g. `/rpc`). */
5
+ readonly baseUrl: string;
6
+ /**
7
+ * Auto-redirect to SSO on a sign-in 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
8
+ * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
9
+ */
10
+ readonly bounceOnAuth?: BounceOption;
11
+ /** Override `fetch` (tests / non-browser). Defaults to the global `fetch`. */
12
+ readonly fetch?: RpcFetch;
13
+ }
14
+ export declare function createRpcClient<TApi>(opts: RpcClientOptions): InferRpcClient<TApi>;
@@ -0,0 +1,2 @@
1
+ /** The key the share link carried, or `null` outside a share SPA or when the link had none. */
2
+ export declare function shareKey(): string | null;
@@ -0,0 +1,42 @@
1
+ export declare class RpcError extends Error {
2
+ readonly type: string;
3
+ readonly issues?: unknown;
4
+ readonly loginUrl?: string;
5
+ readonly httpStatus?: number;
6
+ constructor(payload: {
7
+ type: string;
8
+ message: string;
9
+ issues?: unknown;
10
+ loginUrl?: string;
11
+ httpStatus?: number;
12
+ });
13
+ }
14
+ /** Minimal Fetch API surface required by the RPC client. */
15
+ export type RpcFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
16
+ /**
17
+ * Auto-redirect to SSO on a sign-in 401 (`type: 'auth'` + `loginUrl`) instead of throwing.
18
+ * `true` uses sane defaults; pass `{ sessionKey, windowMs }` to tune the re-entry guard.
19
+ */
20
+ export type BounceOption = boolean | {
21
+ sessionKey?: string;
22
+ windowMs?: number;
23
+ };
24
+ export interface BounceConfig {
25
+ readonly sessionKey: string;
26
+ readonly windowMs: number;
27
+ }
28
+ export declare function resolveBounce(scope: string, opt: BounceOption | undefined): BounceConfig | null;
29
+ /**
30
+ * Sends one request and answers the envelope's `result`; every failure is an `RpcError`, and so is every answer that is
31
+ * not 2xx, whatever its body holds. `init` builds the request inside the guard, so an input that does not serialize
32
+ * rejects like a failed request instead of throwing.
33
+ */
34
+ export declare function exchange(doFetch: RpcFetch, url: string, init: () => RequestInit, bounce: BounceConfig | null): Promise<unknown>;
35
+ /**
36
+ * Sends one request whose success is a file and answers its bytes and its `Content-Disposition`; a failure is read from
37
+ * its `{ error }` envelope.
38
+ */
39
+ export declare function exchangeFile(doFetch: RpcFetch, url: string, init: () => RequestInit, bounce: BounceConfig | null): Promise<{
40
+ readonly body: Blob;
41
+ readonly disposition: string | null;
42
+ }>;
@@ -0,0 +1,73 @@
1
+ import { type SqliteStorage } from '@fabrika/db/sqlite';
2
+ import { type CrashEvents } from '../implement/crashes.js';
3
+ import type { ContractImplementation } from '../implement/implement.js';
4
+ import { type JobClock } from '../jobs/runner.js';
5
+ import { type OpsRecovery, type OpsStorage } from './ops.js';
6
+ /** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
7
+ export type ImplementationLoader = () => Promise<{
8
+ readonly default: ContractImplementation;
9
+ }>;
10
+ /** One of the application's SQLite migrations, as `fabrika app build` bundles them from `db/migrations`. */
11
+ export interface ApplicationMigration {
12
+ readonly name: string;
13
+ readonly sql: string;
14
+ }
15
+ export interface ContractWorkerOptions {
16
+ /** The application's own SQLite migrations, applied as the bundle `app` after the framework's `fabrika`. */
17
+ readonly migrations?: readonly ApplicationMigration[];
18
+ /** Where the isolate hears of an unhandled rejection; the global `unhandledrejection` event by default. */
19
+ readonly rejections?: CrashEvents;
20
+ /** What posts a report to Operations' ingest; `fetch` by default. */
21
+ readonly operationsFetch?: (request: Request) => Promise<Response>;
22
+ /** The jobs' and the alarm's waits and an attempt's deadline; the system clock by default. */
23
+ readonly clock?: JobClock;
24
+ }
25
+ /**
26
+ * Marks the Worker's repair tick, with its `scheduledTime`. The Worker's `fetch` removes it from every request it
27
+ * forwards, so only its own `scheduled` handler reaches the tick.
28
+ */
29
+ export declare const TICK_HEADER = "X-Fabrika-Tick";
30
+ /** A wake runs at most this early: `Date.now()` is pinned between I/O, so an alarm may start a moment before it (I6). */
31
+ export declare const ALARM_SLACK_MS = 50;
32
+ /** After an internal error the alarm is armed again this far ahead; the repair tick covers a re-arm that failed. */
33
+ export declare const ALARM_RETRY_MS = 30000;
34
+ /**
35
+ * The object's KV key that holds the name of the object it is, recorded at its first verified event: an alarm names no
36
+ * object, and the one ordinary traffic reaches may since have changed. Outside the SQLite, so no dump carries it.
37
+ */
38
+ export declare const OBJECT_NAME_KEY = "fabrika:object";
39
+ /** The object's alarm. On a SQLite-backed object `setAlarm` and `deleteAlarm` commit with the open transaction. */
40
+ export interface AlarmStorage {
41
+ setAlarm(scheduledTime: number): Promise<void>;
42
+ deleteAlarm(): Promise<void>;
43
+ }
44
+ /**
45
+ * What the object needs of its `ctx.storage`; a Durable Object's `DurableObjectStorage` fits it. A test double without
46
+ * an alarm arms none.
47
+ */
48
+ export type ApplicationStorage = SqliteStorage & OpsStorage & Partial<AlarmStorage>;
49
+ /** What the object needs of its `DurableObjectState`. */
50
+ export interface ApplicationState {
51
+ readonly storage: ApplicationStorage & Partial<Omit<OpsRecovery, 'abort'>>;
52
+ blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
53
+ waitUntil(promise: Promise<unknown>): void;
54
+ /** workerd resets the object; the test double has none. */
55
+ abort?(reason?: string): void;
56
+ }
57
+ /** `state` with every `waitUntil` promise recorded by the isolate's pending-work tracker (the ops operation `timers`). */
58
+ export declare function trackedState(state: ApplicationState): ApplicationState;
59
+ /** What the object classes of this isolate boot: the generated entrypoint's `createContractWorker` registers it. */
60
+ export declare function registerApplication(load: ImplementationLoader, options: ContractWorkerOptions): void;
61
+ /** The application environment's one object. The Worker's generated entrypoint exports it as `FabrikaApplication`. */
62
+ export declare class FabrikaApplication {
63
+ #private;
64
+ constructor(state: ApplicationState, env: Readonly<Record<string, unknown>>);
65
+ fetch(request: Request): Promise<Response>;
66
+ /**
67
+ * workerd calls it when the alarm is due (ADR-0065 §5). Only the object ordinary traffic reaches runs jobs, and only
68
+ * in `open`; otherwise it runs nothing and arms nothing: the maintenance operation owns the object, reopening arms the
69
+ * alarm again, and the repair tick arms the serving object's. It never throws, because after six failures the platform
70
+ * stops retrying: an internal error in `open` arms it again in `ALARM_RETRY_MS` and is reported.
71
+ */
72
+ alarm(): Promise<void>;
73
+ }
@@ -0,0 +1,33 @@
1
+ import type { IamMembershipRpc, IamTerminalRpc } from '@fabrika/auth-core';
2
+ import type { IamKeySource } from '../implement/boot.js';
3
+ import { type ConnectFetch } from '../implement/connect.js';
4
+ import type { SpaAssets } from '../implement/dispatch.js';
5
+ import type { WorkloadTokenSource } from '../implement/workload.js';
6
+ /** The method `name` of a binding, bound to it, or `null` when it has none. */
7
+ export declare function method(target: unknown, name: string): ((...args: unknown[]) => unknown) | null;
8
+ export declare function bindingKeySource(binding: unknown): IamKeySource;
9
+ /**
10
+ * IAM's membership operations on the `IAM` binding (`PropustkaApplication`), every answer decoded like the HTTP
11
+ * transport's. A binding without them is no membership transport, and `boot` refuses a contract that needs one.
12
+ */
13
+ export declare function bindingMembership(binding: unknown): IamMembershipRpc | undefined;
14
+ /** The identifications at a terminal over the IAM binding, when its entrypoint serves them (ADR-0067). */
15
+ export declare function bindingTerminals(binding: unknown): IamTerminalRpc | undefined;
16
+ /**
17
+ * IAM's token exchange on the `IAM` binding (`mintFromKey`), for the keys of the jobs, webhooks and public procedures.
18
+ * An answer that is not IAM's decided outcome throws: "IAM could not be asked".
19
+ */
20
+ export declare function bindingWorkloadTokens(binding: unknown): WorkloadTokenSource | undefined;
21
+ /**
22
+ * The SPA and link mounts' files from the Workers Assets binding, whose directory mirrors the request paths: the mount
23
+ * `/admin` reads `admin/…` of it, the root mount the rest (the Cloudflare deploy stages each mount's `dir` there). A page
24
+ * route that names no file (`isPageRoute`) gets the mount's `index.html`, as `diskAssets` serves it: Workers Assets
25
+ * answers `<prefix>/` with it. A missing asset stays 404.
26
+ */
27
+ export declare function bindingAssets(binding: unknown): SpaAssets | undefined;
28
+ /**
29
+ * The service bindings to owners' proxy Workers (`FABRIKA_CONNECT_<IMPORT>`), which `captureEnvironment` keeps from
30
+ * the application because no `FABRIKA_*` value reaches it. A binding routes by itself: the URL it is called with
31
+ * carries the owner's host, which the proxy Worker selects the application by.
32
+ */
33
+ export declare function connectBindings(env: Readonly<Record<string, unknown>>): Record<string, ConnectFetch>;
@@ -0,0 +1,16 @@
1
+ import { type OpsExportRequest } from '@fabrika/auth-core';
2
+ import type { MaintenanceBarrier } from './maintenance.js';
3
+ import type { OpsTarget } from './ops.js';
4
+ /** One step of a dump of the object's database (ADR-0070). */
5
+ export declare function serveExport(target: OpsTarget, barrier: MaintenanceBarrier, step: OpsExportRequest): Promise<Response>;
6
+ /** What an export step reads: the object's storage, bucket and bookmarks, and the digest of the contract it was deployed with. */
7
+ export interface ExportSource extends Pick<OpsTarget, 'storage' | 'bucket' | 'recovery'> {
8
+ /** `FABRIKA_CONTRACT_DIGEST`, which the manifest records. */
9
+ readonly contractDigest: string | null;
10
+ }
11
+ /**
12
+ * One step of a dump. A diagnostic step runs in any mode. A consistent one runs in the barrier's turn, only at the
13
+ * published generation, never while the object is `open` or holds an import marker, so no transition and no migration
14
+ * falls inside it; past `begin` it refuses a database whose state or stretch is not the one its `begin` saw.
15
+ */
16
+ export declare function exportStep(source: ExportSource, barrier: MaintenanceBarrier, step: OpsExportRequest): Promise<Response>;
@@ -0,0 +1,47 @@
1
+ import { type OpsDumpSchema, type OpsImportRequest } from '@fabrika/auth-core';
2
+ import type { SqliteStorage } from '@fabrika/db/sqlite';
3
+ import { type SqliteMigrationBundle } from '@fabrika/db/sqlite-migrate';
4
+ import type { MaintenanceBarrier } from './maintenance.js';
5
+ import type { OpsTarget } from './ops.js';
6
+ /**
7
+ * One step of loading a dump into a fresh object (ADR-0070); `serving` is the object of ordinary traffic. A runtime
8
+ * whose storage has no synchronous KV or `deleteAll` does not serve the operation.
9
+ */
10
+ export declare function serveImport(target: OpsTarget, barrier: MaintenanceBarrier, step: OpsImportRequest, serving: string): Promise<Response>;
11
+ /** workerd's synchronous KV storage of a SQLite-backed object: it lives in the same database, so it commits with a transaction. */
12
+ export interface ImportKv {
13
+ get(key: string): unknown;
14
+ put(key: string, value: unknown): void;
15
+ delete(key: string): boolean;
16
+ }
17
+ /** What the importer needs of the object's storage; a SQLite-backed `DurableObjectStorage` fits it. */
18
+ export interface ImportStorage extends SqliteStorage {
19
+ readonly kv: ImportKv;
20
+ /** Wipes the object's database, its KV storage and its alarm. */
21
+ deleteAll(): Promise<void>;
22
+ }
23
+ /** The object an import step loads into. */
24
+ export interface ImportTarget {
25
+ readonly storage: ImportStorage;
26
+ /** The environment's bucket (the `FABRIKA_FILES` R2 binding), where the backup lies. */
27
+ readonly bucket: unknown;
28
+ /** The release's migration bundles in the order the object applies them: the framework's, then the application's. */
29
+ readonly migrations: readonly SqliteMigrationBundle[];
30
+ /** The object of ordinary traffic (`FABRIKA_APPLICATION_OBJECT`), which `discard` never wipes. */
31
+ readonly serving: string;
32
+ }
33
+ /** The KV key of the import marker. Invariant: an object that holds it never boots and never leaves `inspect`. */
34
+ export declare const IMPORT_MARKER_KEY = "fabrika:import";
35
+ /** Whether the object holds an import marker, so it must neither boot nor leave `inspect`. */
36
+ export declare function importInProgress(storage: {
37
+ readonly kv: ImportKv;
38
+ }): boolean;
39
+ /**
40
+ * One step of loading the consistent backup `step.source` into the fresh object `target` (ADR-0070 §6), in the
41
+ * barrier's turn: ADR-0069's stale refusal unless `step.generation` is the published one, then `serving_object` on the
42
+ * object of ordinary traffic, then `wrong_mode` unless `inspect`. The turn is held across the step's R2 reads, so the
43
+ * generation and mode it was admitted under still hold when it commits.
44
+ */
45
+ export declare function importStep(target: ImportTarget, barrier: MaintenanceBarrier, step: OpsImportRequest): Promise<Response>;
46
+ /** The schema `planOpsDump` reads, of every table a dump holds (`describeOpsDumpSchema`). */
47
+ export declare function describeDumpSchema(storage: SqliteStorage): OpsDumpSchema;
@@ -0,0 +1,117 @@
1
+ import { type OpsMaintenance, type OpsMode, type OpsPublishedState, type OpsStateAck } from '@fabrika/auth-core';
2
+ import type { InvocationAdmission, InvocationGate, InvocationKind } from '../implement/dispatch.js';
3
+ export declare const DRAIN_BOUND_MS: number;
4
+ /** The state R2 holds, and its version: the etag a conditional put names. */
5
+ export interface StoredMaintenance {
6
+ readonly state: OpsPublishedState;
7
+ readonly version: string;
8
+ }
9
+ /**
10
+ * Since which generation the object has written nothing, as of the published generation `generation`: kept only while
11
+ * it is `read-only`, `closed` or `inspect`.
12
+ */
13
+ export interface FrozenRecord {
14
+ readonly generation: number;
15
+ readonly since: number;
16
+ }
17
+ /** The object's durable copy of its maintenance state. */
18
+ export interface MaintenanceStore {
19
+ /** `null` only for a definite not-found; every other failure throws, and is never read as absence. */
20
+ read(): Promise<StoredMaintenance | null>;
21
+ /** Puts `state` if R2 still holds `version` (`null`: holds nothing); the new version, or `null` when the condition failed. */
22
+ put(state: OpsPublishedState, version: string | null): Promise<string | null>;
23
+ /** The frozen record, `null` when none is stored. A store without these keeps the record in memory only. */
24
+ readFrozen?(): Promise<FrozenRecord | null>;
25
+ putFrozen?(record: FrozenRecord): Promise<void>;
26
+ }
27
+ /** `__fabrika/ops/<object>.json` in the environment's bucket (`bucket`, an R2 binding). */
28
+ export declare function r2MaintenanceStore(bucket: unknown, object: string): MaintenanceStore;
29
+ export type TransitionResult = {
30
+ readonly kind: 'acknowledged';
31
+ readonly ack: OpsStateAck;
32
+ }
33
+ /** The 409: what R2 holds as far as the object knows, `null` before the first publication. */
34
+ | {
35
+ readonly kind: 'stale';
36
+ readonly published: OpsPublishedState | null;
37
+ }
38
+ /** R2 could not be read or written: the call fails and Control retries. */
39
+ | {
40
+ readonly kind: 'failed';
41
+ }
42
+ /** The caller's `frozen` held the object in `inspect`: nothing changed. */
43
+ | {
44
+ readonly kind: 'frozen';
45
+ };
46
+ export type MigrateResult<T> = {
47
+ readonly kind: 'migrated';
48
+ readonly value: T;
49
+ } | {
50
+ readonly kind: 'stale';
51
+ readonly published: OpsPublishedState | null;
52
+ };
53
+ /** What a step run in the barrier's turn answers, and what keeps the turn past the answer (`null`: nothing). */
54
+ export interface TurnStep<T> {
55
+ readonly value: T;
56
+ readonly holdUntil: Promise<void> | null;
57
+ }
58
+ export type StepResult<T> = {
59
+ readonly kind: 'ran';
60
+ readonly value: T;
61
+ } | {
62
+ readonly kind: 'stale';
63
+ readonly published: OpsPublishedState | null;
64
+ };
65
+ export interface BarrierOptions {
66
+ /** The drain's bound; `DRAIN_BOUND_MS` by default. */
67
+ readonly drainBoundMs?: number;
68
+ }
69
+ export declare class MaintenanceBarrier {
70
+ #private;
71
+ private constructor();
72
+ /** The cold start: an absent state is `open`; a failed read rejects, and the caller retries on its next request. */
73
+ static load(store: MaintenanceStore, options?: BarrierOptions): Promise<MaintenanceBarrier>;
74
+ get mode(): OpsMode;
75
+ view(): OpsMaintenance;
76
+ /** What R2 holds as far as this instance knows, `null` before the first publication: what a stale refusal names. */
77
+ get published(): OpsPublishedState | null;
78
+ /**
79
+ * The generation at which the object entered its current stretch of `read-only`, `closed` and `inspect`, or at which a
80
+ * data step last wrote within it; `null` outside such a stretch. A consistent dump is one state while it holds.
81
+ */
82
+ get frozenSince(): number | null;
83
+ /**
84
+ * Called in a data step's turn before the step writes while the object writes nothing else (an import step, a
85
+ * restore's `arm`): the stretch starts again at the current generation, durably before the write. A failed put rejects.
86
+ */
87
+ restrictedWrite(): Promise<void>;
88
+ /** The scope of one invocation, admitted now: the generation and mode it captures, which its writes are fenced on. */
89
+ event(): BarrierEvent;
90
+ /** Whether a write of an invocation admitted at `generation` in `mode` may commit now. */
91
+ writable(generation: number | null, mode: OpsMode): boolean;
92
+ /** Admits an invocation of `kind` captured at `generation`, or `null` when the mode refuses it or a transition followed. */
93
+ admit(kind: InvocationKind, generation: number | null): InvocationAdmission | null;
94
+ /**
95
+ * `POST /__fabrika/ops/state`: the transition of ADR-0069 §3, acknowledged once published and drained. `frozen` is
96
+ * asked in the turn, after every data step before it: while it holds, no transition leaves `inspect`.
97
+ */
98
+ transition(requested: OpsPublishedState, frozen?: () => boolean): Promise<TransitionResult>;
99
+ /**
100
+ * `POST /__fabrika/ops/migrate`: `work` runs only under the published generation, in a mode that may migrate, and no
101
+ * transition runs meanwhile.
102
+ */
103
+ migrate<T>(generation: number, work: () => Promise<T>): Promise<MigrateResult<T>>;
104
+ /**
105
+ * A data step of Control's (ADR-0070): `work` runs in the barrier's turn, only under the published `generation`, with
106
+ * the mode it is in. No transition runs until `work` settles, nor, when it answers one, until `holdUntil` settles.
107
+ */
108
+ step<T>(generation: number, work: (mode: OpsMode) => Promise<TurnStep<T>>): Promise<StepResult<T>>;
109
+ }
110
+ /** One invocation's view of the barrier: the gate that admits and counts its work, and its write fence. */
111
+ export declare class BarrierEvent implements InvocationGate {
112
+ #private;
113
+ constructor(barrier: MaintenanceBarrier, generation: number | null, mode: OpsMode);
114
+ admit(kind: InvocationKind): InvocationAdmission | null;
115
+ /** Whether this invocation may commit a write now: still `open`, at the generation it was admitted under. */
116
+ writable(): boolean;
117
+ }
@@ -0,0 +1,11 @@
1
+ /** The Durable Object class the Cloudflare entry exports: one object per application environment runs it (ADR-0065). */
2
+ export declare const CLOUDFLARE_APPLICATION_CLASS = "FabrikaApplication";
3
+ /** The binding through which the application's Worker reaches its object. */
4
+ export declare const CLOUDFLARE_APPLICATION_BINDING = "FABRIKA_APPLICATION";
5
+ /** The R2 bucket binding of the environment's stored files. */
6
+ export declare const CLOUDFLARE_FILES_BINDING = "FABRIKA_FILES";
7
+ /**
8
+ * The Workers Assets binding the SPA and link mounts serve their files from. Its directory mirrors the request paths:
9
+ * the mount `/admin` serves `<directory>/admin/…`, the root mount `<directory>/…`.
10
+ */
11
+ export declare const CLOUDFLARE_ASSETS_BINDING = "ASSETS";