@pithy-sh/storage 0.1.2 → 0.1.3

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 (86) hide show
  1. package/dist/capability.d.ts +43 -0
  2. package/dist/capability.d.ts.map +1 -0
  3. package/dist/capability.js +74 -0
  4. package/dist/config/config.d.ts +25 -0
  5. package/dist/config/config.d.ts.map +1 -0
  6. package/dist/config/config.js +47 -0
  7. package/dist/data/share.d.ts +25 -0
  8. package/dist/data/share.d.ts.map +1 -0
  9. package/dist/data/share.js +26 -0
  10. package/dist/data/storageObject.d.ts +53 -0
  11. package/dist/data/storageObject.d.ts.map +1 -0
  12. package/dist/data/storageObject.js +42 -0
  13. package/dist/data/tables.d.ts +21 -0
  14. package/dist/data/tables.d.ts.map +1 -0
  15. package/dist/data/tables.js +24 -0
  16. package/dist/error/errors.d.ts +58 -0
  17. package/dist/error/errors.d.ts.map +1 -0
  18. package/dist/error/errors.js +87 -0
  19. package/dist/http/guard.d.ts +18 -0
  20. package/dist/http/guard.d.ts.map +1 -0
  21. package/dist/http/guard.js +27 -0
  22. package/dist/http/handlers.d.ts +230 -0
  23. package/dist/http/handlers.d.ts.map +1 -0
  24. package/dist/http/handlers.js +505 -0
  25. package/dist/http/routes.d.ts +68 -0
  26. package/dist/http/routes.d.ts.map +1 -0
  27. package/dist/http/routes.js +133 -0
  28. package/dist/http/schemas.d.ts +72 -0
  29. package/dist/http/schemas.d.ts.map +1 -0
  30. package/dist/http/schemas.js +91 -0
  31. package/dist/http/serve.d.ts +119 -0
  32. package/dist/http/serve.d.ts.map +1 -0
  33. package/dist/http/serve.js +207 -0
  34. package/dist/index.d.ts +21 -0
  35. package/dist/index.d.ts.map +1 -0
  36. package/dist/index.js +12 -0
  37. package/dist/migrations/0001_objects.d.ts +22 -0
  38. package/dist/migrations/0001_objects.d.ts.map +1 -0
  39. package/dist/migrations/0001_objects.js +39 -0
  40. package/dist/object/cloudflare.d.ts +21 -0
  41. package/dist/object/cloudflare.d.ts.map +1 -0
  42. package/dist/object/cloudflare.js +46 -0
  43. package/dist/object/key.d.ts +27 -0
  44. package/dist/object/key.d.ts.map +1 -0
  45. package/dist/object/key.js +35 -0
  46. package/dist/object/multipart.d.ts +76 -0
  47. package/dist/object/multipart.d.ts.map +1 -0
  48. package/dist/object/multipart.js +129 -0
  49. package/dist/object/store.d.ts +201 -0
  50. package/dist/object/store.d.ts.map +1 -0
  51. package/dist/object/store.js +176 -0
  52. package/dist/provision/provisionStorage.d.ts +137 -0
  53. package/dist/provision/provisionStorage.d.ts.map +1 -0
  54. package/dist/provision/provisionStorage.js +110 -0
  55. package/dist/provision/resolveStorageConfig.d.ts +43 -0
  56. package/dist/provision/resolveStorageConfig.d.ts.map +1 -0
  57. package/dist/provision/resolveStorageConfig.js +31 -0
  58. package/dist/quota/quota.d.ts +125 -0
  59. package/dist/quota/quota.d.ts.map +1 -0
  60. package/dist/quota/quota.js +100 -0
  61. package/dist/secret/registry.d.ts +70 -0
  62. package/dist/secret/registry.d.ts.map +1 -0
  63. package/dist/secret/registry.js +82 -0
  64. package/dist/seeds/example.d.ts +3 -0
  65. package/dist/seeds/example.d.ts.map +1 -0
  66. package/dist/seeds/example.js +109 -0
  67. package/dist/test-utils/liveStorage.d.ts +50 -0
  68. package/dist/test-utils/liveStorage.d.ts.map +1 -0
  69. package/dist/test-utils/liveStorage.js +196 -0
  70. package/dist/version.generated.d.ts +5 -0
  71. package/dist/version.generated.d.ts.map +1 -0
  72. package/dist/version.generated.js +7 -0
  73. package/dist/workflows/retryPolicy.d.ts +37 -0
  74. package/dist/workflows/retryPolicy.d.ts.map +1 -0
  75. package/dist/workflows/retryPolicy.js +41 -0
  76. package/dist/workflows/specs.d.ts +55 -0
  77. package/dist/workflows/specs.d.ts.map +1 -0
  78. package/dist/workflows/specs.js +58 -0
  79. package/dist/workflows/sweep.d.ts +82 -0
  80. package/dist/workflows/sweep.d.ts.map +1 -0
  81. package/dist/workflows/sweep.js +143 -0
  82. package/dist/workflows/worker.d.ts +49 -0
  83. package/dist/workflows/worker.d.ts.map +1 -0
  84. package/dist/workflows/worker.js +50 -0
  85. package/package.json +22 -11
  86. package/src/version.generated.ts +1 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/object/store.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,176 @@
1
+ import { r2CredentialsRegistry } from "../secret/registry.js";
2
+ import { r2Presigned } from "./cloudflare.js";
3
+ import { z } from "zod";
4
+ import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
5
+ //#region src/object/store.ts
6
+ /**
7
+ * `ObjectStore` — the object-plane seam, and the one piece of this package that is reusable outside it.
8
+ *
9
+ * **The load-bearing constraint: this module imports no D1, no routes, and no storage config.** It is
10
+ * constructed over an injected bucket binding and a *named* credential secret, which is exactly what
11
+ * lets `@pithy-sh/media` import it, point it at `MEDIA_BUCKET` under `media-r2-credentials`, and
12
+ * inherit none of storage's tables, routes, or opaque-key policy. Adding `@pithy-sh/storage` to media
13
+ * must not mount storage's routes or create `pithy_storage_objects`; keeping this file free of those
14
+ * imports is what guarantees it.
15
+ *
16
+ * It is **mechanism only**. It takes an explicit key and moves bytes. Key policy lives in `key.ts` and
17
+ * in the handlers: storage derives `obj/<uuid>`, media passes `media/<type>/<id>`, and neither knows
18
+ * the other's scheme.
19
+ *
20
+ * **Bindings inside the Worker, S3 outside it** (CLAUDE.md §Cloudflare access). Reads, head, list and
21
+ * delete go through the `R2Bucket` binding — no credentials, no round trip, and a body that streams.
22
+ * Presigned URLs, the multipart lifecycle, and server-side copy have no binding equivalent that keeps
23
+ * bytes out of the Worker, so they go over the S3 protocol through `@pithy-sh/cloudflare`. The seam
24
+ * hides which is which; only `object/cloudflare.ts` touches the manager.
25
+ *
26
+ * Every response crossing the seam is Zod-validated, so an unexpected shape fails loudly at the
27
+ * boundary rather than surfacing as `undefined` three layers up.
28
+ */
29
+ /** An object's metadata, as either a HEAD or a GET reports it. */
30
+ const ObjectMetadata = z.object({
31
+ key: z.string().min(1).describe("The R2 object key. Opaque to the caller — policy lives in `key.ts`."),
32
+ size: z.number().int().nonnegative().describe("The whole object's size in bytes, not the served range's."),
33
+ etag: z.string().min(1).describe("R2's entity tag for this object version, unquoted. Quote it before it becomes an `ETag` header."),
34
+ contentType: z.string().min(1).optional().describe("The stored `Content-Type`. Absent when the object was written without one."),
35
+ contentDisposition: z.string().min(1).optional().describe("The stored `Content-Disposition`, when one was written. Recorded, not honored — the serve path derives its own, because this string is whatever the uploader sent."),
36
+ uploaded: z.date().describe("When R2 wrote this object version."),
37
+ checksumSha256: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("Lowercase hex SHA-256, when R2 holds one. Absent unless the upload supplied or requested it.")
38
+ }).describe("One object's metadata — everything a serve path needs without transferring the body.");
39
+ /** Which bytes of an object to read. Mirrors R2's own range shapes; exactly one form is meaningful. */
40
+ const ObjectRange = z.object({
41
+ offset: z.number().int().nonnegative().optional().describe("First byte to read, from the start of the object."),
42
+ length: z.number().int().positive().optional().describe("How many bytes to read from `offset`."),
43
+ suffix: z.number().int().positive().optional().describe("Read this many bytes from the *end* — `bytes=-N`.")
44
+ }).describe("A byte range to read, as an HTTP `Range` header maps onto R2.");
45
+ /** Preconditions a read must satisfy, so a conditional request can answer 304 without moving bytes. */
46
+ const ObjectConditions = z.object({
47
+ etagMatches: z.string().min(1).optional().describe("Read only if the object's etag equals this (`If-Match`)."),
48
+ etagDoesNotMatch: z.string().min(1).optional().describe("Read only if the object's etag differs (`If-None-Match`) — the 304 path."),
49
+ uploadedBefore: z.date().optional().describe("Read only if the object was written before this (`If-Unmodified-Since`)."),
50
+ uploadedAfter: z.date().optional().describe("Read only if the object was written after this (`If-Modified-Since`).")
51
+ }).describe("Conditional-read preconditions. R2 returns metadata with no body when one fails.");
52
+ /** One page of a bucket listing — the sweep's view, distinct from the D1 listing an owner sees. */
53
+ const ObjectListing = z.object({
54
+ objects: z.array(ObjectMetadata).describe("This page's objects, in R2's lexicographic key order."),
55
+ cursor: z.string().min(1).optional().describe("Continuation cursor for the next page. Absent means this page was the last.")
56
+ }).describe("One page of a bucket listing. Pagination is caller-driven — pass `cursor` back to advance.");
57
+ /** One part already stored against an in-flight multipart upload — what makes an upload resumable. */
58
+ const UploadedPart = z.object({
59
+ partNumber: z.number().int().min(1).describe("The part's 1-based index within the upload."),
60
+ etag: z.string().min(1).describe("The part's entity tag, verbatim. Pass it back unchanged to complete."),
61
+ size: z.number().int().nonnegative().describe("The part's size in bytes, as R2 stored it.")
62
+ }).describe("One uploaded part — the unit a resumed upload skips re-sending.");
63
+ /** Map our range shape onto R2's — the binding's union admits exactly one of these three forms. */
64
+ function toR2Range(range) {
65
+ if (!range) return void 0;
66
+ if (range.suffix !== void 0) return { suffix: range.suffix };
67
+ if (range.offset !== void 0 && range.length !== void 0) return {
68
+ offset: range.offset,
69
+ length: range.length
70
+ };
71
+ if (range.offset !== void 0) return { offset: range.offset };
72
+ if (range.length !== void 0) return { length: range.length };
73
+ }
74
+ /** Lowercase hex for a checksum R2 hands back as raw bytes. */
75
+ function toHex(buffer) {
76
+ return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
77
+ }
78
+ /** Validate an `R2Object` into {@link ObjectMetadata} — the one place binding shapes cross the seam. */
79
+ function toMetadata(object) {
80
+ return ObjectMetadata.parse({
81
+ key: object.key,
82
+ size: object.size,
83
+ etag: object.etag,
84
+ contentType: object.httpMetadata?.contentType,
85
+ contentDisposition: object.httpMetadata?.contentDisposition,
86
+ uploaded: object.uploaded,
87
+ checksumSha256: object.checksums?.sha256 ? toHex(object.checksums.sha256) : void 0
88
+ });
89
+ }
90
+ /**
91
+ * Build an object store over a bucket binding and a named credential secret.
92
+ *
93
+ * Credentials resolve **lazily, once**: a read-only worker that never presigns never touches the
94
+ * secrets store, and a worker that presigns twice resolves once. The promise itself is memoized, so
95
+ * two concurrent presigns share one resolution rather than racing two.
96
+ */
97
+ function objectStore(options) {
98
+ const secretName = options.secretName ?? "storage-r2-credentials";
99
+ const build = options.presigned ?? r2Presigned;
100
+ const bucket = options.bucket;
101
+ let presignedPromise = null;
102
+ function presigned() {
103
+ if (!presignedPromise) presignedPromise = (async () => {
104
+ const registry = r2CredentialsRegistry(secretName);
105
+ const store = await sharedSecretsStore(options.env, registry);
106
+ return build(store.get(secretName));
107
+ })();
108
+ return presignedPromise;
109
+ }
110
+ return {
111
+ async presignPut(key, contentType, contentLength, presignOptions) {
112
+ return (await presigned()).presignPut(key, contentType, contentLength, presignOptions);
113
+ },
114
+ async presignGet(key, presignOptions) {
115
+ return (await presigned()).presignGet(key, presignOptions);
116
+ },
117
+ async initMultipart(key, contentType) {
118
+ return (await presigned()).createMultipartUpload(key, contentType);
119
+ },
120
+ async presignPart(key, uploadId, partNumber, presignOptions) {
121
+ return (await presigned()).presignUploadPart(key, uploadId, partNumber, presignOptions);
122
+ },
123
+ async completeMultipart(key, uploadId, parts) {
124
+ await (await presigned()).completeMultipartUpload(key, uploadId, parts);
125
+ },
126
+ async abortMultipart(key, uploadId) {
127
+ await (await presigned()).abortMultipartUpload(key, uploadId);
128
+ },
129
+ async listParts(key, uploadId) {
130
+ return (await presigned()).listParts(key, uploadId);
131
+ },
132
+ async get(key, getOptions) {
133
+ const conditions = getOptions?.onlyIf;
134
+ const object = await bucket.get(key, {
135
+ range: toR2Range(getOptions?.range),
136
+ onlyIf: conditions ? conditions : void 0
137
+ });
138
+ if (!object) return null;
139
+ const body = "body" in object ? object.body : null;
140
+ const served = getOptions?.range && object.range ? object.range : void 0;
141
+ const offset = served && "offset" in served ? served.offset ?? 0 : 0;
142
+ const length = served && "length" in served ? served.length ?? 0 : 0;
143
+ return {
144
+ metadata: toMetadata(object),
145
+ body,
146
+ range: served ? {
147
+ offset,
148
+ length
149
+ } : null
150
+ };
151
+ },
152
+ async head(key) {
153
+ const object = await bucket.head(key);
154
+ return object ? toMetadata(object) : null;
155
+ },
156
+ async list(listOptions) {
157
+ const page = await bucket.list({
158
+ prefix: listOptions?.prefix,
159
+ cursor: listOptions?.cursor,
160
+ limit: listOptions?.limit
161
+ });
162
+ return ObjectListing.parse({
163
+ objects: page.objects.map(toMetadata),
164
+ cursor: page.truncated ? page.cursor : void 0
165
+ });
166
+ },
167
+ async copy(sourceKey, destinationKey) {
168
+ await (await presigned()).copyObject(sourceKey, destinationKey);
169
+ },
170
+ async delete(key) {
171
+ await bucket.delete(key);
172
+ }
173
+ };
174
+ }
175
+ //#endregion
176
+ export { ObjectConditions, ObjectListing, ObjectMetadata, ObjectRange, UploadedPart, objectStore };
@@ -0,0 +1,137 @@
1
+ import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
2
+ import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
3
+ /**
4
+ * The provisioning orchestration for the storage capability — the live counterpart to
5
+ * `pithy add storage`'s config wiring.
6
+ *
7
+ * The split is deliberate and worth stating, because the two commands look like one. `pithy add`
8
+ * writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
9
+ * `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
10
+ * nothing — an `add` that reached out to an account would make adding a capability an operation you
11
+ * could not do offline, or in CI, or without credentials. This command stands up what those bindings
12
+ * point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
13
+ *
14
+ * The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
15
+ * Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
16
+ * per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
17
+ * CLI writes the complete entry here, once the host worker exists.
18
+ *
19
+ * The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
20
+ * orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
21
+ * records its call order, and no account. **Every step is idempotent**: find-then-create for the
22
+ * bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
23
+ *
24
+ * **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
25
+ * here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
26
+ * and written into the secret as given. That is a real limitation, and the manifest says so rather
27
+ * than promising a mint that does not happen.
28
+ */
29
+ /**
30
+ * The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
31
+ * `acme-prod-storage`.
32
+ *
33
+ * One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
34
+ * teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
35
+ * buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
36
+ * `@pithy-sh/email`'s deliberately project-shared suppression database.
37
+ *
38
+ * The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
39
+ * account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
40
+ * same account and silently adopted — two apps writing objects into one bucket, and either teardown
41
+ * deleting both. The name is the only partition R2 offers, so the name carries the owner.
42
+ *
43
+ * Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
44
+ * genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
45
+ * writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
46
+ * keeps it on purpose.
47
+ */
48
+ export declare function storageBucketName(project: string, env: ManagedEnvironment): string;
49
+ /**
50
+ * The deployed sweep-worker name for a project's environment — also its resolved config's basename.
51
+ *
52
+ * A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
53
+ * cannot be renamed once a deploy or a `service` binding points at it.
54
+ */
55
+ export declare function storageWorkerName(project: string, env: ManagedEnvironment): string;
56
+ /** The provisioned resources an environment's worker and secret are wired to. */
57
+ export interface StorageResources {
58
+ /** The R2 bucket objects live in. */
59
+ bucketName: string;
60
+ }
61
+ /** The live Cloudflare/wrangler seam. Each step must be idempotent. */
62
+ export interface StorageProvisioner {
63
+ /**
64
+ * Verify account prerequisites before any resource is created — most importantly a registered
65
+ * `workers.dev` subdomain, which Cloudflare requires to deploy a Workflow-hosting worker. Failing
66
+ * here means failing before a bucket exists, rather than half way through a fan-out.
67
+ */
68
+ preflight(): Promise<void>;
69
+ /** Create (or reuse) this environment's R2 bucket; returns its name. Idempotent. */
70
+ ensureBucket(env: ManagedEnvironment): Promise<{
71
+ bucketName: string;
72
+ }>;
73
+ /**
74
+ * Write this environment's `storage-r2-credentials` secret — the account id, S3 key pair, scoped
75
+ * token, and bucket name the object store presigns with. Idempotent (create, else update). Runs
76
+ * before the worker is deployed: a worker that boots without its credentials fails on its first
77
+ * multipart abort.
78
+ */
79
+ writeCredentials(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
80
+ /** Deploy the prebuilt sweep worker for this environment, wired to the provisioned bucket. */
81
+ deployWorker(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
82
+ }
83
+ /** What provisioning produced, per environment. */
84
+ export interface StorageProvisionResult {
85
+ /** Each environment provisioned, with the resources its worker and secret were wired to. */
86
+ environments: Array<{
87
+ env: ManagedEnvironment;
88
+ } & StorageResources>;
89
+ }
90
+ /**
91
+ * Provision the storage infrastructure: check the account, create every environment's bucket, write
92
+ * every environment's credentials, then deploy every environment's sweep worker.
93
+ *
94
+ * The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
95
+ * must not boot before the secret it reads. Fanning each phase across all environments — rather than
96
+ * completing one environment end to end before starting the next — means a failure creating prod's
97
+ * bucket stops the run before staging's worker is deployed against a half-provisioned account.
98
+ *
99
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
100
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
101
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
102
+ */
103
+ export declare function provisionStorage(provisioner: StorageProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<StorageProvisionResult>;
104
+ /** The teardown seam — the inverse of {@link StorageProvisioner}. Every step idempotent. */
105
+ export interface StorageDeprovisioner {
106
+ /** Delete this environment's sweep worker. Idempotent (a missing worker is a no-op). */
107
+ deleteWorker(env: ManagedEnvironment): Promise<void>;
108
+ /**
109
+ * Delete this environment's R2 bucket **and every file in it**. **Destructive** — nothing here is
110
+ * recoverable. Idempotent (a missing bucket is a no-op).
111
+ *
112
+ * Emptying the bucket is part of the contract, not a nicety: R2 refuses to delete a bucket that still
113
+ * holds an object, or the parts of a multipart upload that was never completed. An implementation that
114
+ * only called the control-plane delete would work on an untouched bucket and fail on every bucket
115
+ * anyone had used.
116
+ */
117
+ deleteBucket(env: ManagedEnvironment): Promise<void>;
118
+ }
119
+ /** Teardown options. By default the stored files are **kept** — only the sweep workers come down. */
120
+ export interface StorageDeprovisionOptions {
121
+ /**
122
+ * Also delete the R2 buckets, with every file in them. Off by default, because those files are the
123
+ * adopter's data and no deploy can restore them — the flag is the confirmation.
124
+ */
125
+ deleteStorage?: boolean;
126
+ }
127
+ /**
128
+ * Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
129
+ * sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
130
+ * everything in them. Idempotent end to end.
131
+ *
132
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
133
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
134
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
135
+ */
136
+ export declare function deprovisionStorage(deprovisioner: StorageDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: StorageDeprovisionOptions): Promise<void>;
137
+ //# sourceMappingURL=provisionStorage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provisionStorage.d.ts","sourceRoot":"","sources":["../../src/provision/provisionStorage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAElF,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,6BAA6B,CAAC;AAG3F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAElF;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,oFAAoF;IACpF,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,8FAA8F;IAC9F,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,4FAA4F;IAC5F,YAAY,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,kBAAkB,CAAA;KAAE,GAAG,gBAAgB,CAAC,CAAC;CACrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,sBAAsB,CAAC,CAiBjC;AASD,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;;;;OAQG;IACH,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED,qGAAqG;AACrG,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,oBAAoB,EACnC,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,EACtD,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CASf"}
@@ -0,0 +1,110 @@
1
+ import { STORAGE_CAPABILITY } from "../workflows/specs.js";
2
+ import { InternalError } from "@pithy-sh/core/src/error/pithyError";
3
+ import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
4
+ import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
5
+ //#region src/provision/provisionStorage.ts
6
+ /**
7
+ * The provisioning orchestration for the storage capability — the live counterpart to
8
+ * `pithy add storage`'s config wiring.
9
+ *
10
+ * The split is deliberate and worth stating, because the two commands look like one. `pithy add`
11
+ * writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
12
+ * `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
13
+ * nothing — an `add` that reached out to an account would make adding a capability an operation you
14
+ * could not do offline, or in CI, or without credentials. This command stands up what those bindings
15
+ * point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
16
+ *
17
+ * The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
18
+ * Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
19
+ * per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
20
+ * CLI writes the complete entry here, once the host worker exists.
21
+ *
22
+ * The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
23
+ * orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
24
+ * records its call order, and no account. **Every step is idempotent**: find-then-create for the
25
+ * bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
26
+ *
27
+ * **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
28
+ * here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
29
+ * and written into the secret as given. That is a real limitation, and the manifest says so rather
30
+ * than promising a mint that does not happen.
31
+ */
32
+ /**
33
+ * The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
34
+ * `acme-prod-storage`.
35
+ *
36
+ * One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
37
+ * teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
38
+ * buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
39
+ * `@pithy-sh/email`'s deliberately project-shared suppression database.
40
+ *
41
+ * The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
42
+ * account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
43
+ * same account and silently adopted — two apps writing objects into one bucket, and either teardown
44
+ * deleting both. The name is the only partition R2 offers, so the name carries the owner.
45
+ *
46
+ * Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
47
+ * genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
48
+ * writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
49
+ * keeps it on purpose.
50
+ */
51
+ function storageBucketName(project, env) {
52
+ return resourceNames(project).env(env).r2(STORAGE_CAPABILITY);
53
+ }
54
+ /**
55
+ * The deployed sweep-worker name for a project's environment — also its resolved config's basename.
56
+ *
57
+ * A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
58
+ * cannot be renamed once a deploy or a `service` binding points at it.
59
+ */
60
+ function storageWorkerName(project, env) {
61
+ return resourceNames(project).env(env).worker(STORAGE_CAPABILITY);
62
+ }
63
+ /**
64
+ * Provision the storage infrastructure: check the account, create every environment's bucket, write
65
+ * every environment's credentials, then deploy every environment's sweep worker.
66
+ *
67
+ * The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
68
+ * must not boot before the secret it reads. Fanning each phase across all environments — rather than
69
+ * completing one environment end to end before starting the next — means a failure creating prod's
70
+ * bucket stops the run before staging's worker is deployed against a half-provisioned account.
71
+ *
72
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
73
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
74
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
75
+ */
76
+ async function provisionStorage(provisioner, environments) {
77
+ await provisioner.preflight();
78
+ const resources = /* @__PURE__ */ new Map();
79
+ for (const env of managedEnvironments(environments)) {
80
+ const { bucketName } = await provisioner.ensureBucket(env);
81
+ resources.set(env, { bucketName });
82
+ }
83
+ for (const env of managedEnvironments(environments)) await provisioner.writeCredentials(env, resourcesFor(resources, env));
84
+ for (const env of managedEnvironments(environments)) await provisioner.deployWorker(env, resourcesFor(resources, env));
85
+ return { environments: managedEnvironments(environments).map((env) => ({
86
+ env,
87
+ ...resourcesFor(resources, env)
88
+ })) };
89
+ }
90
+ /** Read back an environment's resources. Absent is impossible by construction, so the throw is a bug check. */
91
+ function resourcesFor(resources, env) {
92
+ const found = resources.get(env);
93
+ if (!found) throw new InternalError({ message: `No provisioned resources for the ${env} environment.` });
94
+ return found;
95
+ }
96
+ /**
97
+ * Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
98
+ * sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
99
+ * everything in them. Idempotent end to end.
100
+ *
101
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
102
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
103
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
104
+ */
105
+ async function deprovisionStorage(deprovisioner, environments, options = {}) {
106
+ for (const env of managedEnvironments(environments)) await deprovisioner.deleteWorker(env);
107
+ if (options.deleteStorage) for (const env of managedEnvironments(environments)) await deprovisioner.deleteBucket(env);
108
+ }
109
+ //#endregion
110
+ export { deprovisionStorage, provisionStorage, storageBucketName, storageWorkerName };
@@ -0,0 +1,43 @@
1
+ import { type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
2
+ import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
3
+ import type { StorageConfig } from "../config/config";
4
+ import type { StorageResources } from "./provisionStorage";
5
+ /**
6
+ * Resolve the sweep worker's committed `wrangler.jsonc` template into one environment's standalone
7
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the
8
+ * bindings' names — stays as the template committed it.
9
+ *
10
+ * Thin over core's {@link resolveWorkflowHost}, which owns the mechanics (clone, fill by binding name,
11
+ * stamp `ENVIRONMENT`). What this file adds is one thing the generic resolver deliberately does not
12
+ * do: it **rewrites `workflows` and `triggers.crons` from the capability's specs** rather than from
13
+ * the template's own block. The template carries both so it reads as a complete, deployable config,
14
+ * but `workflows/specs.ts` is the single source of the binding name, the class name, and the
15
+ * schedule — so changing the sweep's cron is a one-line spec edit, not a spec edit plus a JSONC edit
16
+ * that nothing checks agree.
17
+ *
18
+ * Pure: the caller parses the template and writes the result.
19
+ */
20
+ /** The resolved ids and per-env values for one environment's sweep-worker deploy. */
21
+ export interface StorageConfigParams {
22
+ /**
23
+ * The project name — the `<project>` segment the deployed worker and Workflow names lead with. The
24
+ * root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed: a Worker script
25
+ * name is account-scoped, so a wrong value here overwrites another project's running host.
26
+ */
27
+ project: string;
28
+ /** The target environment. */
29
+ env: ManagedEnvironment;
30
+ /** The app database id for this environment — where the `pithy_storage_*` tables live. */
31
+ appDatabaseId: string;
32
+ /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the R2 credentials. */
33
+ secretsDatabaseId: string;
34
+ /** The CF Secrets Store id holding the per-env master key. */
35
+ storeId: string;
36
+ /** The provisioned bucket the worker binds. */
37
+ resources: StorageResources;
38
+ /** The app's resolved storage config — serialized into the worker's `STORAGE_CONFIG` var. */
39
+ storageConfig: StorageConfig;
40
+ }
41
+ /** Fill the template for one environment. */
42
+ export declare function resolveStorageConfig(template: WorkflowHostTemplate, params: StorageConfigParams): WorkflowHostTemplate;
43
+ //# sourceMappingURL=resolveStorageConfig.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolveStorageConfig.d.ts","sourceRoot":"","sources":["../../src/provision/resolveStorageConfig.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyC,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAEpH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AAEH,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,GAAG,EAAE,kBAAkB,CAAC;IACxB,0FAA0F;IAC1F,aAAa,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,SAAS,EAAE,gBAAgB,CAAC;IAC5B,6FAA6F;IAC7F,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,oBAAoB,CA2BtB"}
@@ -0,0 +1,31 @@
1
+ import { STORAGE_CAPABILITY, storageWorkflowRegistry } from "../workflows/specs.js";
2
+ import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
3
+ import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
4
+ //#region src/provision/resolveStorageConfig.ts
5
+ /** Fill the template for one environment. */
6
+ function resolveStorageConfig(template, params) {
7
+ const { project, env, appDatabaseId, secretsDatabaseId, storeId, resources, storageConfig } = params;
8
+ const derived = hostWorkflowsFor(storageWorkflowRegistry, {
9
+ project,
10
+ capability: STORAGE_CAPABILITY,
11
+ env
12
+ });
13
+ const resolved = resolveWorkflowHost(template, {
14
+ project,
15
+ capability: STORAGE_CAPABILITY,
16
+ env,
17
+ databaseIds: {
18
+ DB: appDatabaseId,
19
+ SECRETS: secretsDatabaseId
20
+ },
21
+ r2BucketNames: { STORAGE_BUCKET: resources.bucketName },
22
+ secretsStoreId: storeId,
23
+ masterKeySecretName: masterKeySecretName(project, env),
24
+ vars: { STORAGE_CONFIG: JSON.stringify(storageConfig) },
25
+ workflows: derived.workflows
26
+ });
27
+ resolved.triggers = derived.crons.length > 0 ? { crons: derived.crons } : void 0;
28
+ return resolved;
29
+ }
30
+ //#endregion
31
+ export { resolveStorageConfig };
@@ -0,0 +1,125 @@
1
+ import type { StorageObjectRow, StorageObjectStatus } from "../data/storageObject";
2
+ import { type StorageDatabase } from "../data/tables";
3
+ /**
4
+ * Per-owner byte quotas.
5
+ *
6
+ * **Quota is checked when an upload *starts*, and the sum counts `pending` rows alongside `stored`
7
+ * ones.** That is the whole design, and it is not an optimization.
8
+ *
9
+ * Counting only completed uploads would make the check meaningless under concurrency: ten clients
10
+ * that each declare 1 GiB against a 1 GiB quota all read a used total of zero, all pass, and all
11
+ * upload. Nothing in that sequence is a bug in any single request — the check is simply measuring the
12
+ * wrong thing. Making the client declare its size up front, and having the `pending` row *reserve*
13
+ * those bytes the moment it is written, turns the quota into something a concurrent burst cannot
14
+ * walk past: the second init reads the first's reservation.
15
+ *
16
+ * **The reservation only holds if the sum and the insert are one statement.** A `SELECT sum(size)`
17
+ * followed by a separate `INSERT` reproduces the very race it was meant to close, one round trip
18
+ * later: ten concurrent inits all read a used total that none of them has yet contributed to, all
19
+ * pass, and all insert. D1 has no interactive transactions, so a `BEGIN`/`COMMIT` wrapper is not
20
+ * available — {@link insertReservingQuota} is the mechanism instead. It writes the pending row with a
21
+ * conditional `INSERT … SELECT … WHERE`, so the sum is evaluated *inside* the write, and a row that
22
+ * would breach the limit simply does not appear.
23
+ *
24
+ * {@link assertWithinQuota} survives as the cheap pre-check a handler runs before it creates anything
25
+ * that would need cleaning up. It is a courtesy, not the enforcement.
26
+ *
27
+ * **Completion settles the same way it reserved.** A part URL carries no signed `Content-Length`, so
28
+ * an owner may PUT more than they declared, and the overshoot has to be re-asserted when the row turns
29
+ * `stored`. That re-assertion is {@link updateSettlingQuota} — a conditional `UPDATE`, the same shape
30
+ * as the conditional `INSERT` — because two completions racing on a plain check both read a total
31
+ * neither has yet contributed and both pass. The rule is one rule: every write that changes what an
32
+ * owner holds evaluates the sum inside itself.
33
+ *
34
+ * The reservation is not free — an abandoned upload holds bytes it never stored. That is what
35
+ * `pendingTtlSeconds` and the orphan sweep are for: a `pending` row past its TTL is aborted and
36
+ * dropped, returning its reservation. Over-counting briefly and reclaiming is the right way round;
37
+ * under-counting has no recovery.
38
+ *
39
+ * A `null` limit is unlimited and skips the query entirely. A `null` owner (a system object) has no
40
+ * quota — there is no principal to bill it to.
41
+ */
42
+ /** What a quota check needs. */
43
+ export interface QuotaCheck {
44
+ /** The storage database. */
45
+ db: StorageDatabase;
46
+ /** The owner the bytes are billed to. Null is a system object, which no quota applies to. */
47
+ ownerId: string | null;
48
+ /** The configured per-owner ceiling in bytes. Null is unlimited. */
49
+ limitBytes: number | null;
50
+ /** The bytes this upload declares — what the pending row is about to reserve. */
51
+ additionalBytes: number;
52
+ }
53
+ /** A quota check plus the row whose insertion *is* the reservation. */
54
+ export interface QuotaReservation extends QuotaCheck {
55
+ /** The row to write, already through `StorageObject.encode` — the SQLite shape, never the app one. */
56
+ record: StorageObjectRow;
57
+ }
58
+ /** A quota check plus the row whose update *is* the settlement. */
59
+ export interface QuotaSettlement extends QuotaCheck {
60
+ /**
61
+ * The whole row to write, already through `StorageObject.encode`. Its `id` is what the update
62
+ * targets — the settlement rewrites one known row rather than a set.
63
+ */
64
+ record: StorageObjectRow;
65
+ }
66
+ /**
67
+ * The statuses that bill an owner: a `pending` row reserves its declared bytes and a `stored` one
68
+ * holds real ones. `failed` bills nothing.
69
+ *
70
+ * Exported because the orphan sweep asks the same question of the same rows — a key is *claimed* if
71
+ * and only if a row bills for it — and the two predicates drifting apart is what let a `failed` row
72
+ * shield its R2 object from collection while counting toward nobody's quota
73
+ * (`workflows/sweep.ts`).
74
+ */
75
+ export declare const QUOTA_COUNTED_STATUSES: readonly StorageObjectStatus[];
76
+ /**
77
+ * Bytes an owner currently holds: every `pending` reservation plus every `stored` object. `failed`
78
+ * rows are excluded — they hold no bytes and reserve nothing.
79
+ */
80
+ export declare function usedBytes(db: StorageDatabase, ownerId: string): Promise<number>;
81
+ /**
82
+ * Throw `storage/quota_exceeded` when this upload would put the owner over their limit. The
83
+ * comparison is `used + additional > limit`, so an upload landing exactly on the limit is allowed —
84
+ * a quota is a ceiling you may reach, not one you must stay under.
85
+ *
86
+ * **This is a pre-check, not the reservation.** It reads a total nothing holds still, so between it
87
+ * and any later write a concurrent init can have taken the room. Use it to refuse an obviously
88
+ * oversized upload *before* opening an R2 multipart upload there would then be nothing to clean up
89
+ * for, and let {@link insertReservingQuota} be the boundary that actually decides.
90
+ */
91
+ export declare function assertWithinQuota(check: QuotaCheck): Promise<void>;
92
+ /**
93
+ * Insert a storage row **only if** it fits inside the owner's quota, and throw
94
+ * `storage/quota_exceeded` when it does not.
95
+ *
96
+ * The sum and the write are one statement — `INSERT … SELECT <values> WHERE (SELECT sum(size) …) <=
97
+ * limit - additional` — because two statements cannot be made to hold a reservation without a
98
+ * transaction, and D1 has none to offer. SQLite evaluates the sub-select while it holds the write
99
+ * lock, so a burst of concurrent inits is serialized by the database itself: each one sees every
100
+ * reservation that landed before it, and the first that would breach the limit inserts nothing.
101
+ *
102
+ * `RETURNING id` is how "inserted nothing" is read back. Zero rows is not an error to SQLite — the
103
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
104
+ */
105
+ export declare function insertReservingQuota(reservation: QuotaReservation): Promise<void>;
106
+ /**
107
+ * Rewrite one row **only if** the bytes it newly claims still fit inside the owner's quota, and throw
108
+ * `storage/quota_exceeded` when they do not.
109
+ *
110
+ * This is {@link insertReservingQuota}'s other half, and it exists for the identical reason. A
111
+ * completion measures what R2 actually holds against what the pending row reserved, and the difference
112
+ * is bytes the owner has not been granted yet. Settling that difference with a separate
113
+ * {@link assertWithinQuota} would put the enforcement back where it never worked: two completions
114
+ * racing both read a total neither has yet contributed to, both pass, and the owner ends over the
115
+ * limit — the same defect the conditional insert was written to close, one lifecycle stage later.
116
+ *
117
+ * `additionalBytes` is the **overshoot**, not the object's size. The row being updated is still
118
+ * `pending`, so the sub-select in the `WHERE` already counts its reservation: SQLite evaluates the
119
+ * condition against the pre-update table. Passing the full size would bill the reservation twice.
120
+ *
121
+ * `RETURNING id` reads back whether the row moved. Zero rows updated is not an error to SQLite — the
122
+ * `WHERE` simply matched nothing — so the absence of a returned row *is* the quota answer.
123
+ */
124
+ export declare function updateSettlingQuota(settlement: QuotaSettlement): Promise<void>;
125
+ //# sourceMappingURL=quota.d.ts.map