@fabrika/provider-cloudflare 0.9.0-dev.1 → 0.9.0-dev.11

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 (51) hide show
  1. package/package.json +17 -15
  2. package/src/authoring.ts +56 -6
  3. package/src/bounds.ts +145 -4
  4. package/src/cli-args.ts +2 -2
  5. package/src/cli.ts +14 -0
  6. package/src/command.ts +29 -4
  7. package/src/contract-support.ts +235 -0
  8. package/src/control.ts +55 -118
  9. package/src/deploy-order.ts +35 -0
  10. package/src/index.ts +19 -3
  11. package/src/installation/init.ts +11 -18
  12. package/src/installation/installation.ts +2 -4
  13. package/src/installation/scaffold.ts +29 -2
  14. package/src/installation/templates/README.md +30 -12
  15. package/src/installation/templates/platform.yml +12 -5
  16. package/src/managed-secrets.ts +61 -0
  17. package/src/plan.ts +13 -3
  18. package/src/provider.ts +467 -64
  19. package/src/proxy-worker.ts +40 -16
  20. package/src/proxy.ts +48 -16
  21. package/src/runner-protocol.ts +35 -2
  22. package/src/spa-assets.ts +176 -0
  23. package/types/src/assets.d.ts +8 -0
  24. package/types/src/authoring.d.ts +39 -0
  25. package/types/src/bounds.d.ts +84 -0
  26. package/types/src/checkout.d.ts +7 -0
  27. package/types/src/cli-args.d.ts +25 -0
  28. package/types/src/cli.d.ts +8 -0
  29. package/types/src/codec.d.ts +8 -0
  30. package/types/src/collaborators.d.ts +52 -0
  31. package/types/src/command.d.ts +54 -0
  32. package/types/src/config-schema.d.ts +9 -0
  33. package/types/src/contract-support.d.ts +80 -0
  34. package/types/src/control.d.ts +503 -0
  35. package/types/src/deploy-order.d.ts +8 -0
  36. package/types/src/index.d.ts +18 -0
  37. package/types/src/installation/cloudflare.d.ts +40 -0
  38. package/types/src/installation/envfile.d.ts +39 -0
  39. package/types/src/installation/index.d.ts +2 -0
  40. package/types/src/installation/init-options.d.ts +59 -0
  41. package/types/src/installation/init.d.ts +114 -0
  42. package/types/src/installation/installation.d.ts +2 -0
  43. package/types/src/installation/scaffold.d.ts +39 -0
  44. package/types/src/managed-secrets.d.ts +19 -0
  45. package/types/src/plan.d.ts +21 -0
  46. package/types/src/provider.d.ts +98 -0
  47. package/types/src/proxy-worker.d.ts +15 -0
  48. package/types/src/proxy.d.ts +72 -0
  49. package/types/src/runner-protocol.d.ts +142 -0
  50. package/types/src/schema.d.ts +17 -0
  51. package/types/src/spa-assets.d.ts +28 -0
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env bun
2
+ import type { AppCli } from '@fabrika/provider-contract/app-cli';
3
+ export declare const runCloudflareCli: (argv: readonly string[]) => Promise<void>;
4
+ /**
5
+ * What `fabrika app build` and `app deploy` run for an application on Cloudflare. A contract application's build is its
6
+ * generated Worker entry, which the `fabrika` command writes; there is nothing else to build.
7
+ */
8
+ export declare const appCli: AppCli;
@@ -0,0 +1,8 @@
1
+ import type { ProviderCodec } from '@fabrika/provider-contract';
2
+ /** A checkout recipe. The Oblaka graph stays executable code in the referenced config module. */
3
+ export interface CloudflareArtifact {
4
+ readonly configPath: string;
5
+ }
6
+ export declare const cloudflareArtifactCodec: ProviderCodec<CloudflareArtifact>;
7
+ /** Build the default checkout recipe used by the Cloudflare runner. */
8
+ export declare const cloudflareArtifact: (configPath?: string) => CloudflareArtifact;
@@ -0,0 +1,52 @@
1
+ import type { ContractArtifact } from '@fabrika/auth-core';
2
+ import type { SchemaReconciler } from '@fabrika/provider-contract';
3
+ import { type Definition, type DeployResult as OblakaDeployResult } from 'oblaka-iac';
4
+ import { type CloudflareAppConfig } from './authoring';
5
+ import { type RunnerOutcomeFile } from './runner-protocol';
6
+ export interface CommandSpec {
7
+ readonly command: string;
8
+ readonly args: string[];
9
+ readonly cwd: string;
10
+ readonly env?: Record<string, string>;
11
+ /** Names dropped from the INHERITED environment: a child that runs checkout code gets no platform credential. */
12
+ readonly omitEnv?: readonly string[];
13
+ readonly stdin?: string;
14
+ readonly signal?: AbortSignal;
15
+ }
16
+ export interface CommandResult {
17
+ readonly exitCode: number;
18
+ readonly stdout: string;
19
+ readonly stderr: string;
20
+ }
21
+ export type CommandRunner = (spec: CommandSpec) => Promise<CommandResult>;
22
+ export interface ProvisionInput {
23
+ readonly definition: Definition;
24
+ readonly accountId: string;
25
+ readonly apiToken: string;
26
+ readonly env: string;
27
+ readonly cwd: string;
28
+ readonly stateNamespace: string;
29
+ readonly dryRun: boolean;
30
+ }
31
+ export type OblakaProvisioner = (input: ProvisionInput) => Promise<OblakaDeployResult>;
32
+ /** Hand the run's outcome back to the runner, which folds it into the terminal status the control plane reads. */
33
+ export type OutcomeWriter = (outcome: RunnerOutcomeFile) => Promise<void>;
34
+ export interface LoadedCloudflareConfig {
35
+ readonly config: CloudflareAppConfig;
36
+ readonly cwd: string;
37
+ }
38
+ export type CloudflareConfigLoader = (cwd: string, configPath: string) => Promise<LoadedCloudflareConfig>;
39
+ /** The contract an application root declares, or null when it has no `fabrika.contract.ts`. */
40
+ export type ContractReader = (root: string) => Promise<ContractArtifact | null>;
41
+ export interface CloudflareCollaborators {
42
+ readonly loadConfig: CloudflareConfigLoader;
43
+ readonly readContract: ContractReader;
44
+ readonly runCommand: CommandRunner;
45
+ readonly provision: OblakaProvisioner;
46
+ readonly writeOutcome: OutcomeWriter;
47
+ }
48
+ export declare const loadCloudflareConfig: (cwd: string, configPath: string) => Promise<LoadedCloudflareConfig & {
49
+ readonly absolutePath: string;
50
+ }>;
51
+ export declare const defaultCloudflareCollaborators: CloudflareCollaborators;
52
+ export type { SchemaReconciler };
@@ -0,0 +1,54 @@
1
+ import { type AppEnvironment, type ApplicationObjects } from '@fabrika/auth-core';
2
+ import type { CloudflareAppConfig } from './authoring';
3
+ import { type CloudflareDeployResult, type PlatformIamTarget } from './provider';
4
+ import { type RunnerApprovedAccess } from './runner-protocol';
5
+ /**
6
+ * Decode `FABRIKA_IAM_RETURN_ORIGINS`, the comma-separated set the installation's workflow hands the
7
+ * platform's own deploy (ADR-0022). Undefined for an absent or empty value, so a deploy with nothing to
8
+ * project leaves IAM's registry alone rather than clearing it. Part of the executor's environment
9
+ * contract, exported for the test that pins it; not part of the package's public surface.
10
+ */
11
+ export declare const parseReturnOrigins: (raw: string | undefined) => readonly string[] | undefined;
12
+ /**
13
+ * Decode `FABRIKA_CROSS_ORIGINS`, the environment's cross-origin list as the runner writes it. Undefined when absent or
14
+ * empty; anything malformed fails the deploy, and the proxy manifest's own parser judges each origin.
15
+ */
16
+ export declare const parseCrossOrigins: (raw: string | undefined) => readonly string[] | undefined;
17
+ /**
18
+ * Decode `FABRIKA_RUNNER_APPLICATION_OBJECTS`, the pointer Control recorded, as the runner writes it. Undefined when
19
+ * absent, and the deployer writes its defaults; anything malformed fails the deploy rather than move ordinary traffic.
20
+ */
21
+ export declare const parseApplicationObjectsEnvironment: (raw: string | undefined) => ApplicationObjects | undefined;
22
+ /**
23
+ * Decode `FABRIKA_INSTALLATION_APPS`, the Cloudflare deployments Control registered, as the runner writes it.
24
+ * Undefined when absent; anything malformed fails the deploy rather than dropping the refusal it feeds.
25
+ */
26
+ export declare const parseInstallationApps: (raw: string | undefined) => readonly AppEnvironment[] | undefined;
27
+ /**
28
+ * Read the access Control approved for this run from the file at `FABRIKA_APPROVED_ACCESS_FILE`, as the runner
29
+ * writes it. Undefined when no runner set it (a local deploy); a file that is unreadable or malformed fails the deploy
30
+ * rather than falling back to the checkout.
31
+ */
32
+ export declare const readApprovedAccess: (path: string | undefined) => Promise<RunnerApprovedAccess | undefined>;
33
+ export interface LoadedCloudflareCommandConfig {
34
+ readonly config: CloudflareAppConfig;
35
+ readonly absolutePath: string;
36
+ readonly cwd: string;
37
+ }
38
+ export declare const loadCloudflareCommandConfig: (configPath: string, cwd: string) => Promise<LoadedCloudflareCommandConfig>;
39
+ export interface CloudflareCommandDeployOptions {
40
+ readonly env: string;
41
+ readonly configPath?: string;
42
+ readonly cwd?: string;
43
+ readonly dryRun?: boolean;
44
+ readonly stateNamespace?: string;
45
+ readonly managedVarNames?: readonly string[];
46
+ /** Defaults to `refuse`: only fabrika deploying its own components may name a platform resource. */
47
+ readonly platformResources?: 'refuse' | 'allow';
48
+ /** Where a platform deploy registers a component's schema (ADR-0058); only the installation sets it. */
49
+ readonly platformIam?: PlatformIamTarget;
50
+ readonly signal?: AbortSignal;
51
+ readonly log?: (line: string) => void;
52
+ }
53
+ /** Deploy one config with the account credentials, declared secrets and vars read from the environment. */
54
+ export declare const deployCloudflareConfig: (options: CloudflareCommandDeployOptions) => Promise<CloudflareDeployResult>;
@@ -0,0 +1,9 @@
1
+ import type { AppSchema } from '@fabrika/auth-core';
2
+ /**
3
+ * A config's IAM schema, parsed and deep-frozen. A config that still declares `gates` is refused: an application is
4
+ * protected by the endpoint table of its `fabrika.contract.ts`, and the platform's own services by theirs.
5
+ */
6
+ export declare const configSchema: (config: {
7
+ readonly gates?: unknown;
8
+ readonly schema?: unknown;
9
+ }) => AppSchema | null;
@@ -0,0 +1,80 @@
1
+ import { type ContractArtifact } from '@fabrika/auth-core';
2
+ import type { ProviderManagedEnvironment } from '@fabrika/provider-contract';
3
+ /**
4
+ * The longest a procedure's or a webhook's handler may run on Cloudflare. It runs inside the object's transaction, and
5
+ * workerd resets an object whose transaction runs about 30 s (docs/reference/cloudflare-platform.md).
6
+ */
7
+ export declare const CLOUDFLARE_MAX_HANDLER_MS = 25000;
8
+ /** What the release a caller runs a contract as decides about it; each caller reads them off that release. */
9
+ export interface CloudflareContractGates {
10
+ /** The release caps a job at one segment (`capsJobSegments`). */
11
+ readonly capsSegments: boolean;
12
+ /** The release runs `ctx.sql` on the object's SQLite (`servesRawSql`). */
13
+ readonly servesSql: boolean;
14
+ }
15
+ /**
16
+ * Refuse what a contract declares that an application on Cloudflare cannot run yet (ADR-0065): a file kind that scans
17
+ * its uploads, a handler allowed to outlive the object's transaction limit, and, by the release it runs as, a job longer
18
+ * than one segment and raw SQL (`ctx.sql`).
19
+ */
20
+ export declare const assertCloudflareContract: (contract: ContractArtifact, { capsSegments, servesSql }: CloudflareContractGates) => void;
21
+ /**
22
+ * The object runs due jobs and the file sweep of file kinds, a framework job, from the Worker's cron trigger: the minute
23
+ * tick, or from `servesAlarms` its alarm with an hourly repair tick (ADR-0065 §5). Legacy `files` collections do not
24
+ * count: the object schedules no sweep of theirs.
25
+ */
26
+ export declare const needsMinuteTick: (contract: ContractArtifact) => boolean;
27
+ /**
28
+ * Whether framework release `release` is at least `since`. A prerelease counts as its `major.minor`; a release that
29
+ * does not start with `<major>.<minor>.` is never at least anything (ADR-0062).
30
+ */
31
+ export declare const releaseAtLeast: (release: string, since: {
32
+ readonly major: number;
33
+ readonly minor: number;
34
+ }) => boolean;
35
+ /**
36
+ * Whether an application on framework release `release` runs in its Durable Object. An older release's entry is a
37
+ * stateless Worker, which the platform keeps deploying in its old shape (ADR-0062).
38
+ */
39
+ export declare const runsInObject: (release: string) => boolean;
40
+ /** Whether the Cloudflare deploy of release `release` accepts only the generated entry and regenerates it. */
41
+ export declare const pinsGeneratedEntry: (release: string) => boolean;
42
+ /** Whether an environment on release `release` gets the ops row, the ops key digests and the object variables. */
43
+ export declare const servesOps: (release: string) => boolean;
44
+ /**
45
+ * Whether framework release `release` is at or above the exact version `since` in semver's precedence, prerelease
46
+ * included; a release that is not a semver version never is (ADR-0062).
47
+ */
48
+ export declare const releaseFrom: (release: string, since: string) => boolean;
49
+ /**
50
+ * The release a gate reads for an approved access: the application's pin, never the reader's `checker`, which is this
51
+ * platform's patch of the pin's minor and so passes a `releaseFrom` gate a prerelease pin does not. An access approved before Control recorded the pin is read as the oldest release of its
52
+ * reader's minor (`<major>.<minor>.0-0`): every `releaseAtLeast` gate answers as for that minor, and every `releaseFrom`
53
+ * gate of a prerelease or a patch fails closed, as for an older application, until a deploy reads its pin.
54
+ */
55
+ export declare const applicationRelease: (access: {
56
+ readonly checker: string;
57
+ readonly framework?: string;
58
+ }) => string;
59
+ /**
60
+ * Whether the object of release `release` holds the maintenance barrier and serves Control's data operations: the
61
+ * backups, the migration phase and the side restore (ADR-0069 §3, ADR-0070).
62
+ */
63
+ export declare const servesDataOperations: (release: string) => boolean;
64
+ /**
65
+ * Whether the Worker of release `release` gets the hourly repair tick instead of the minute tick: an older object runs
66
+ * its jobs only from the minute tick and has no alarm.
67
+ */
68
+ export declare const servesAlarms: (release: string) => boolean;
69
+ /**
70
+ * Whether the Cloudflare deploy of release `release` refuses a job whose `timeoutMs` exceeds one segment
71
+ * (`CLOUDFLARE_MAX_JOB_SEGMENT_MS`). An older release deploys as it did (ADR-0062).
72
+ */
73
+ export declare const capsJobSegments: (release: string) => boolean;
74
+ /** Whether an application on release `release` may declare `sql` on Cloudflare. */
75
+ export declare const servesRawSql: (release: string) => boolean;
76
+ /**
77
+ * Refuse what a stateless Worker of an older release cannot run: a job, a webhook, a public procedure, installation
78
+ * mail and token purposes all need the object's database or a Worker secret it never reads.
79
+ */
80
+ export declare const assertStatelessEnvironment: (managed: ProviderManagedEnvironment, release: string) => void;