@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

package/types/src/cloudflare/bindings.d.ts

@@ -0,0 +1,33 @@
+import type { IamMembershipRpc, IamTerminalRpc } from '@fabrika/auth-core';
+import type { IamKeySource } from '../implement/boot.js';
+import { type ConnectFetch } from '../implement/connect.js';
+import type { SpaAssets } from '../implement/dispatch.js';
+import type { WorkloadTokenSource } from '../implement/workload.js';
+/** The method `name` of a binding, bound to it, or `null` when it has none. */
+export declare function method(target: unknown, name: string): ((...args: unknown[]) => unknown) | null;
+export declare function bindingKeySource(binding: unknown): IamKeySource;
+/**
+ * IAM's membership operations on the `IAM` binding (`PropustkaApplication`), every answer decoded like the HTTP
+ * transport's. A binding without them is no membership transport, and `boot` refuses a contract that needs one.
+ */
+export declare function bindingMembership(binding: unknown): IamMembershipRpc | undefined;
+/** The identifications at a terminal over the IAM binding, when its entrypoint serves them (ADR-0067). */
+export declare function bindingTerminals(binding: unknown): IamTerminalRpc | undefined;
+/**
+ * IAM's token exchange on the `IAM` binding (`mintFromKey`), for the keys of the jobs, webhooks and public procedures.
+ * An answer that is not IAM's decided outcome throws: "IAM could not be asked".
+ */
+export declare function bindingWorkloadTokens(binding: unknown): WorkloadTokenSource | undefined;
+/**
+ * The SPA and link mounts' files from the Workers Assets binding, whose directory mirrors the request paths: the mount
+ * `/admin` reads `admin/…` of it, the root mount the rest (the Cloudflare deploy stages each mount's `dir` there). A page
+ * route that names no file (`isPageRoute`) gets the mount's `index.html`, as `diskAssets` serves it: Workers Assets
+ * answers `<prefix>/` with it. A missing asset stays 404.
+ */
+export declare function bindingAssets(binding: unknown): SpaAssets | undefined;
+/**
+ * The service bindings to owners' proxy Workers (`FABRIKA_CONNECT_<IMPORT>`), which `captureEnvironment` keeps from
+ * the application because no `FABRIKA_*` value reaches it. A binding routes by itself: the URL it is called with
+ * carries the owner's host, which the proxy Worker selects the application by.
+ */
+export declare function connectBindings(env: Readonly<Record<string, unknown>>): Record<string, ConnectFetch>;

package/types/src/cloudflare/names.d.ts

@@ -0,0 +1,11 @@
+/** The Durable Object class the Cloudflare entry exports: one object per application environment runs it (ADR-0065). */
+export declare const CLOUDFLARE_APPLICATION_CLASS = "FabrikaApplication";
+/** The binding through which the application's Worker reaches its object. */
+export declare const CLOUDFLARE_APPLICATION_BINDING = "FABRIKA_APPLICATION";
+/** The R2 bucket binding of the environment's stored files. */
+export declare const CLOUDFLARE_FILES_BINDING = "FABRIKA_FILES";
+/**
+ * The Workers Assets binding the SPA and link mounts serve their files from. Its directory mirrors the request paths:
+ * the mount `/admin` serves `<directory>/admin/…`, the root mount `<directory>/…`.
+ */
+export declare const CLOUDFLARE_ASSETS_BINDING = "ASSETS";

package/types/src/cloudflare/ops.d.ts

@@ -0,0 +1,46 @@
+import { type ApplicationObjects, type OpsBootFailureContent, type OpsOperation } from '@fabrika/auth-core';
+import type { SqliteCursor, SqliteValue } from '@fabrika/db/sqlite';
+/** What the view reads of the object's storage; workerd's `DurableObjectStorage` has both optional members. */
+export interface OpsStorage {
+    readonly sql: {
+        exec(query: string, ...bindings: SqliteValue[]): SqliteCursor;
+        /** The bun:sqlite test double has no size. */
+        readonly databaseSize?: number;
+    };
+    /** The bun:sqlite test double has no alarm. */
+    getAlarm?(): Promise<number | null>;
+}
+/** `X-Fabrika-Endpoint` of the composed ops row, the only value an ops request may carry (ADR-0022 rule 3). */
+export declare const OPS_ENDPOINT: string;
+/** What the platform wrote for the ops channel: the key digests and the objects a request may name. */
+export interface OpsAccess {
+    readonly digests: readonly Uint8Array[];
+    readonly objects: ApplicationObjects;
+}
+/** The environment's ops access, or `null` (an older deploy, or a malformed value), which refuses every ops request. */
+export declare function opsAccess(env: Readonly<Record<string, unknown>>): OpsAccess | null;
+/** What an ops request reads of the object it reached. */
+export interface OpsTarget {
+    readonly storage: OpsStorage;
+    /**
+     * The instance's last failed boot, the application's error text included. Asked only after authentication: it
+     * waits for a boot under way and never starts one.
+     */
+    bootFailure(): Promise<OpsBootFailureContent | null>;
+}
+/**
+ * Answers an ops request the Worker forwarded with the proxy secret, which the object checked before. Authentication
+ * runs first; an unknown operation, a malformed body and an object name the list lacks are refused after it.
+ */
+export declare function serveOps(request: Request, access: OpsAccess | null, target: OpsTarget): Promise<Response>;
+/** The object an ops request names, read with its operation's strict parser; `null` for a body that does not parse. */
+export declare function objectNamed(operation: OpsOperation, body: unknown): string | null;
+/** The request's body as JSON, or `undefined` when it is none: every parser refuses `undefined`. */
+export declare function jsonBody(request: {
+    text(): Promise<string>;
+}): Promise<unknown>;
+/**
+ * Control's credentials on an ops request: the row's method, its endpoint header, and a key whose digest is one the
+ * platform wrote, compared in constant time. The Worker and the object both run it; it reads nothing the body names.
+ */
+export declare function opsAuthenticated(request: Request, access: OpsAccess): boolean;

package/types/src/cloudflare/r2-files.d.ts

@@ -0,0 +1,9 @@
+import { type FileObjectStore } from '@fabrika/platform';
+/**
+ * R2 stores a stream only when its length is known up front, which an upload's is not. A body up to this size is
+ * buffered and written in one conditional put; a longer one goes up in parts of this size, so an object holds at most
+ * one part in memory. R2 takes parts of at least 5 MiB, all but the last of one size.
+ */
+export declare const R2_PART_BYTES: number;
+/** `bucket` (an R2 binding) as the files' object store, or `undefined` when the environment binds none. */
+export declare function r2FileObjectStore(bucket: unknown): FileObjectStore | undefined;

package/types/src/cloudflare.d.ts

@@ -0,0 +1,42 @@
+import { type ContractWorkerOptions, type ImplementationLoader } from './cloudflare/application.js';
+import type { FetchService, RequestExecutionContext } from './fetch.js';
+export { markProductionProcess } from '@fabrika/db/production';
+export { type ApplicationMigration, type ApplicationState, type ApplicationStorage, type ContractWorkerOptions, FabrikaApplication, type ImplementationLoader, } from './cloudflare/application.js';
+/** Minimal structural view of a Workers `ExecutionContext`. */
+export interface CloudflareExecutionContext extends RequestExecutionContext {
+    passThroughOnException(): void;
+}
+/** Minimal structural view of a Workers cron `ScheduledController`. */
+export interface CloudflareScheduledController {
+    readonly scheduledTime: number;
+    readonly cron: string;
+    noRetry(): void;
+}
+/** Minimal structural view of a Workers queue `MessageBatch`. */
+export interface CloudflareMessageBatch {
+    readonly queue: string;
+    readonly messages: ReadonlyArray<unknown>;
+}
+export interface CloudflareWorkerOptions<Env> {
+    scheduled?: (controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext) => Promise<void>;
+    queue?: (batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext) => Promise<void>;
+}
+export interface CloudflareWorker<Env> {
+    fetch(request: Request, env: Env, exec: CloudflareExecutionContext): Promise<Response>;
+    scheduled?(controller: CloudflareScheduledController, env: Env, exec: CloudflareExecutionContext): Promise<void>;
+    queue?(batch: CloudflareMessageBatch, env: Env, exec: CloudflareExecutionContext): Promise<void>;
+}
+/** Adapt a runtime-neutral `{ fetch }` service to a Workers module export. */
+export declare function createCloudflareWorker<Env>(app: FetchService<Env>, options?: CloudflareWorkerOptions<Env>): CloudflareWorker<Env>;
+export interface ContractWorker {
+    fetch(request: Request, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<Response>;
+    scheduled(controller: CloudflareScheduledController, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<void>;
+}
+/**
+ * The Worker module of a contract application, called only by the generated entrypoint, which also exports
+ * `FabrikaApplication`. The application runs in the environment's Durable Object (ADR-0065): `fetch` forwards every
+ * request to it with the proxy secret, the proxy's own headers unchanged, and `scheduled` forwards the minute tick.
+ * An ops request goes to the object its body names instead (ADR-0069). The object captures the environment, imports
+ * the application and boots it.
+ */
+export declare function createContractWorker(load: ImplementationLoader, options?: ContractWorkerOptions): ContractWorker;

package/types/src/contract/app-id.d.ts

@@ -0,0 +1,2 @@
+/** The contract's application id rule; an id that holds to it reaches a generated script unquoted. */
+export declare const CONTRACT_APP_ID_PATTERN: RegExp;

package/types/src/contract/artifact-schema.d.ts

@@ -0,0 +1,8 @@
+import { type ContractArtifact, type OutputShape, type SchemaShape } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+/** A `SchemaShape` read back as JSON. */
+export declare const schemaShapeSchema: z.ZodType<SchemaShape>;
+export declare const outputShapeSchema: z.ZodType<OutputShape>;
+export declare const contractArtifactSchema: z.ZodType<ContractArtifact>;
+/** Parses JSON that should be a contract artifact; throws a `ZodError` naming every mismatch. */
+export declare function parseContractArtifact(value: unknown): ContractArtifact;

package/types/src/contract/attachment.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod/v4';
+import { type AttachmentDeclaration } from './declaration';
+import type { InputSchema, NotLoose, Schema } from './define';
+declare const ATTACHMENT: unique symbol;
+/** What `attachment()` adds to the rows' array schema: its declaration and its row schema. */
+export interface AttachmentMark {
+    readonly declaration: AttachmentDeclaration;
+    readonly row: InputSchema;
+}
+/** An attachment output of rows `R`: the handler returns `z.input<R>[]`, and the caller receives a file. */
+export type Attachment<R extends InputSchema> = z.ZodArray<R> & AttachmentBrand;
+/** What tells an attachment output from a JSON one in the types. */
+export interface AttachmentBrand {
+    readonly [ATTACHMENT]: AttachmentMark;
+}
+export interface AttachmentOptions<R> {
+    /**
+     * `'csv'`: RFC 4180, UTF-8 with a byte order mark, a header line of the row's field names. `'xlsx'`: one sheet, the
+     * header row of the field names, then a number, boolean or text cell per value, and a date cell for a string whose
+     * schema is `z.iso.date()` or `z.iso.datetime()`.
+     */
+    readonly format: 'csv' | 'xlsx';
+    /** The file name the browser saves: `[A-Za-z0-9._-]`, ending in `.csv` or `.xlsx`, as the format. */
+    readonly filename: string;
+    /** The row schema: a strict object of scalar fields, in the file's column order. */
+    readonly row: R;
+    /** The encoded file's limit; an encoding over it fails the invocation and sends no body. */
+    readonly maxBytes: number;
+    /** At most this many rows; 10 000 when left out. */
+    readonly maxRows?: number;
+}
+/**
+ * The output of a procedure that answers a file of `row`s. Like every builder it validates nothing: `compileContract`
+ * and the checker refuse a format, a name, a limit or a column outside what an attachment may be.
+ */
+export declare function attachment<R extends InputSchema>(options: AttachmentOptions<R & NotLoose<R>>): Attachment<R>;
+/** The rows' array schema marked with `declaration`; the static reader builds the evaluated value with it. */
+export declare function attachmentOutput<R extends InputSchema>(row: R, declaration: AttachmentDeclaration): Attachment<R>;
+/** The mark of an `attachment()` output, or `null` for any other schema. */
+export declare function attachmentOf(schema: Schema): AttachmentMark | null;
+export {};

package/types/src/contract/build.d.ts

@@ -0,0 +1,12 @@
+import { type ContractArtifact, type FileShape, type SchemaShape, type TablePolicyArtifact } from '@fabrika/auth-core';
+import { type ContractDeclaration } from './declaration';
+/** Turnstile's `action`: the procedure's endpoint id, which the verification expects back. */
+/** Validates a described contract against its table policies and normalizes it; throws `ContractError` with every problem. */
+export declare function buildArtifact(contract: ContractDeclaration<SchemaShape>, tables: Readonly<Record<string, TablePolicyArtifact>>): ContractArtifact;
+/** Whether a schema holds a file anywhere. */
+export declare function containsFile(shape: SchemaShape): boolean;
+/** The file fields of an input, by name: the parts a multipart body carries beside its JSON. */
+export declare function fileFieldsOf(input: SchemaShape | null): ReadonlyMap<string, FileShape & {
+    readonly many: boolean;
+    readonly max: number;
+}>;

package/types/src/contract/compile.d.ts

@@ -0,0 +1,11 @@
+import type { ContractArtifact, SchemaShape, TablePolicyArtifact } from '@fabrika/auth-core';
+import { type Tables } from '@fabrika/db/tables';
+import { type ContractDeclaration } from './declaration';
+import type { AnyContract } from './define';
+/**
+ * The normalized artifact of a contract and its table policies: what `defineTables` returned (`src/db/tables.ts`),
+ * or the artifact form of each policy.
+ */
+export declare function compileContract<DB, P>(contract: AnyContract, tables: Tables<DB, P> | Readonly<Record<string, TablePolicyArtifact>>): ContractArtifact;
+/** The contract with its schemas read as shapes; throws `ContractError` for a schema outside the subset. */
+export declare function describeContract(contract: AnyContract): ContractDeclaration<SchemaShape>;

package/types/src/contract/connect.d.ts

@@ -0,0 +1,51 @@
+import { type ContractArtifact, type ExportDescription } from '@fabrika/auth-core';
+import { z } from 'zod/v4';
+import type { InputSchema, Schema } from './define';
+/** One vendored procedure: the zod schemas `fabrika connect add` generated from the owner's description. */
+export interface SnapshotProcedure {
+    readonly input: InputSchema | null;
+    readonly output: Schema;
+}
+/**
+ * The vendored description of another application's export, as `fabrika connect add` writes it to
+ * `fabrika/connect/<app>.<export>.v<version>.ts`. The consumer passes it to `implement({ connect })` and imports its
+ * digest into the contract.
+ */
+export interface ConnectSnapshot {
+    readonly app: string;
+    readonly export: string;
+    readonly version: number;
+    readonly audience: string;
+    readonly digest: string;
+    /** By the procedure's dotted path in the export. */
+    readonly procedures: {
+        readonly [path: string]: SnapshotProcedure;
+    };
+}
+/** The description the owner serves for `name`, or `null` when the artifact declares no such export. */
+export declare function exportDescription(artifact: ContractArtifact, name: string): ExportDescription | null;
+/**
+ * The description a snapshot's schemas describe now, with the digest of that. A snapshot whose recomputed digest is
+ * not its own `digest` was edited after `fabrika connect add` wrote it. Throws `ContractError` for a schema outside
+ * the contract subset.
+ */
+export declare function describeSnapshot(snapshot: ConnectSnapshot): ExportDescription;
+/** The parser of a description another application served; the digest is checked by `parseExportDescription`. */
+export declare const exportDescriptionSchema: z.ZodType<ExportDescription>;
+/** A served description, parsed, whose digest is the digest of what it describes; throws `ContractError` otherwise. */
+export declare function parseExportDescription(value: unknown): ExportDescription;
+/**
+ * What an owner's change of one export version breaks for a consumer that imports `procedures` of it: a removed
+ * procedure, an input that accepts less, a changed output, or a changed audience. An output may not even gain a field,
+ * because the consumer parses every answer against its vendored schema, whose objects are strict; an input object may
+ * gain optional fields. Every other change is a new version. Empty when the change is compatible.
+ */
+export declare function incompatibleChanges(before: ExportDescription, after: ExportDescription, procedures: readonly string[]): string[];
+/**
+ * What `after` breaks for the callers of each mount `before` promises `compatibility: 'backward'`: a procedure it
+ * removes (including its generated challenge endpoint), an input or a query that accepts less, another output, another
+ * HTTP shape (method, path, body codec), file answer or access (its kind, callers, requirement and cross-origin form), or a
+ * mount moved. The promise binds the
+ * publication that drops it too, so a breaking change is a new mount beside the old one. Empty when compatible.
+ */
+export declare function incompatibleMountChanges(before: ContractArtifact, after: ContractArtifact): string[];