@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,507 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { StorageObject } from "../data/storageObject.js";
|
|
4
|
+
import { StorageForbiddenError, StorageNotFoundError, StorageShareExpiredError, StorageShareRevokedError, StorageUploadIncompleteError } from "../error/errors.js";
|
|
5
|
+
import { collectParts, needsMultipart, planMultipart } from "../object/multipart.js";
|
|
6
|
+
import { StorageShare } from "../data/share.js";
|
|
7
|
+
import { STORAGE_OBJECTS_TABLE, STORAGE_SHARES_TABLE } from "../data/tables.js";
|
|
8
|
+
import { deriveObjectKey } from "../object/key.js";
|
|
9
|
+
import { assertWithinQuota, insertReservingQuota, updateSettlingQuota } from "../quota/quota.js";
|
|
10
|
+
//#region src/http/handlers.ts
|
|
11
|
+
/** Drop the server-only fields. The single place a row becomes something a client may see. */
|
|
12
|
+
function view(object) {
|
|
13
|
+
return {
|
|
14
|
+
id: object.id,
|
|
15
|
+
path: object.path,
|
|
16
|
+
ownerId: object.ownerId,
|
|
17
|
+
contentType: object.contentType,
|
|
18
|
+
size: object.size,
|
|
19
|
+
visibility: object.visibility,
|
|
20
|
+
checksum: object.checksum,
|
|
21
|
+
status: object.status,
|
|
22
|
+
createdAt: object.createdAt,
|
|
23
|
+
updatedAt: object.updatedAt
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
/** Load one row, decoded through the schema. Null when absent. */
|
|
27
|
+
async function findObject(deps, id) {
|
|
28
|
+
const row = await deps.db.selectFrom(STORAGE_OBJECTS_TABLE).selectAll().where("id", "=", id).executeTakeFirst();
|
|
29
|
+
return row ? StorageObject.parse(row) : null;
|
|
30
|
+
}
|
|
31
|
+
/** Load one row or throw `storage/not_found`. */
|
|
32
|
+
async function loadObject(deps, id) {
|
|
33
|
+
const object = await findObject(deps, id);
|
|
34
|
+
if (!object) throw new StorageNotFoundError({ detail: `no storage object ${id}` });
|
|
35
|
+
return object;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Require the caller to own the object. A private object they do not own is reported as **missing**,
|
|
39
|
+
* so the route cannot be used to test whether an id exists. A public object is reported as
|
|
40
|
+
* **forbidden**, because its existence is already public knowledge and "missing" would just be a lie.
|
|
41
|
+
*/
|
|
42
|
+
function assertOwner(object, ownerId) {
|
|
43
|
+
if (ownerId !== null && object.ownerId === ownerId) return;
|
|
44
|
+
if (object.visibility === "public") throw new StorageForbiddenError({ detail: `object ${object.id} is owned by ${object.ownerId ?? "the system"}` });
|
|
45
|
+
throw new StorageNotFoundError({ detail: `object ${object.id} is not owned by ${ownerId ?? "an anonymous caller"}` });
|
|
46
|
+
}
|
|
47
|
+
/** Require the caller to be allowed to *read* the object: it is public, or it is theirs. */
|
|
48
|
+
function assertReadable(object, ownerId) {
|
|
49
|
+
if (object.visibility === "public") return;
|
|
50
|
+
if (ownerId !== null && object.ownerId === ownerId) return;
|
|
51
|
+
throw new StorageNotFoundError({ detail: `object ${object.id} is not readable by ${ownerId ?? "an anonymous caller"}` });
|
|
52
|
+
}
|
|
53
|
+
/** Require the object's bytes to actually be there. A `pending` row has a record but no content. */
|
|
54
|
+
function assertStored(object) {
|
|
55
|
+
if (object.status === "stored") return;
|
|
56
|
+
throw new StorageUploadIncompleteError({ detail: `object ${object.id} is ${object.status}, not stored` });
|
|
57
|
+
}
|
|
58
|
+
/** Write a whole row back through the codec — the round-trip rule, so no field bypasses its codec. */
|
|
59
|
+
async function saveObject(deps, object) {
|
|
60
|
+
const record = StorageObject.encode(object);
|
|
61
|
+
await deps.db.updateTable(STORAGE_OBJECTS_TABLE).set(record).where("id", "=", object.id).execute();
|
|
62
|
+
return object;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Start an upload: reserve the row and its quota, then mint the URL(s) the client PUTs to.
|
|
66
|
+
*
|
|
67
|
+
* **The reservation is the insert, and the insert is conditional.** A `pending` row holds its bytes
|
|
68
|
+
* against the owner's quota, so the row has to exist before an upload can proceed — but a check that
|
|
69
|
+
* ran separately from the write would let a burst of concurrent inits each read a used total none of
|
|
70
|
+
* them had yet contributed to. `insertReservingQuota` evaluates the sum inside the write instead, so
|
|
71
|
+
* the tenth concurrent init sees the other nine (`quota/quota.ts`).
|
|
72
|
+
*
|
|
73
|
+
* The pre-check above it is a courtesy: it refuses an obviously oversized upload before an R2
|
|
74
|
+
* multipart upload exists to clean up. When the conditional insert loses the race anyway, that
|
|
75
|
+
* multipart upload is aborted — a refused init leaves R2 holding nothing.
|
|
76
|
+
*/
|
|
77
|
+
async function initUpload(deps, input) {
|
|
78
|
+
const now = deps.now();
|
|
79
|
+
await assertWithinQuota({
|
|
80
|
+
db: deps.db,
|
|
81
|
+
ownerId: deps.ownerId,
|
|
82
|
+
limitBytes: deps.config.quota.bytesPerOwner,
|
|
83
|
+
additionalBytes: input.size
|
|
84
|
+
});
|
|
85
|
+
const key = deriveObjectKey();
|
|
86
|
+
const multipart = needsMultipart(input.size, deps.config.multipartThresholdBytes);
|
|
87
|
+
let upload;
|
|
88
|
+
let uploadId = null;
|
|
89
|
+
if (multipart) {
|
|
90
|
+
const plan = planMultipart(input.size, deps.config.partSizeBytes);
|
|
91
|
+
uploadId = await deps.store.initMultipart(key, input.contentType);
|
|
92
|
+
const parts = [];
|
|
93
|
+
for (const part of plan.parts) parts.push({
|
|
94
|
+
partNumber: part.partNumber,
|
|
95
|
+
offset: part.offset,
|
|
96
|
+
length: part.length,
|
|
97
|
+
url: await deps.store.presignPart(key, uploadId, part.partNumber)
|
|
98
|
+
});
|
|
99
|
+
upload = {
|
|
100
|
+
kind: "multipart",
|
|
101
|
+
uploadId,
|
|
102
|
+
partSize: plan.partSize,
|
|
103
|
+
parts
|
|
104
|
+
};
|
|
105
|
+
} else upload = {
|
|
106
|
+
kind: "single",
|
|
107
|
+
url: await deps.store.presignPut(key, input.contentType, input.size)
|
|
108
|
+
};
|
|
109
|
+
const object = {
|
|
110
|
+
id: deps.newId(),
|
|
111
|
+
key,
|
|
112
|
+
path: input.path,
|
|
113
|
+
ownerId: deps.ownerId,
|
|
114
|
+
contentType: input.contentType,
|
|
115
|
+
size: input.size,
|
|
116
|
+
visibility: input.visibility ?? deps.config.defaultVisibility,
|
|
117
|
+
checksum: null,
|
|
118
|
+
status: "pending",
|
|
119
|
+
uploadId,
|
|
120
|
+
createdAt: now,
|
|
121
|
+
updatedAt: now
|
|
122
|
+
};
|
|
123
|
+
try {
|
|
124
|
+
await insertReservingQuota({
|
|
125
|
+
db: deps.db,
|
|
126
|
+
ownerId: deps.ownerId,
|
|
127
|
+
limitBytes: deps.config.quota.bytesPerOwner,
|
|
128
|
+
additionalBytes: input.size,
|
|
129
|
+
record: StorageObject.encode(object)
|
|
130
|
+
});
|
|
131
|
+
} catch (error) {
|
|
132
|
+
if (uploadId) await deps.store.abortMultipart(key, uploadId).catch(() => {});
|
|
133
|
+
throw error;
|
|
134
|
+
}
|
|
135
|
+
return {
|
|
136
|
+
object: view(object),
|
|
137
|
+
upload
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* Finalize an upload: assemble the parts (for a multipart), then confirm against R2 that the bytes
|
|
142
|
+
* are really there before the row is allowed to claim they are.
|
|
143
|
+
*
|
|
144
|
+
* The `head` is not a formality. Without it a client could complete an upload it never performed and
|
|
145
|
+
* leave a `stored` row pointing at nothing — a 404 from R2 at read time, long after the request that
|
|
146
|
+
* caused it. The size *and the content type* R2 reports win over the declared ones, so the row records
|
|
147
|
+
* what was stored rather than what was promised.
|
|
148
|
+
*
|
|
149
|
+
* **It is also where the quota is settled.** Part URLs carry no signed `Content-Length` — the final
|
|
150
|
+
* part's differs from every other, so pinning one at mint time would mean knowing the total up front
|
|
151
|
+
* and would still leave the last part unconstrained. The declared size therefore buys a *reservation*,
|
|
152
|
+
* not a limit, and an owner who declares 100 MiB can PUT far more across those URLs. Completion is the
|
|
153
|
+
* first and last point where the real byte count is known and the object can still be thrown away, so
|
|
154
|
+
* anything past the reservation is re-asserted against the quota here.
|
|
155
|
+
*
|
|
156
|
+
* **That re-assertion is the write, for the same reason the reservation was.** A check that ran ahead
|
|
157
|
+
* of the `UPDATE` would let two completions racing on one owner both read a total neither had yet
|
|
158
|
+
* contributed to, both pass, and both store — the init race, reproduced at the other end of the
|
|
159
|
+
* lifecycle. `updateSettlingQuota` evaluates the sum inside the update, so the second completion sees
|
|
160
|
+
* the first (`quota/quota.ts`).
|
|
161
|
+
*/
|
|
162
|
+
async function completeUpload(deps, id, input) {
|
|
163
|
+
const object = await loadObject(deps, id);
|
|
164
|
+
assertOwner(object, deps.ownerId);
|
|
165
|
+
if (object.status === "stored") return view(object);
|
|
166
|
+
if (object.status !== "pending") throw new StorageUploadIncompleteError({ detail: `object ${id} is ${object.status} and cannot be completed` });
|
|
167
|
+
if (object.uploadId) {
|
|
168
|
+
const expected = planMultipart(object.size ?? 0, deps.config.partSizeBytes).partCount;
|
|
169
|
+
const parts = collectParts(input.parts, expected);
|
|
170
|
+
await deps.store.completeMultipart(object.key, object.uploadId, parts);
|
|
171
|
+
}
|
|
172
|
+
const metadata = await deps.store.head(object.key);
|
|
173
|
+
if (!metadata) throw new StorageUploadIncompleteError({
|
|
174
|
+
message: "No bytes were uploaded for that file.",
|
|
175
|
+
action: "Upload to the URL the init call returned, then complete again.",
|
|
176
|
+
detail: `R2 has no object at ${object.key}`
|
|
177
|
+
});
|
|
178
|
+
const settled = {
|
|
179
|
+
...object,
|
|
180
|
+
status: "stored",
|
|
181
|
+
size: metadata.size,
|
|
182
|
+
contentType: metadata.contentType ?? object.contentType,
|
|
183
|
+
checksum: input.checksum ?? metadata.checksumSha256 ?? null,
|
|
184
|
+
uploadId: null,
|
|
185
|
+
updatedAt: deps.now()
|
|
186
|
+
};
|
|
187
|
+
const overshoot = metadata.size - (object.size ?? 0);
|
|
188
|
+
if (overshoot <= 0) return view(await saveObject(deps, settled));
|
|
189
|
+
try {
|
|
190
|
+
await updateSettlingQuota({
|
|
191
|
+
db: deps.db,
|
|
192
|
+
ownerId: object.ownerId,
|
|
193
|
+
limitBytes: deps.config.quota.bytesPerOwner,
|
|
194
|
+
additionalBytes: overshoot,
|
|
195
|
+
record: StorageObject.encode(settled)
|
|
196
|
+
});
|
|
197
|
+
} catch (error) {
|
|
198
|
+
await deps.store.delete(object.key).catch(() => {});
|
|
199
|
+
await saveObject(deps, {
|
|
200
|
+
...object,
|
|
201
|
+
status: "failed",
|
|
202
|
+
uploadId: null,
|
|
203
|
+
updatedAt: deps.now()
|
|
204
|
+
});
|
|
205
|
+
throw error;
|
|
206
|
+
}
|
|
207
|
+
return view(settled);
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Abandon an in-flight upload: tell R2 to discard the stored parts, then mark the row `failed`.
|
|
211
|
+
*
|
|
212
|
+
* The row survives rather than being deleted. `failed` rows are excluded from the quota sum, so they
|
|
213
|
+
* hold nothing, and keeping them means an owner can see that an upload was attempted and abandoned
|
|
214
|
+
* instead of the record silently evaporating.
|
|
215
|
+
*
|
|
216
|
+
* **The bytes are R2's problem after this, not the row's.** A single-PUT abort cannot revoke the
|
|
217
|
+
* presigned URL it handed out — nothing can, which is the whole cost of presigning — so a client may
|
|
218
|
+
* still PUT to it for the rest of that URL's hour, after the delete below has run. The row that
|
|
219
|
+
* survives therefore stops *claiming* its key the moment it goes `failed`: the orphan sweep matches
|
|
220
|
+
* only rows that bill for a key, so anything that lands afterwards is collected as an orphan rather
|
|
221
|
+
* than sheltered forever by a row that counts toward no quota (`workflows/sweep.ts`).
|
|
222
|
+
*/
|
|
223
|
+
async function abortUpload(deps, id) {
|
|
224
|
+
const object = await loadObject(deps, id);
|
|
225
|
+
assertOwner(object, deps.ownerId);
|
|
226
|
+
if (object.status === "stored") throw new StorageUploadIncompleteError({
|
|
227
|
+
message: "That upload already finished.",
|
|
228
|
+
action: "Delete the file instead.",
|
|
229
|
+
detail: `object ${id} is stored`
|
|
230
|
+
});
|
|
231
|
+
if (object.uploadId) await deps.store.abortMultipart(object.key, object.uploadId);
|
|
232
|
+
await deps.store.delete(object.key);
|
|
233
|
+
return view(await saveObject(deps, {
|
|
234
|
+
...object,
|
|
235
|
+
status: "failed",
|
|
236
|
+
uploadId: null,
|
|
237
|
+
updatedAt: deps.now()
|
|
238
|
+
}));
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Resume a multipart upload: the parts R2 already holds, plus a **freshly presigned** URL for each
|
|
242
|
+
* one still missing.
|
|
243
|
+
*
|
|
244
|
+
* This is what makes multipart resumable at all. `initUpload` presigns every part once, and those
|
|
245
|
+
* URLs lapse an hour later — a 40 GiB upload is 640 of them, and a client that stalls or dies has no
|
|
246
|
+
* way back to the ones it never sent. Re-minting them here is the recovery path, and it is a route
|
|
247
|
+
* rather than a longer TTL because a presigned URL cannot be revoked: minting on demand keeps each
|
|
248
|
+
* one's life short and its issue authorized.
|
|
249
|
+
*
|
|
250
|
+
* Only while the row is `pending`. A `stored` row has no upload left to resume, and a `failed` one had
|
|
251
|
+
* its parts discarded — re-presigning against either would hand out URLs addressing nothing.
|
|
252
|
+
*/
|
|
253
|
+
async function listUploadParts(deps, id) {
|
|
254
|
+
const object = await loadObject(deps, id);
|
|
255
|
+
assertOwner(object, deps.ownerId);
|
|
256
|
+
const uploadId = object.uploadId;
|
|
257
|
+
if (object.status !== "pending" || !uploadId) throw new StorageUploadIncompleteError({
|
|
258
|
+
message: "That upload has no parts to resume.",
|
|
259
|
+
action: "Only an in-flight multipart upload can be resumed. Start a new upload.",
|
|
260
|
+
detail: `object ${id} is ${object.status} with uploadId ${uploadId ?? "null"}`
|
|
261
|
+
});
|
|
262
|
+
const plan = planMultipart(object.size ?? 0, deps.config.partSizeBytes);
|
|
263
|
+
const uploaded = await deps.store.listParts(object.key, uploadId);
|
|
264
|
+
const stored = new Set(uploaded.map((part) => part.partNumber));
|
|
265
|
+
const missing = [];
|
|
266
|
+
for (const part of plan.parts) {
|
|
267
|
+
if (stored.has(part.partNumber)) continue;
|
|
268
|
+
missing.push({
|
|
269
|
+
partNumber: part.partNumber,
|
|
270
|
+
offset: part.offset,
|
|
271
|
+
length: part.length,
|
|
272
|
+
url: await deps.store.presignPart(object.key, uploadId, part.partNumber)
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
return {
|
|
276
|
+
uploadId,
|
|
277
|
+
partSize: plan.partSize,
|
|
278
|
+
partCount: plan.partCount,
|
|
279
|
+
uploaded,
|
|
280
|
+
missing
|
|
281
|
+
};
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Encode a cursor. Keyset, not offset: an `OFFSET` page skips rows a concurrent upload shifted, so a
|
|
285
|
+
* client paging through their files while uploading would miss some. Base64url keeps it opaque, which
|
|
286
|
+
* is the point — the shape is ours to change.
|
|
287
|
+
*/
|
|
288
|
+
function encodeCursor(cursor) {
|
|
289
|
+
const json = JSON.stringify(cursor);
|
|
290
|
+
const bytes = new TextEncoder().encode(json);
|
|
291
|
+
const binary = String.fromCharCode(...bytes);
|
|
292
|
+
return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
|
293
|
+
}
|
|
294
|
+
/** Decode a cursor, or `null` when it is not one we minted. A bad cursor starts from the beginning. */
|
|
295
|
+
function decodeCursor(value) {
|
|
296
|
+
if (!value) return null;
|
|
297
|
+
try {
|
|
298
|
+
const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
|
|
299
|
+
const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
|
|
300
|
+
const parsed = JSON.parse(new TextDecoder().decode(bytes));
|
|
301
|
+
if (typeof parsed !== "object" || parsed === null) return null;
|
|
302
|
+
const { path, id } = parsed;
|
|
303
|
+
return typeof path === "string" && typeof id === "string" ? {
|
|
304
|
+
path,
|
|
305
|
+
id
|
|
306
|
+
} : null;
|
|
307
|
+
} catch {
|
|
308
|
+
return null;
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
/** Default page size — generous enough for a file browser, small enough to stay one index read. */
|
|
312
|
+
const DEFAULT_LIST_LIMIT = 50;
|
|
313
|
+
/**
|
|
314
|
+
* One page of the caller's files, ordered by logical path. Scoped to the authenticated owner: there
|
|
315
|
+
* is no way to list another owner's files, and no parameter that could be made to.
|
|
316
|
+
*/
|
|
317
|
+
async function listObjects(deps, query) {
|
|
318
|
+
const limit = query.limit ?? DEFAULT_LIST_LIMIT;
|
|
319
|
+
const after = decodeCursor(query.cursor);
|
|
320
|
+
let statement = deps.db.selectFrom(STORAGE_OBJECTS_TABLE).selectAll().where("ownerId", "=", deps.ownerId).orderBy("path", "asc").orderBy("id", "asc").limit(limit + 1);
|
|
321
|
+
if (query.prefix) {
|
|
322
|
+
const escaped = query.prefix.replace(/[\\%_]/g, (character) => `\\${character}`);
|
|
323
|
+
statement = statement.where("path", "like", `${escaped}%`);
|
|
324
|
+
}
|
|
325
|
+
if (after) statement = statement.where((eb) => eb.or([eb("path", ">", after.path), eb.and([eb("path", "=", after.path), eb("id", ">", after.id)])]));
|
|
326
|
+
const rows = await statement.execute();
|
|
327
|
+
const page = rows.slice(0, limit).map((row) => StorageObject.parse(row));
|
|
328
|
+
const objects = page.map(view);
|
|
329
|
+
if (rows.length <= limit) return { objects };
|
|
330
|
+
const last = page[page.length - 1];
|
|
331
|
+
return last ? {
|
|
332
|
+
objects,
|
|
333
|
+
cursor: encodeCursor({
|
|
334
|
+
path: last.path,
|
|
335
|
+
id: last.id
|
|
336
|
+
})
|
|
337
|
+
} : { objects };
|
|
338
|
+
}
|
|
339
|
+
/** Load an object for reading, enforcing public-or-owner and that its bytes exist. */
|
|
340
|
+
async function readableObject(deps, id) {
|
|
341
|
+
const object = await loadObject(deps, id);
|
|
342
|
+
assertReadable(object, deps.ownerId);
|
|
343
|
+
assertStored(object);
|
|
344
|
+
return object;
|
|
345
|
+
}
|
|
346
|
+
/** How long a direct-download URL stays valid. Short: it is bearer-equivalent and cannot be revoked. */
|
|
347
|
+
const PRESIGNED_URL_TTL_SECONDS = 300;
|
|
348
|
+
/**
|
|
349
|
+
* Mint a presigned GET — the no-Worker-in-the-byte-path escape hatch.
|
|
350
|
+
*
|
|
351
|
+
* Authorization happens **here**, once, and then the URL is on its own: it cannot be revoked, and
|
|
352
|
+
* anyone holding it can read the bytes until it lapses. Five minutes is short enough that a URL
|
|
353
|
+
* pasted into a chat is dead before it is read, and long enough to start a large download.
|
|
354
|
+
*/
|
|
355
|
+
async function presignObject(deps, id) {
|
|
356
|
+
const object = await readableObject(deps, id);
|
|
357
|
+
return {
|
|
358
|
+
url: await deps.store.presignGet(object.key, { expiresIn: 300 }),
|
|
359
|
+
expiresInSeconds: 300
|
|
360
|
+
};
|
|
361
|
+
}
|
|
362
|
+
/** Rename a file, change who may read it, or both. The key never moves — only the row changes. */
|
|
363
|
+
async function updateObject(deps, id, input) {
|
|
364
|
+
const object = await loadObject(deps, id);
|
|
365
|
+
assertOwner(object, deps.ownerId);
|
|
366
|
+
return view(await saveObject(deps, {
|
|
367
|
+
...object,
|
|
368
|
+
path: input.path ?? object.path,
|
|
369
|
+
visibility: input.visibility ?? object.visibility,
|
|
370
|
+
updatedAt: deps.now()
|
|
371
|
+
}));
|
|
372
|
+
}
|
|
373
|
+
/**
|
|
374
|
+
* Copy a file server-side. The bytes are copied by R2 and never enter the Worker; the copy is a new
|
|
375
|
+
* object with its own id, its own key, and its own share links — it is not an alias.
|
|
376
|
+
*
|
|
377
|
+
* Owner-scoped, like every other mutating route: you may copy your own files. Copying a *public* file
|
|
378
|
+
* you do not own is a plausible feature and deliberately not this one — it would let any reader
|
|
379
|
+
* duplicate bytes into their own quota on the owner's storage bill, which is a decision an adopter
|
|
380
|
+
* should make explicitly rather than inherit.
|
|
381
|
+
*/
|
|
382
|
+
async function copyObject(deps, id, input) {
|
|
383
|
+
const source = await loadObject(deps, id);
|
|
384
|
+
assertOwner(source, deps.ownerId);
|
|
385
|
+
assertStored(source);
|
|
386
|
+
await assertWithinQuota({
|
|
387
|
+
db: deps.db,
|
|
388
|
+
ownerId: deps.ownerId,
|
|
389
|
+
limitBytes: deps.config.quota.bytesPerOwner,
|
|
390
|
+
additionalBytes: source.size ?? 0
|
|
391
|
+
});
|
|
392
|
+
const key = deriveObjectKey();
|
|
393
|
+
await deps.store.copy(source.key, key);
|
|
394
|
+
const now = deps.now();
|
|
395
|
+
const copy = {
|
|
396
|
+
...source,
|
|
397
|
+
id: deps.newId(),
|
|
398
|
+
key,
|
|
399
|
+
path: input.path,
|
|
400
|
+
ownerId: deps.ownerId,
|
|
401
|
+
visibility: "private",
|
|
402
|
+
status: "stored",
|
|
403
|
+
uploadId: null,
|
|
404
|
+
createdAt: now,
|
|
405
|
+
updatedAt: now
|
|
406
|
+
};
|
|
407
|
+
try {
|
|
408
|
+
await insertReservingQuota({
|
|
409
|
+
db: deps.db,
|
|
410
|
+
ownerId: deps.ownerId,
|
|
411
|
+
limitBytes: deps.config.quota.bytesPerOwner,
|
|
412
|
+
additionalBytes: source.size ?? 0,
|
|
413
|
+
record: StorageObject.encode(copy)
|
|
414
|
+
});
|
|
415
|
+
} catch (error) {
|
|
416
|
+
await deps.store.delete(key).catch(() => {});
|
|
417
|
+
throw error;
|
|
418
|
+
}
|
|
419
|
+
return view(copy);
|
|
420
|
+
}
|
|
421
|
+
/**
|
|
422
|
+
* Delete a file: the object first, then the row. Every share link pointing at it goes with the row,
|
|
423
|
+
* through the foreign key's `ON DELETE CASCADE` — a share that outlived its object would be a live
|
|
424
|
+
* token for bytes that no longer exist.
|
|
425
|
+
*
|
|
426
|
+
* The object delete is best-effort. An R2 hiccup must not leave a row nobody can remove; the orphan
|
|
427
|
+
* sweep collects an object whose row went first.
|
|
428
|
+
*/
|
|
429
|
+
async function deleteObject(deps, id) {
|
|
430
|
+
const object = await loadObject(deps, id);
|
|
431
|
+
assertOwner(object, deps.ownerId);
|
|
432
|
+
if (object.uploadId) await deps.store.abortMultipart(object.key, object.uploadId).catch(() => {});
|
|
433
|
+
await deps.store.delete(object.key).catch(() => {});
|
|
434
|
+
await deps.db.deleteFrom(STORAGE_OBJECTS_TABLE).where("id", "=", id).execute();
|
|
435
|
+
return {
|
|
436
|
+
id,
|
|
437
|
+
deleted: true
|
|
438
|
+
};
|
|
439
|
+
}
|
|
440
|
+
/** Mint a revocable share link for one file. */
|
|
441
|
+
async function createShare(deps, id, input) {
|
|
442
|
+
const object = await loadObject(deps, id);
|
|
443
|
+
assertOwner(object, deps.ownerId);
|
|
444
|
+
assertStored(object);
|
|
445
|
+
const now = deps.now();
|
|
446
|
+
const share = {
|
|
447
|
+
token: deps.newToken(),
|
|
448
|
+
objectId: object.id,
|
|
449
|
+
expiresAt: input.expiresInSeconds ? new Date(now.getTime() + input.expiresInSeconds * 1e3) : null,
|
|
450
|
+
revokedAt: null,
|
|
451
|
+
createdAt: now
|
|
452
|
+
};
|
|
453
|
+
await deps.db.insertInto(STORAGE_SHARES_TABLE).values(StorageShare.encode(share)).execute();
|
|
454
|
+
return {
|
|
455
|
+
token: share.token,
|
|
456
|
+
objectId: share.objectId,
|
|
457
|
+
expiresAt: share.expiresAt,
|
|
458
|
+
createdAt: share.createdAt
|
|
459
|
+
};
|
|
460
|
+
}
|
|
461
|
+
/**
|
|
462
|
+
* Withdraw a share link. A write, effective on the very next request — which is the whole reason a
|
|
463
|
+
* share is a row and not a presigned URL.
|
|
464
|
+
*
|
|
465
|
+
* Revoking twice is a no-op. The first revocation time is kept, because when a link stopped working
|
|
466
|
+
* is the fact anyone actually needs.
|
|
467
|
+
*/
|
|
468
|
+
async function revokeShare(deps, token) {
|
|
469
|
+
const row = await deps.db.selectFrom(STORAGE_SHARES_TABLE).selectAll().where("token", "=", token).executeTakeFirst();
|
|
470
|
+
if (!row) throw new StorageNotFoundError({ detail: `no share token ${token}` });
|
|
471
|
+
const share = StorageShare.parse(row);
|
|
472
|
+
assertOwner(await loadObject(deps, share.objectId), deps.ownerId);
|
|
473
|
+
if (share.revokedAt) return {
|
|
474
|
+
token,
|
|
475
|
+
revokedAt: share.revokedAt
|
|
476
|
+
};
|
|
477
|
+
const revokedAt = deps.now();
|
|
478
|
+
await deps.db.updateTable(STORAGE_SHARES_TABLE).set(StorageShare.encode({
|
|
479
|
+
...share,
|
|
480
|
+
revokedAt
|
|
481
|
+
})).where("token", "=", token).execute();
|
|
482
|
+
return {
|
|
483
|
+
token,
|
|
484
|
+
revokedAt
|
|
485
|
+
};
|
|
486
|
+
}
|
|
487
|
+
/**
|
|
488
|
+
* Resolve a share token to the object it grants read access to.
|
|
489
|
+
*
|
|
490
|
+
* Revoked and expired are **separate answers**, deliberately. Both are 410, but `storage/share_revoked`
|
|
491
|
+
* says the owner took the link back and `storage/share_expired` says it simply aged out — one is worth
|
|
492
|
+
* asking about, the other is worth re-requesting. Collapsing them into "gone" throws away the only
|
|
493
|
+
* information the holder can act on. Revocation is checked first: an explicit withdrawal is the more
|
|
494
|
+
* specific fact about a link that is both.
|
|
495
|
+
*/
|
|
496
|
+
async function resolveShare(deps, token) {
|
|
497
|
+
const row = await deps.db.selectFrom(STORAGE_SHARES_TABLE).selectAll().where("token", "=", token).executeTakeFirst();
|
|
498
|
+
if (!row) throw new StorageNotFoundError({ detail: `no share token ${token}` });
|
|
499
|
+
const share = StorageShare.parse(row);
|
|
500
|
+
if (share.revokedAt) throw new StorageShareRevokedError({ detail: `share ${token} revoked at ${share.revokedAt.toISOString()}` });
|
|
501
|
+
if (share.expiresAt && share.expiresAt.getTime() <= deps.now().getTime()) throw new StorageShareExpiredError({ detail: `share ${token} expired at ${share.expiresAt.toISOString()}` });
|
|
502
|
+
const object = await loadObject(deps, share.objectId);
|
|
503
|
+
assertStored(object);
|
|
504
|
+
return object;
|
|
505
|
+
}
|
|
506
|
+
//#endregion
|
|
507
|
+
export { PRESIGNED_URL_TTL_SECONDS, abortUpload, completeUpload, copyObject, createShare, deleteObject, initUpload, listObjects, listUploadParts, presignObject, readableObject, resolveShare, revokeShare, updateObject };
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
4
|
+
import type { Context, Hono } from "hono";
|
|
5
|
+
import type { StorageConfig } from "../config/config";
|
|
6
|
+
import { type HandlerDeps } from "./handlers";
|
|
7
|
+
/**
|
|
8
|
+
* The storage routes, their declared verification strategies, and what each accepts:
|
|
9
|
+
*
|
|
10
|
+
* POST /storage → start an upload (bearer | session)
|
|
11
|
+
* json: CreateUploadInput
|
|
12
|
+
* GET /storage → list your files (bearer | session, owner-scoped)
|
|
13
|
+
* query: ListObjectsQuery
|
|
14
|
+
* DELETE /storage/shares/:token → revoke a share (bearer | session, owner-scoped)
|
|
15
|
+
* param: ShareTokenParam
|
|
16
|
+
* POST /storage/:id/complete → finalize a multipart (bearer | session, owner-scoped)
|
|
17
|
+
* param: ObjectIdParam, json: CompleteUploadInput
|
|
18
|
+
* POST /storage/:id/abort → abandon an upload (bearer | session, owner-scoped)
|
|
19
|
+
* param: ObjectIdParam — no body
|
|
20
|
+
* GET /storage/:id/parts → resume a multipart (bearer | session, owner-scoped)
|
|
21
|
+
* param: ObjectIdParam
|
|
22
|
+
* POST /storage/:id/copy → server-side copy (bearer | session, owner-scoped)
|
|
23
|
+
* param: ObjectIdParam, json: CopyObjectInput
|
|
24
|
+
* POST /storage/:id/shares → mint a revocable share (bearer | session, owner-scoped)
|
|
25
|
+
* param: ObjectIdParam, json: CreateShareInput
|
|
26
|
+
* GET /storage/:id/url → presigned direct URL (bearer | session, owner-or-public)
|
|
27
|
+
* param: ObjectIdParam
|
|
28
|
+
* GET /storage/:id → stream the bytes (public when `visibility: 'public'`,
|
|
29
|
+
* otherwise bearer | session + owner)
|
|
30
|
+
* param: ObjectIdParam, query: ObjectReadQuery
|
|
31
|
+
* HEAD /storage/:id → metadata only (bearer | session, owner-scoped)
|
|
32
|
+
* param: ObjectIdParam
|
|
33
|
+
* PATCH /storage/:id → rename or change access (bearer | session, owner-scoped)
|
|
34
|
+
* param: ObjectIdParam, json: UpdateObjectInput
|
|
35
|
+
* DELETE /storage/:id → delete file and row (bearer | session, owner-scoped)
|
|
36
|
+
* param: ObjectIdParam
|
|
37
|
+
* GET /s/:token → fetch via a share link (public — the token is the credential)
|
|
38
|
+
* param: ShareTokenParam, query: ObjectReadQuery
|
|
39
|
+
*
|
|
40
|
+
* **Every validator sits after the guard.** An unauthenticated request with a malformed body is a
|
|
41
|
+
* 401, never a 400 — shape is not something a caller learns before being verified. `POST
|
|
42
|
+
* /storage/:id/abort` carries no json validator because it reads no body: adding one would 400 the
|
|
43
|
+
* bodyless POST every client sends today.
|
|
44
|
+
*
|
|
45
|
+
* `GET /storage/:id` is the one route with two strategies, because a public file must be readable by
|
|
46
|
+
* someone with no session at all. It is therefore **not** wrapped in {@link requireAuth}: the guard
|
|
47
|
+
* would deny before the handler could see that the object is public. Authorization happens inside the
|
|
48
|
+
* handler instead, against `c.var.auth` — which is `null` with no auth capability composed, so a
|
|
49
|
+
* private object is denied by default and only an explicitly public one is served.
|
|
50
|
+
*
|
|
51
|
+
* **Static segments are registered before `:param` ones.** Hono matches in registration order, so
|
|
52
|
+
* `/storage/shares/:token` has to come before `/storage/:id` or a DELETE to `/storage/shares/abc`
|
|
53
|
+
* would be read as deleting the object whose id is `shares`.
|
|
54
|
+
*
|
|
55
|
+
* **Uploads never proxy bytes through the Worker; downloads do.** That asymmetry is the design, not
|
|
56
|
+
* an inconsistency — `serve.ts` carries the reasoning.
|
|
57
|
+
*/
|
|
58
|
+
export interface StorageRoutesOptions {
|
|
59
|
+
/** The resolved storage config. */
|
|
60
|
+
config: StorageConfig;
|
|
61
|
+
/** Where the object routes mount. Defaults to `/storage`. */
|
|
62
|
+
basePath?: string;
|
|
63
|
+
/** Where share fetches mount. Defaults to `/s` — short, because the whole URL gets pasted around. */
|
|
64
|
+
sharePath?: string;
|
|
65
|
+
/** Test seam: resolve handler deps from the request. Defaults to the env-based resolver. */
|
|
66
|
+
resolveDeps?: (c: Context<PithyHonoEnv>) => Promise<HandlerDeps>;
|
|
67
|
+
}
|
|
68
|
+
/** Register the storage sub-router. Returned as the capability's `routes` hook. */
|
|
69
|
+
export declare function registerStorageRoutes(options: StorageRoutesOptions): (app: Hono<PithyHonoEnv>) => void;
|
|
70
|
+
//# sourceMappingURL=routes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAI7E,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKtD,OAAO,EAML,KAAK,WAAW,EASjB,MAAM,YAAY,CAAC;AAqBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAClE;AAuDD,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAiJtG"}
|