@pithy-sh/storage 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/capability.d.ts +45 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +76 -0
- package/dist/config/config.d.ts +27 -0
- package/dist/config/config.d.ts.map +1 -0
- package/dist/config/config.js +49 -0
- package/dist/data/share.d.ts +27 -0
- package/dist/data/share.d.ts.map +1 -0
- package/dist/data/share.js +28 -0
- package/dist/data/storageObject.d.ts +55 -0
- package/dist/data/storageObject.d.ts.map +1 -0
- package/dist/data/storageObject.js +44 -0
- package/dist/data/tables.d.ts +23 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +26 -0
- package/dist/error/errors.d.ts +60 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +89 -0
- package/dist/http/guard.d.ts +20 -0
- package/dist/http/guard.d.ts.map +1 -0
- package/dist/http/guard.js +29 -0
- package/dist/http/handlers.d.ts +232 -0
- package/dist/http/handlers.d.ts.map +1 -0
- package/dist/http/handlers.js +507 -0
- package/dist/http/routes.d.ts +70 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +135 -0
- package/dist/http/schemas.d.ts +74 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +93 -0
- package/dist/http/serve.d.ts +121 -0
- package/dist/http/serve.d.ts.map +1 -0
- package/dist/http/serve.js +209 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +14 -0
- package/dist/migrations/0001_objects.d.ts +24 -0
- package/dist/migrations/0001_objects.d.ts.map +1 -0
- package/dist/migrations/0001_objects.js +41 -0
- package/dist/object/cloudflare.d.ts +23 -0
- package/dist/object/cloudflare.d.ts.map +1 -0
- package/dist/object/cloudflare.js +48 -0
- package/dist/object/key.d.ts +29 -0
- package/dist/object/key.d.ts.map +1 -0
- package/dist/object/key.js +37 -0
- package/dist/object/multipart.d.ts +78 -0
- package/dist/object/multipart.d.ts.map +1 -0
- package/dist/object/multipart.js +131 -0
- package/dist/object/store.d.ts +203 -0
- package/dist/object/store.d.ts.map +1 -0
- package/dist/object/store.js +178 -0
- package/dist/provision/provisionStorage.d.ts +139 -0
- package/dist/provision/provisionStorage.d.ts.map +1 -0
- package/dist/provision/provisionStorage.js +112 -0
- package/dist/provision/resolveStorageConfig.d.ts +45 -0
- package/dist/provision/resolveStorageConfig.d.ts.map +1 -0
- package/dist/provision/resolveStorageConfig.js +33 -0
- package/dist/quota/quota.d.ts +127 -0
- package/dist/quota/quota.d.ts.map +1 -0
- package/dist/quota/quota.js +102 -0
- package/dist/secret/registry.d.ts +72 -0
- package/dist/secret/registry.d.ts.map +1 -0
- package/dist/secret/registry.js +84 -0
- package/dist/seeds/example.d.ts +5 -0
- package/dist/seeds/example.d.ts.map +1 -0
- package/dist/seeds/example.js +111 -0
- package/dist/test-utils/liveStorage.d.ts +52 -0
- package/dist/test-utils/liveStorage.d.ts.map +1 -0
- package/dist/test-utils/liveStorage.js +198 -0
- package/dist/version.generated.d.ts +7 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +9 -0
- package/dist/workflows/retryPolicy.d.ts +39 -0
- package/dist/workflows/retryPolicy.d.ts.map +1 -0
- package/dist/workflows/retryPolicy.js +43 -0
- package/dist/workflows/specs.d.ts +57 -0
- package/dist/workflows/specs.d.ts.map +1 -0
- package/dist/workflows/specs.js +60 -0
- package/dist/workflows/sweep.d.ts +84 -0
- package/dist/workflows/sweep.d.ts.map +1 -0
- package/dist/workflows/sweep.js +145 -0
- package/dist/workflows/worker.d.ts +51 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +52 -0
- package/package.json +22 -11
- package/src/version.generated.ts +1 -1
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { R2Bucket, ReadableStream } from "@cloudflare/workers-types";
|
|
4
|
+
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
import { type R2StorageCredentials } from "../secret/registry";
|
|
7
|
+
import type { ReportedPart } from "./multipart";
|
|
8
|
+
/**
|
|
9
|
+
* `ObjectStore` — the object-plane seam, and the one piece of this package that is reusable outside it.
|
|
10
|
+
*
|
|
11
|
+
* **The load-bearing constraint: this module imports no D1, no routes, and no storage config.** It is
|
|
12
|
+
* constructed over an injected bucket binding and a *named* credential secret, which is exactly what
|
|
13
|
+
* lets `@pithy-sh/media` import it, point it at `MEDIA_BUCKET` under `media-r2-credentials`, and
|
|
14
|
+
* inherit none of storage's tables, routes, or opaque-key policy. Adding `@pithy-sh/storage` to media
|
|
15
|
+
* must not mount storage's routes or create `pithy_storage_objects`; keeping this file free of those
|
|
16
|
+
* imports is what guarantees it.
|
|
17
|
+
*
|
|
18
|
+
* It is **mechanism only**. It takes an explicit key and moves bytes. Key policy lives in `key.ts` and
|
|
19
|
+
* in the handlers: storage derives `obj/<uuid>`, media passes `media/<type>/<id>`, and neither knows
|
|
20
|
+
* the other's scheme.
|
|
21
|
+
*
|
|
22
|
+
* **Bindings inside the Worker, S3 outside it** (CLAUDE.md §Cloudflare access). Reads, head, list and
|
|
23
|
+
* delete go through the `R2Bucket` binding — no credentials, no round trip, and a body that streams.
|
|
24
|
+
* Presigned URLs, the multipart lifecycle, and server-side copy have no binding equivalent that keeps
|
|
25
|
+
* bytes out of the Worker, so they go over the S3 protocol through `@pithy-sh/cloudflare`. The seam
|
|
26
|
+
* hides which is which; only `object/cloudflare.ts` touches the manager.
|
|
27
|
+
*
|
|
28
|
+
* Every response crossing the seam is Zod-validated, so an unexpected shape fails loudly at the
|
|
29
|
+
* boundary rather than surfacing as `undefined` three layers up.
|
|
30
|
+
*/
|
|
31
|
+
/** An object's metadata, as either a HEAD or a GET reports it. */
|
|
32
|
+
export declare const ObjectMetadata: z.ZodObject<{
|
|
33
|
+
key: z.ZodString;
|
|
34
|
+
size: z.ZodNumber;
|
|
35
|
+
etag: z.ZodString;
|
|
36
|
+
contentType: z.ZodOptional<z.ZodString>;
|
|
37
|
+
contentDisposition: z.ZodOptional<z.ZodString>;
|
|
38
|
+
uploaded: z.ZodDate;
|
|
39
|
+
checksumSha256: z.ZodOptional<z.ZodString>;
|
|
40
|
+
}, z.core.$strip>;
|
|
41
|
+
export type ObjectMetadata = z.output<typeof ObjectMetadata>;
|
|
42
|
+
/** Which bytes of an object to read. Mirrors R2's own range shapes; exactly one form is meaningful. */
|
|
43
|
+
export declare const ObjectRange: z.ZodObject<{
|
|
44
|
+
offset: z.ZodOptional<z.ZodNumber>;
|
|
45
|
+
length: z.ZodOptional<z.ZodNumber>;
|
|
46
|
+
suffix: z.ZodOptional<z.ZodNumber>;
|
|
47
|
+
}, z.core.$strip>;
|
|
48
|
+
export type ObjectRange = z.output<typeof ObjectRange>;
|
|
49
|
+
/** Preconditions a read must satisfy, so a conditional request can answer 304 without moving bytes. */
|
|
50
|
+
export declare const ObjectConditions: z.ZodObject<{
|
|
51
|
+
etagMatches: z.ZodOptional<z.ZodString>;
|
|
52
|
+
etagDoesNotMatch: z.ZodOptional<z.ZodString>;
|
|
53
|
+
uploadedBefore: z.ZodOptional<z.ZodDate>;
|
|
54
|
+
uploadedAfter: z.ZodOptional<z.ZodDate>;
|
|
55
|
+
}, z.core.$strip>;
|
|
56
|
+
export type ObjectConditions = z.output<typeof ObjectConditions>;
|
|
57
|
+
/** One page of a bucket listing — the sweep's view, distinct from the D1 listing an owner sees. */
|
|
58
|
+
export declare const ObjectListing: z.ZodObject<{
|
|
59
|
+
objects: z.ZodArray<z.ZodObject<{
|
|
60
|
+
key: z.ZodString;
|
|
61
|
+
size: z.ZodNumber;
|
|
62
|
+
etag: z.ZodString;
|
|
63
|
+
contentType: z.ZodOptional<z.ZodString>;
|
|
64
|
+
contentDisposition: z.ZodOptional<z.ZodString>;
|
|
65
|
+
uploaded: z.ZodDate;
|
|
66
|
+
checksumSha256: z.ZodOptional<z.ZodString>;
|
|
67
|
+
}, z.core.$strip>>;
|
|
68
|
+
cursor: z.ZodOptional<z.ZodString>;
|
|
69
|
+
}, z.core.$strip>;
|
|
70
|
+
export type ObjectListing = z.output<typeof ObjectListing>;
|
|
71
|
+
/** One part already stored against an in-flight multipart upload — what makes an upload resumable. */
|
|
72
|
+
export declare const UploadedPart: z.ZodObject<{
|
|
73
|
+
partNumber: z.ZodNumber;
|
|
74
|
+
etag: z.ZodString;
|
|
75
|
+
size: z.ZodNumber;
|
|
76
|
+
}, z.core.$strip>;
|
|
77
|
+
export type UploadedPart = z.output<typeof UploadedPart>;
|
|
78
|
+
/** How long a presigned URL stays valid. */
|
|
79
|
+
export interface PresignOptions {
|
|
80
|
+
/** Lifetime in seconds. Defaults to one hour — long enough for a large part, short enough to leak little. */
|
|
81
|
+
expiresIn?: number;
|
|
82
|
+
}
|
|
83
|
+
/** Presign options for one part, which may additionally pin its exact byte count. */
|
|
84
|
+
export interface PresignPartOptions extends PresignOptions {
|
|
85
|
+
/** Exact byte count the client must send. Omitted by default; see `presignPart`. */
|
|
86
|
+
contentLength?: number;
|
|
87
|
+
}
|
|
88
|
+
/** What to read, and under what preconditions. */
|
|
89
|
+
export interface GetOptions {
|
|
90
|
+
/** Serve only this byte range (206). */
|
|
91
|
+
range?: ObjectRange;
|
|
92
|
+
/** Serve only if these preconditions hold; otherwise the result carries metadata and no body (304). */
|
|
93
|
+
onlyIf?: ObjectConditions;
|
|
94
|
+
}
|
|
95
|
+
/** Which slice of the bucket to list. */
|
|
96
|
+
export interface ListOptions {
|
|
97
|
+
/** Only keys starting with this prefix. Omitted lists the whole bucket. */
|
|
98
|
+
prefix?: string;
|
|
99
|
+
/** Continuation cursor from a previous page. */
|
|
100
|
+
cursor?: string;
|
|
101
|
+
/** Page size. R2 caps this at 1,000. */
|
|
102
|
+
limit?: number;
|
|
103
|
+
}
|
|
104
|
+
/** An object read: its metadata, its bytes, and the range R2 actually served. */
|
|
105
|
+
export interface ObjectBody {
|
|
106
|
+
/** The whole object's metadata — `size` is the object's, not the range's. */
|
|
107
|
+
metadata: ObjectMetadata;
|
|
108
|
+
/** The bytes, streamed. `null` when a precondition failed, which is the 304 signal. */
|
|
109
|
+
body: ReadableStream | null;
|
|
110
|
+
/** The byte range R2 served, when a range was asked for. `null` means the whole object. */
|
|
111
|
+
range: {
|
|
112
|
+
offset: number;
|
|
113
|
+
length: number;
|
|
114
|
+
} | null;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* The S3-protocol half of the seam: everything the R2 binding cannot do without pulling bytes through
|
|
118
|
+
* the Worker. Declared here as a structural port so `store.ts` never imports `@pithy-sh/cloudflare`,
|
|
119
|
+
* and so a test can drive the store with no SDK and no network.
|
|
120
|
+
*/
|
|
121
|
+
export interface PresignedObjects {
|
|
122
|
+
/**
|
|
123
|
+
* Presign a PUT for one whole object. The length is signed, so the client must send exactly that many
|
|
124
|
+
* bytes. The type is **not** — S3 presigning marks `content-type` unsignable — so it is a hint the
|
|
125
|
+
* completion reconciles against what R2 actually stored.
|
|
126
|
+
*/
|
|
127
|
+
presignPut(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
|
|
128
|
+
/** Presign a GET for one object. */
|
|
129
|
+
presignGet(key: string, options?: PresignOptions): Promise<string>;
|
|
130
|
+
/** Open a multipart upload; returns the `uploadId` every later step is addressed by. */
|
|
131
|
+
createMultipartUpload(key: string, contentType: string): Promise<string>;
|
|
132
|
+
/** Presign a PUT for one part — the only multipart step a client ever touches. */
|
|
133
|
+
presignUploadPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
|
|
134
|
+
/** Assemble the uploaded parts into one object. */
|
|
135
|
+
completeMultipartUpload(key: string, uploadId: string, parts: readonly ReportedPart[]): Promise<void>;
|
|
136
|
+
/** Discard an in-flight upload and its stored parts. Idempotent. */
|
|
137
|
+
abortMultipartUpload(key: string, uploadId: string): Promise<void>;
|
|
138
|
+
/** List the parts already stored against an in-flight upload, ascending. */
|
|
139
|
+
listParts(key: string, uploadId: string): Promise<UploadedPart[]>;
|
|
140
|
+
/** Copy an object within the bucket, server-side — the bytes never leave R2. */
|
|
141
|
+
copyObject(sourceKey: string, destinationKey: string): Promise<void>;
|
|
142
|
+
}
|
|
143
|
+
/** The object plane: presigned transfer, the multipart lifecycle, and binding-backed reads. */
|
|
144
|
+
export interface ObjectStore {
|
|
145
|
+
/** Presign a PUT the client uploads a whole object to. Bytes never proxy through the Worker. */
|
|
146
|
+
presignPut(key: string, contentType: string, contentLength: number, options?: PresignOptions): Promise<string>;
|
|
147
|
+
/** Presign a GET — the escape hatch for serving without a Worker in the byte path. */
|
|
148
|
+
presignGet(key: string, options?: PresignOptions): Promise<string>;
|
|
149
|
+
/** Open a multipart upload. Persist the returned `uploadId`: it is the handle a resume needs. */
|
|
150
|
+
initMultipart(key: string, contentType: string): Promise<string>;
|
|
151
|
+
/**
|
|
152
|
+
* Presign a PUT for one part. `contentLength` is **not** signed by default: the final part's length
|
|
153
|
+
* differs from every other, so signing it would mean knowing the total size at mint time. R2 enforces
|
|
154
|
+
* the 5 MiB floor and 5 GiB ceiling itself, and the object's real size is confirmed at completion.
|
|
155
|
+
*/
|
|
156
|
+
presignPart(key: string, uploadId: string, partNumber: number, options?: PresignPartOptions): Promise<string>;
|
|
157
|
+
/** Assemble the reported parts into one object. Order and completeness are checked before R2 sees them. */
|
|
158
|
+
completeMultipart(key: string, uploadId: string, parts: readonly ReportedPart[]): Promise<void>;
|
|
159
|
+
/** Abort an in-flight upload. Idempotent, so a sweep or a retried teardown can re-run. */
|
|
160
|
+
abortMultipart(key: string, uploadId: string): Promise<void>;
|
|
161
|
+
/** The parts already stored against an in-flight upload — what a resuming client asks for. */
|
|
162
|
+
listParts(key: string, uploadId: string): Promise<UploadedPart[]>;
|
|
163
|
+
/** Read an object through the binding, honoring a range and conditional preconditions. `null` when absent. */
|
|
164
|
+
get(key: string, options?: GetOptions): Promise<ObjectBody | null>;
|
|
165
|
+
/** Read an object's metadata without its body. `null` when absent — a missing object is an answer. */
|
|
166
|
+
head(key: string): Promise<ObjectMetadata | null>;
|
|
167
|
+
/** One page of bucket keys. The orphan sweep's view; an owner's file list comes from D1. */
|
|
168
|
+
list(options?: ListOptions): Promise<ObjectListing>;
|
|
169
|
+
/** Server-side copy within the bucket. */
|
|
170
|
+
copy(sourceKey: string, destinationKey: string): Promise<void>;
|
|
171
|
+
/** Delete one object. Idempotent by protocol. */
|
|
172
|
+
delete(key: string): Promise<void>;
|
|
173
|
+
}
|
|
174
|
+
/** How to build an object store. */
|
|
175
|
+
export interface ObjectStoreOptions {
|
|
176
|
+
/** The R2 bucket binding — `STORAGE_BUCKET` for storage, `MEDIA_BUCKET` for media. */
|
|
177
|
+
bucket: R2Bucket;
|
|
178
|
+
/**
|
|
179
|
+
* The env the credential secret resolves against. Only ever handed to `sharedSecretsStore`; no
|
|
180
|
+
* binding on it is read directly (CLAUDE.md §Secrets).
|
|
181
|
+
*/
|
|
182
|
+
env: SecretsStoreEnv;
|
|
183
|
+
/**
|
|
184
|
+
* The registry name the R2 credential bundle is stored under. Whatever name is passed, the *same*
|
|
185
|
+
* capability must have declared it with `r2CredentialsRegistry(name)` — a name no capability
|
|
186
|
+
* declared is absent from the aggregated registry and throws on first use.
|
|
187
|
+
*/
|
|
188
|
+
secretName?: string;
|
|
189
|
+
/**
|
|
190
|
+
* Test seam: build the S3 port from resolved credentials. Defaults to the real R2 adapter. Overriding
|
|
191
|
+
* it is how a test drives the store with no SDK, no credentials, and no network.
|
|
192
|
+
*/
|
|
193
|
+
presigned?: (credentials: R2StorageCredentials) => PresignedObjects;
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* Build an object store over a bucket binding and a named credential secret.
|
|
197
|
+
*
|
|
198
|
+
* Credentials resolve **lazily, once**: a read-only worker that never presigns never touches the
|
|
199
|
+
* secrets store, and a worker that presigns twice resolves once. The promise itself is memoized, so
|
|
200
|
+
* two concurrent presigns share one resolution rather than racing two.
|
|
201
|
+
*/
|
|
202
|
+
export declare function objectStore(options: ObjectStoreOptions): ObjectStore;
|
|
203
|
+
//# sourceMappingURL=store.d.ts.map
|
|
@@ -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,178 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { r2CredentialsRegistry } from "../secret/registry.js";
|
|
4
|
+
import { r2Presigned } from "./cloudflare.js";
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
7
|
+
//#region src/object/store.ts
|
|
8
|
+
/**
|
|
9
|
+
* `ObjectStore` — the object-plane seam, and the one piece of this package that is reusable outside it.
|
|
10
|
+
*
|
|
11
|
+
* **The load-bearing constraint: this module imports no D1, no routes, and no storage config.** It is
|
|
12
|
+
* constructed over an injected bucket binding and a *named* credential secret, which is exactly what
|
|
13
|
+
* lets `@pithy-sh/media` import it, point it at `MEDIA_BUCKET` under `media-r2-credentials`, and
|
|
14
|
+
* inherit none of storage's tables, routes, or opaque-key policy. Adding `@pithy-sh/storage` to media
|
|
15
|
+
* must not mount storage's routes or create `pithy_storage_objects`; keeping this file free of those
|
|
16
|
+
* imports is what guarantees it.
|
|
17
|
+
*
|
|
18
|
+
* It is **mechanism only**. It takes an explicit key and moves bytes. Key policy lives in `key.ts` and
|
|
19
|
+
* in the handlers: storage derives `obj/<uuid>`, media passes `media/<type>/<id>`, and neither knows
|
|
20
|
+
* the other's scheme.
|
|
21
|
+
*
|
|
22
|
+
* **Bindings inside the Worker, S3 outside it** (CLAUDE.md §Cloudflare access). Reads, head, list and
|
|
23
|
+
* delete go through the `R2Bucket` binding — no credentials, no round trip, and a body that streams.
|
|
24
|
+
* Presigned URLs, the multipart lifecycle, and server-side copy have no binding equivalent that keeps
|
|
25
|
+
* bytes out of the Worker, so they go over the S3 protocol through `@pithy-sh/cloudflare`. The seam
|
|
26
|
+
* hides which is which; only `object/cloudflare.ts` touches the manager.
|
|
27
|
+
*
|
|
28
|
+
* Every response crossing the seam is Zod-validated, so an unexpected shape fails loudly at the
|
|
29
|
+
* boundary rather than surfacing as `undefined` three layers up.
|
|
30
|
+
*/
|
|
31
|
+
/** An object's metadata, as either a HEAD or a GET reports it. */
|
|
32
|
+
const ObjectMetadata = z.object({
|
|
33
|
+
key: z.string().min(1).describe("The R2 object key. Opaque to the caller — policy lives in `key.ts`."),
|
|
34
|
+
size: z.number().int().nonnegative().describe("The whole object's size in bytes, not the served range's."),
|
|
35
|
+
etag: z.string().min(1).describe("R2's entity tag for this object version, unquoted. Quote it before it becomes an `ETag` header."),
|
|
36
|
+
contentType: z.string().min(1).optional().describe("The stored `Content-Type`. Absent when the object was written without one."),
|
|
37
|
+
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."),
|
|
38
|
+
uploaded: z.date().describe("When R2 wrote this object version."),
|
|
39
|
+
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.")
|
|
40
|
+
}).describe("One object's metadata — everything a serve path needs without transferring the body.");
|
|
41
|
+
/** Which bytes of an object to read. Mirrors R2's own range shapes; exactly one form is meaningful. */
|
|
42
|
+
const ObjectRange = z.object({
|
|
43
|
+
offset: z.number().int().nonnegative().optional().describe("First byte to read, from the start of the object."),
|
|
44
|
+
length: z.number().int().positive().optional().describe("How many bytes to read from `offset`."),
|
|
45
|
+
suffix: z.number().int().positive().optional().describe("Read this many bytes from the *end* — `bytes=-N`.")
|
|
46
|
+
}).describe("A byte range to read, as an HTTP `Range` header maps onto R2.");
|
|
47
|
+
/** Preconditions a read must satisfy, so a conditional request can answer 304 without moving bytes. */
|
|
48
|
+
const ObjectConditions = z.object({
|
|
49
|
+
etagMatches: z.string().min(1).optional().describe("Read only if the object's etag equals this (`If-Match`)."),
|
|
50
|
+
etagDoesNotMatch: z.string().min(1).optional().describe("Read only if the object's etag differs (`If-None-Match`) — the 304 path."),
|
|
51
|
+
uploadedBefore: z.date().optional().describe("Read only if the object was written before this (`If-Unmodified-Since`)."),
|
|
52
|
+
uploadedAfter: z.date().optional().describe("Read only if the object was written after this (`If-Modified-Since`).")
|
|
53
|
+
}).describe("Conditional-read preconditions. R2 returns metadata with no body when one fails.");
|
|
54
|
+
/** One page of a bucket listing — the sweep's view, distinct from the D1 listing an owner sees. */
|
|
55
|
+
const ObjectListing = z.object({
|
|
56
|
+
objects: z.array(ObjectMetadata).describe("This page's objects, in R2's lexicographic key order."),
|
|
57
|
+
cursor: z.string().min(1).optional().describe("Continuation cursor for the next page. Absent means this page was the last.")
|
|
58
|
+
}).describe("One page of a bucket listing. Pagination is caller-driven — pass `cursor` back to advance.");
|
|
59
|
+
/** One part already stored against an in-flight multipart upload — what makes an upload resumable. */
|
|
60
|
+
const UploadedPart = z.object({
|
|
61
|
+
partNumber: z.number().int().min(1).describe("The part's 1-based index within the upload."),
|
|
62
|
+
etag: z.string().min(1).describe("The part's entity tag, verbatim. Pass it back unchanged to complete."),
|
|
63
|
+
size: z.number().int().nonnegative().describe("The part's size in bytes, as R2 stored it.")
|
|
64
|
+
}).describe("One uploaded part — the unit a resumed upload skips re-sending.");
|
|
65
|
+
/** Map our range shape onto R2's — the binding's union admits exactly one of these three forms. */
|
|
66
|
+
function toR2Range(range) {
|
|
67
|
+
if (!range) return void 0;
|
|
68
|
+
if (range.suffix !== void 0) return { suffix: range.suffix };
|
|
69
|
+
if (range.offset !== void 0 && range.length !== void 0) return {
|
|
70
|
+
offset: range.offset,
|
|
71
|
+
length: range.length
|
|
72
|
+
};
|
|
73
|
+
if (range.offset !== void 0) return { offset: range.offset };
|
|
74
|
+
if (range.length !== void 0) return { length: range.length };
|
|
75
|
+
}
|
|
76
|
+
/** Lowercase hex for a checksum R2 hands back as raw bytes. */
|
|
77
|
+
function toHex(buffer) {
|
|
78
|
+
return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
79
|
+
}
|
|
80
|
+
/** Validate an `R2Object` into {@link ObjectMetadata} — the one place binding shapes cross the seam. */
|
|
81
|
+
function toMetadata(object) {
|
|
82
|
+
return ObjectMetadata.parse({
|
|
83
|
+
key: object.key,
|
|
84
|
+
size: object.size,
|
|
85
|
+
etag: object.etag,
|
|
86
|
+
contentType: object.httpMetadata?.contentType,
|
|
87
|
+
contentDisposition: object.httpMetadata?.contentDisposition,
|
|
88
|
+
uploaded: object.uploaded,
|
|
89
|
+
checksumSha256: object.checksums?.sha256 ? toHex(object.checksums.sha256) : void 0
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Build an object store over a bucket binding and a named credential secret.
|
|
94
|
+
*
|
|
95
|
+
* Credentials resolve **lazily, once**: a read-only worker that never presigns never touches the
|
|
96
|
+
* secrets store, and a worker that presigns twice resolves once. The promise itself is memoized, so
|
|
97
|
+
* two concurrent presigns share one resolution rather than racing two.
|
|
98
|
+
*/
|
|
99
|
+
function objectStore(options) {
|
|
100
|
+
const secretName = options.secretName ?? "storage-r2-credentials";
|
|
101
|
+
const build = options.presigned ?? r2Presigned;
|
|
102
|
+
const bucket = options.bucket;
|
|
103
|
+
let presignedPromise = null;
|
|
104
|
+
function presigned() {
|
|
105
|
+
if (!presignedPromise) presignedPromise = (async () => {
|
|
106
|
+
const registry = r2CredentialsRegistry(secretName);
|
|
107
|
+
const store = await sharedSecretsStore(options.env, registry);
|
|
108
|
+
return build(store.get(secretName));
|
|
109
|
+
})();
|
|
110
|
+
return presignedPromise;
|
|
111
|
+
}
|
|
112
|
+
return {
|
|
113
|
+
async presignPut(key, contentType, contentLength, presignOptions) {
|
|
114
|
+
return (await presigned()).presignPut(key, contentType, contentLength, presignOptions);
|
|
115
|
+
},
|
|
116
|
+
async presignGet(key, presignOptions) {
|
|
117
|
+
return (await presigned()).presignGet(key, presignOptions);
|
|
118
|
+
},
|
|
119
|
+
async initMultipart(key, contentType) {
|
|
120
|
+
return (await presigned()).createMultipartUpload(key, contentType);
|
|
121
|
+
},
|
|
122
|
+
async presignPart(key, uploadId, partNumber, presignOptions) {
|
|
123
|
+
return (await presigned()).presignUploadPart(key, uploadId, partNumber, presignOptions);
|
|
124
|
+
},
|
|
125
|
+
async completeMultipart(key, uploadId, parts) {
|
|
126
|
+
await (await presigned()).completeMultipartUpload(key, uploadId, parts);
|
|
127
|
+
},
|
|
128
|
+
async abortMultipart(key, uploadId) {
|
|
129
|
+
await (await presigned()).abortMultipartUpload(key, uploadId);
|
|
130
|
+
},
|
|
131
|
+
async listParts(key, uploadId) {
|
|
132
|
+
return (await presigned()).listParts(key, uploadId);
|
|
133
|
+
},
|
|
134
|
+
async get(key, getOptions) {
|
|
135
|
+
const conditions = getOptions?.onlyIf;
|
|
136
|
+
const object = await bucket.get(key, {
|
|
137
|
+
range: toR2Range(getOptions?.range),
|
|
138
|
+
onlyIf: conditions ? conditions : void 0
|
|
139
|
+
});
|
|
140
|
+
if (!object) return null;
|
|
141
|
+
const body = "body" in object ? object.body : null;
|
|
142
|
+
const served = getOptions?.range && object.range ? object.range : void 0;
|
|
143
|
+
const offset = served && "offset" in served ? served.offset ?? 0 : 0;
|
|
144
|
+
const length = served && "length" in served ? served.length ?? 0 : 0;
|
|
145
|
+
return {
|
|
146
|
+
metadata: toMetadata(object),
|
|
147
|
+
body,
|
|
148
|
+
range: served ? {
|
|
149
|
+
offset,
|
|
150
|
+
length
|
|
151
|
+
} : null
|
|
152
|
+
};
|
|
153
|
+
},
|
|
154
|
+
async head(key) {
|
|
155
|
+
const object = await bucket.head(key);
|
|
156
|
+
return object ? toMetadata(object) : null;
|
|
157
|
+
},
|
|
158
|
+
async list(listOptions) {
|
|
159
|
+
const page = await bucket.list({
|
|
160
|
+
prefix: listOptions?.prefix,
|
|
161
|
+
cursor: listOptions?.cursor,
|
|
162
|
+
limit: listOptions?.limit
|
|
163
|
+
});
|
|
164
|
+
return ObjectListing.parse({
|
|
165
|
+
objects: page.objects.map(toMetadata),
|
|
166
|
+
cursor: page.truncated ? page.cursor : void 0
|
|
167
|
+
});
|
|
168
|
+
},
|
|
169
|
+
async copy(sourceKey, destinationKey) {
|
|
170
|
+
await (await presigned()).copyObject(sourceKey, destinationKey);
|
|
171
|
+
},
|
|
172
|
+
async delete(key) {
|
|
173
|
+
await bucket.delete(key);
|
|
174
|
+
}
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
//#endregion
|
|
178
|
+
export { ObjectConditions, ObjectListing, ObjectMetadata, ObjectRange, UploadedPart, objectStore };
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
|
|
4
|
+
import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
|
|
5
|
+
/**
|
|
6
|
+
* The provisioning orchestration for the storage capability — the live counterpart to
|
|
7
|
+
* `pithy add storage`'s config wiring.
|
|
8
|
+
*
|
|
9
|
+
* The split is deliberate and worth stating, because the two commands look like one. `pithy add`
|
|
10
|
+
* writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
|
|
11
|
+
* `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
|
|
12
|
+
* nothing — an `add` that reached out to an account would make adding a capability an operation you
|
|
13
|
+
* could not do offline, or in CI, or without credentials. This command stands up what those bindings
|
|
14
|
+
* point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
|
|
15
|
+
*
|
|
16
|
+
* The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
|
|
17
|
+
* Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
|
|
18
|
+
* per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
|
|
19
|
+
* CLI writes the complete entry here, once the host worker exists.
|
|
20
|
+
*
|
|
21
|
+
* The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
|
|
22
|
+
* orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
|
|
23
|
+
* records its call order, and no account. **Every step is idempotent**: find-then-create for the
|
|
24
|
+
* bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
|
|
25
|
+
*
|
|
26
|
+
* **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
|
|
27
|
+
* here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
|
|
28
|
+
* and written into the secret as given. That is a real limitation, and the manifest says so rather
|
|
29
|
+
* than promising a mint that does not happen.
|
|
30
|
+
*/
|
|
31
|
+
/**
|
|
32
|
+
* The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
|
|
33
|
+
* `acme-prod-storage`.
|
|
34
|
+
*
|
|
35
|
+
* One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
|
|
36
|
+
* teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
|
|
37
|
+
* buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
|
|
38
|
+
* `@pithy-sh/email`'s deliberately project-shared suppression database.
|
|
39
|
+
*
|
|
40
|
+
* The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
|
|
41
|
+
* account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
|
|
42
|
+
* same account and silently adopted — two apps writing objects into one bucket, and either teardown
|
|
43
|
+
* deleting both. The name is the only partition R2 offers, so the name carries the owner.
|
|
44
|
+
*
|
|
45
|
+
* Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
|
|
46
|
+
* genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
|
|
47
|
+
* writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
|
|
48
|
+
* keeps it on purpose.
|
|
49
|
+
*/
|
|
50
|
+
export declare function storageBucketName(project: string, env: ManagedEnvironment): string;
|
|
51
|
+
/**
|
|
52
|
+
* The deployed sweep-worker name for a project's environment — also its resolved config's basename.
|
|
53
|
+
*
|
|
54
|
+
* A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
|
|
55
|
+
* cannot be renamed once a deploy or a `service` binding points at it.
|
|
56
|
+
*/
|
|
57
|
+
export declare function storageWorkerName(project: string, env: ManagedEnvironment): string;
|
|
58
|
+
/** The provisioned resources an environment's worker and secret are wired to. */
|
|
59
|
+
export interface StorageResources {
|
|
60
|
+
/** The R2 bucket objects live in. */
|
|
61
|
+
bucketName: string;
|
|
62
|
+
}
|
|
63
|
+
/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
|
|
64
|
+
export interface StorageProvisioner {
|
|
65
|
+
/**
|
|
66
|
+
* Verify account prerequisites before any resource is created — most importantly a registered
|
|
67
|
+
* `workers.dev` subdomain, which Cloudflare requires to deploy a Workflow-hosting worker. Failing
|
|
68
|
+
* here means failing before a bucket exists, rather than half way through a fan-out.
|
|
69
|
+
*/
|
|
70
|
+
preflight(): Promise<void>;
|
|
71
|
+
/** Create (or reuse) this environment's R2 bucket; returns its name. Idempotent. */
|
|
72
|
+
ensureBucket(env: ManagedEnvironment): Promise<{
|
|
73
|
+
bucketName: string;
|
|
74
|
+
}>;
|
|
75
|
+
/**
|
|
76
|
+
* Write this environment's `storage-r2-credentials` secret — the account id, S3 key pair, scoped
|
|
77
|
+
* token, and bucket name the object store presigns with. Idempotent (create, else update). Runs
|
|
78
|
+
* before the worker is deployed: a worker that boots without its credentials fails on its first
|
|
79
|
+
* multipart abort.
|
|
80
|
+
*/
|
|
81
|
+
writeCredentials(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
|
|
82
|
+
/** Deploy the prebuilt sweep worker for this environment, wired to the provisioned bucket. */
|
|
83
|
+
deployWorker(env: ManagedEnvironment, resources: StorageResources): Promise<void>;
|
|
84
|
+
}
|
|
85
|
+
/** What provisioning produced, per environment. */
|
|
86
|
+
export interface StorageProvisionResult {
|
|
87
|
+
/** Each environment provisioned, with the resources its worker and secret were wired to. */
|
|
88
|
+
environments: Array<{
|
|
89
|
+
env: ManagedEnvironment;
|
|
90
|
+
} & StorageResources>;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Provision the storage infrastructure: check the account, create every environment's bucket, write
|
|
94
|
+
* every environment's credentials, then deploy every environment's sweep worker.
|
|
95
|
+
*
|
|
96
|
+
* The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
|
|
97
|
+
* must not boot before the secret it reads. Fanning each phase across all environments — rather than
|
|
98
|
+
* completing one environment end to end before starting the next — means a failure creating prod's
|
|
99
|
+
* bucket stops the run before staging's worker is deployed against a half-provisioned account.
|
|
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
|
+
export declare function provisionStorage(provisioner: StorageProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<StorageProvisionResult>;
|
|
106
|
+
/** The teardown seam — the inverse of {@link StorageProvisioner}. Every step idempotent. */
|
|
107
|
+
export interface StorageDeprovisioner {
|
|
108
|
+
/** Delete this environment's sweep worker. Idempotent (a missing worker is a no-op). */
|
|
109
|
+
deleteWorker(env: ManagedEnvironment): Promise<void>;
|
|
110
|
+
/**
|
|
111
|
+
* Delete this environment's R2 bucket **and every file in it**. **Destructive** — nothing here is
|
|
112
|
+
* recoverable. Idempotent (a missing bucket is a no-op).
|
|
113
|
+
*
|
|
114
|
+
* Emptying the bucket is part of the contract, not a nicety: R2 refuses to delete a bucket that still
|
|
115
|
+
* holds an object, or the parts of a multipart upload that was never completed. An implementation that
|
|
116
|
+
* only called the control-plane delete would work on an untouched bucket and fail on every bucket
|
|
117
|
+
* anyone had used.
|
|
118
|
+
*/
|
|
119
|
+
deleteBucket(env: ManagedEnvironment): Promise<void>;
|
|
120
|
+
}
|
|
121
|
+
/** Teardown options. By default the stored files are **kept** — only the sweep workers come down. */
|
|
122
|
+
export interface StorageDeprovisionOptions {
|
|
123
|
+
/**
|
|
124
|
+
* Also delete the R2 buckets, with every file in them. Off by default, because those files are the
|
|
125
|
+
* adopter's data and no deploy can restore them — the flag is the confirmation.
|
|
126
|
+
*/
|
|
127
|
+
deleteStorage?: boolean;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
|
|
131
|
+
* sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
|
|
132
|
+
* everything in them. Idempotent end to end.
|
|
133
|
+
*
|
|
134
|
+
* `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
|
|
135
|
+
* environment is provisioned; an environment this skipped would be one the project deploys to with no
|
|
136
|
+
* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
|
|
137
|
+
*/
|
|
138
|
+
export declare function deprovisionStorage(deprovisioner: StorageDeprovisioner, environments: DeclaredEnvironments | readonly string[], options?: StorageDeprovisionOptions): Promise<void>;
|
|
139
|
+
//# 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,112 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { STORAGE_CAPABILITY } from "../workflows/specs.js";
|
|
4
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
|
+
import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
|
|
6
|
+
import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
7
|
+
//#region src/provision/provisionStorage.ts
|
|
8
|
+
/**
|
|
9
|
+
* The provisioning orchestration for the storage capability — the live counterpart to
|
|
10
|
+
* `pithy add storage`'s config wiring.
|
|
11
|
+
*
|
|
12
|
+
* The split is deliberate and worth stating, because the two commands look like one. `pithy add`
|
|
13
|
+
* writes *bindings*: it installs the package, adds `storage()` to `pithy.config.ts`, and puts a
|
|
14
|
+
* `STORAGE_BUCKET` entry in `wrangler.jsonc`. It touches no Cloudflare account and provisions
|
|
15
|
+
* nothing — an `add` that reached out to an account would make adding a capability an operation you
|
|
16
|
+
* could not do offline, or in CI, or without credentials. This command stands up what those bindings
|
|
17
|
+
* point at: the R2 bucket, the per-environment credential secret, and the sweep worker.
|
|
18
|
+
*
|
|
19
|
+
* The `STORAGE_SWEEP` Workflow binding is the exception, and it belongs to this side of the split.
|
|
20
|
+
* Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
|
|
21
|
+
* per environment — so `add` writes none (a partial entry stops wrangler loading the config) and the
|
|
22
|
+
* CLI writes the complete entry here, once the host worker exists.
|
|
23
|
+
*
|
|
24
|
+
* The live Cloudflare/wrangler steps sit behind the {@link StorageProvisioner} seam, so the
|
|
25
|
+
* orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that
|
|
26
|
+
* records its call order, and no account. **Every step is idempotent**: find-then-create for the
|
|
27
|
+
* bucket, create-then-update for the secret, and a deploy that overwrites. Re-running is a no-op.
|
|
28
|
+
*
|
|
29
|
+
* **What it does not do.** Cloudflare exposes no API for minting an R2 S3 access-key pair, so nothing
|
|
30
|
+
* here mints one. The pair is supplied by the operator — flags, or `R2_CREDENTIALS` in `.dev.vars` —
|
|
31
|
+
* and written into the secret as given. That is a real limitation, and the manifest says so rather
|
|
32
|
+
* than promising a mint that does not happen.
|
|
33
|
+
*/
|
|
34
|
+
/**
|
|
35
|
+
* The bucket objects live in, **per project and per environment** — `acme-staging-storage`,
|
|
36
|
+
* `acme-prod-storage`.
|
|
37
|
+
*
|
|
38
|
+
* One bucket per account would mean staging writes objects into the bucket prod reads, and a staging
|
|
39
|
+
* teardown deletes prod's files. Buckets are free — the cost is bytes and operations — so a shared one
|
|
40
|
+
* buys nothing and risks everything. The same posture `@pithy-sh/media` takes, and the opposite of
|
|
41
|
+
* `@pithy-sh/email`'s deliberately project-shared suppression database.
|
|
42
|
+
*
|
|
43
|
+
* The project segment is what makes provisioning's find-then-create safe. R2's namespace is flat and
|
|
44
|
+
* account-wide, so an unprefixed `pithy-storage-prod` would be *found* by a second Pithy project in the
|
|
45
|
+
* same account and silently adopted — two apps writing objects into one bucket, and either teardown
|
|
46
|
+
* deleting both. The name is the only partition R2 offers, so the name carries the owner.
|
|
47
|
+
*
|
|
48
|
+
* Named as an **R2 bucket** through core's naming facade, which is the one namespace whose rule is
|
|
49
|
+
* genuinely 3–63 lowercase characters, starting and ending alphanumeric. Every other namespace Pithy
|
|
50
|
+
* writes into was once held to that same 63 for no reason; asking for a bucket by name is how this one
|
|
51
|
+
* keeps it on purpose.
|
|
52
|
+
*/
|
|
53
|
+
function storageBucketName(project, env) {
|
|
54
|
+
return resourceNames(project).env(env).r2(STORAGE_CAPABILITY);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The deployed sweep-worker name for a project's environment — also its resolved config's basename.
|
|
58
|
+
*
|
|
59
|
+
* A **Worker script**, so 63 rather than the Workflow's 64, and refused rather than truncated: a script
|
|
60
|
+
* cannot be renamed once a deploy or a `service` binding points at it.
|
|
61
|
+
*/
|
|
62
|
+
function storageWorkerName(project, env) {
|
|
63
|
+
return resourceNames(project).env(env).worker(STORAGE_CAPABILITY);
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Provision the storage infrastructure: check the account, create every environment's bucket, write
|
|
67
|
+
* every environment's credentials, then deploy every environment's sweep worker.
|
|
68
|
+
*
|
|
69
|
+
* The phase order is the contract. A secret must not name a bucket that does not exist, and a worker
|
|
70
|
+
* must not boot before the secret it reads. Fanning each phase across all environments — rather than
|
|
71
|
+
* completing one environment end to end before starting the next — means a failure creating prod's
|
|
72
|
+
* bucket stops the run before staging's worker is deployed against a half-provisioned account.
|
|
73
|
+
*
|
|
74
|
+
* `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
|
|
75
|
+
* environment is provisioned; an environment this skipped would be one the project deploys to with no
|
|
76
|
+
* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
|
|
77
|
+
*/
|
|
78
|
+
async function provisionStorage(provisioner, environments) {
|
|
79
|
+
await provisioner.preflight();
|
|
80
|
+
const resources = /* @__PURE__ */ new Map();
|
|
81
|
+
for (const env of managedEnvironments(environments)) {
|
|
82
|
+
const { bucketName } = await provisioner.ensureBucket(env);
|
|
83
|
+
resources.set(env, { bucketName });
|
|
84
|
+
}
|
|
85
|
+
for (const env of managedEnvironments(environments)) await provisioner.writeCredentials(env, resourcesFor(resources, env));
|
|
86
|
+
for (const env of managedEnvironments(environments)) await provisioner.deployWorker(env, resourcesFor(resources, env));
|
|
87
|
+
return { environments: managedEnvironments(environments).map((env) => ({
|
|
88
|
+
env,
|
|
89
|
+
...resourcesFor(resources, env)
|
|
90
|
+
})) };
|
|
91
|
+
}
|
|
92
|
+
/** Read back an environment's resources. Absent is impossible by construction, so the throw is a bug check. */
|
|
93
|
+
function resourcesFor(resources, env) {
|
|
94
|
+
const found = resources.get(env);
|
|
95
|
+
if (!found) throw new InternalError({ message: `No provisioned resources for the ${env} environment.` });
|
|
96
|
+
return found;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Tear down the storage infrastructure, reversing {@link provisionStorage}: delete every environment's
|
|
100
|
+
* sweep worker first (they bind the bucket), then — only when `deleteStorage` is set — the buckets and
|
|
101
|
+
* everything in them. Idempotent end to end.
|
|
102
|
+
*
|
|
103
|
+
* `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
|
|
104
|
+
* environment is provisioned; an environment this skipped would be one the project deploys to with no
|
|
105
|
+
* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
|
|
106
|
+
*/
|
|
107
|
+
async function deprovisionStorage(deprovisioner, environments, options = {}) {
|
|
108
|
+
for (const env of managedEnvironments(environments)) await deprovisioner.deleteWorker(env);
|
|
109
|
+
if (options.deleteStorage) for (const env of managedEnvironments(environments)) await deprovisioner.deleteBucket(env);
|
|
110
|
+
}
|
|
111
|
+
//#endregion
|
|
112
|
+
export { deprovisionStorage, provisionStorage, storageBucketName, storageWorkerName };
|