@c9up/archive 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 (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +35 -0
  3. package/dist/ArchiveProvider.d.ts +32 -0
  4. package/dist/ArchiveProvider.d.ts.map +1 -0
  5. package/dist/ArchiveProvider.js +91 -0
  6. package/dist/ArchiveProvider.js.map +1 -0
  7. package/dist/GcsDriver.d.ts +41 -0
  8. package/dist/GcsDriver.d.ts.map +1 -0
  9. package/dist/GcsDriver.js +387 -0
  10. package/dist/GcsDriver.js.map +1 -0
  11. package/dist/S3Driver.d.ts +50 -0
  12. package/dist/S3Driver.d.ts.map +1 -0
  13. package/dist/S3Driver.js +642 -0
  14. package/dist/S3Driver.js.map +1 -0
  15. package/dist/StaticMiddleware.d.ts +46 -0
  16. package/dist/StaticMiddleware.d.ts.map +1 -0
  17. package/dist/StaticMiddleware.js +121 -0
  18. package/dist/StaticMiddleware.js.map +1 -0
  19. package/dist/StorageManager.d.ts +178 -0
  20. package/dist/StorageManager.d.ts.map +1 -0
  21. package/dist/StorageManager.js +405 -0
  22. package/dist/StorageManager.js.map +1 -0
  23. package/dist/errors.d.ts +11 -0
  24. package/dist/errors.d.ts.map +1 -0
  25. package/dist/errors.js +14 -0
  26. package/dist/errors.js.map +1 -0
  27. package/dist/expiry.d.ts +15 -0
  28. package/dist/expiry.d.ts.map +1 -0
  29. package/dist/expiry.js +26 -0
  30. package/dist/expiry.js.map +1 -0
  31. package/dist/index.d.ts +17 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +17 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/mime-types.d.ts +17 -0
  36. package/dist/mime-types.d.ts.map +1 -0
  37. package/dist/mime-types.js +47 -0
  38. package/dist/mime-types.js.map +1 -0
  39. package/dist/services/main.d.ts +19 -0
  40. package/dist/services/main.d.ts.map +1 -0
  41. package/dist/services/main.js +33 -0
  42. package/dist/services/main.js.map +1 -0
  43. package/dist/signed-route.d.ts +61 -0
  44. package/dist/signed-route.d.ts.map +1 -0
  45. package/dist/signed-route.js +155 -0
  46. package/dist/signed-route.js.map +1 -0
  47. package/dist/testing/FakeStorage.d.ts +72 -0
  48. package/dist/testing/FakeStorage.d.ts.map +1 -0
  49. package/dist/testing/FakeStorage.js +266 -0
  50. package/dist/testing/FakeStorage.js.map +1 -0
  51. package/package.json +67 -0
  52. package/src/ArchiveProvider.ts +134 -0
  53. package/src/GcsDriver.ts +490 -0
  54. package/src/S3Driver.ts +791 -0
  55. package/src/StaticMiddleware.ts +175 -0
  56. package/src/StorageManager.ts +627 -0
  57. package/src/errors.ts +14 -0
  58. package/src/expiry.ts +41 -0
  59. package/src/index.ts +41 -0
  60. package/src/mime-types.ts +51 -0
  61. package/src/services/main.ts +41 -0
  62. package/src/signed-route.ts +223 -0
  63. package/src/testing/FakeStorage.ts +372 -0
@@ -0,0 +1,372 @@
1
+ /**
2
+ * FakeStorage — in-memory StorageDriver for tests.
3
+ *
4
+ * Every StorageDriver method is implemented against a local `Map` —
5
+ * no filesystem, no network. Use in tests that need to assert on
6
+ * put/get/list/... behaviour without touching real storage.
7
+ *
8
+ * const storage = new FakeStorage();
9
+ * await storage.put('cat.txt', 'meow');
10
+ * expect(await storage.get('cat.txt')).toEqual(Buffer.from('meow'));
11
+ * storage.clear();
12
+ *
13
+ * Kept behind the `./testing` subpath so production imports stay clean.
14
+ */
15
+
16
+ import { createHash } from "node:crypto";
17
+ import { Readable } from "node:stream";
18
+ import { ArchiveError } from "../errors.js";
19
+ import { assertValidExpiry, DEFAULT_EXPIRES_IN } from "../expiry.js";
20
+ import { inferMimeType } from "../mime-types.js";
21
+ import type {
22
+ Metadata,
23
+ PutStreamOptions,
24
+ SignedUrlOptions,
25
+ StorageDriver,
26
+ StorageEntry,
27
+ Visibility,
28
+ } from "../StorageManager.js";
29
+
30
+ interface StoredObject {
31
+ content: Buffer;
32
+ visibility: Visibility;
33
+ lastModified: Date;
34
+ mimeType: string;
35
+ }
36
+
37
+ /** Deterministic secret for FakeStorage signatures. Not a real HMAC
38
+ * key — signatures are opaque, for shape-matching in test assertions. */
39
+ const FAKE_SECRET = "archive-fake-signing-secret-do-not-use-in-prod";
40
+
41
+ export class FakeStorage implements StorageDriver {
42
+ #store = new Map<string, StoredObject>();
43
+
44
+ async put(filePath: string, content: Buffer | string): Promise<void> {
45
+ const buf = typeof content === "string" ? Buffer.from(content) : content;
46
+ this.#store.set(filePath, {
47
+ content: Buffer.from(buf),
48
+ visibility: this.#store.get(filePath)?.visibility ?? "public",
49
+ lastModified: new Date(),
50
+ mimeType:
51
+ inferMimeType(extFromPath(filePath)) || "application/octet-stream",
52
+ });
53
+ }
54
+
55
+ async putStream(
56
+ filePath: string,
57
+ readable: NodeJS.ReadableStream,
58
+ options?: PutStreamOptions,
59
+ ): Promise<void> {
60
+ const chunks: Buffer[] = [];
61
+ for await (const chunk of readable) {
62
+ chunks.push(
63
+ Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string),
64
+ );
65
+ }
66
+ const buf = Buffer.concat(chunks);
67
+ this.#store.set(filePath, {
68
+ content: buf,
69
+ visibility: this.#store.get(filePath)?.visibility ?? "public",
70
+ lastModified: new Date(),
71
+ mimeType:
72
+ options?.contentType ??
73
+ (inferMimeType(extFromPath(filePath)) || "application/octet-stream"),
74
+ });
75
+ }
76
+
77
+ async get(filePath: string): Promise<Buffer | null> {
78
+ const obj = this.#store.get(filePath);
79
+ return obj ? Buffer.from(obj.content) : null;
80
+ }
81
+
82
+ async getStream(filePath: string): Promise<NodeJS.ReadableStream> {
83
+ const obj = this.#store.get(filePath);
84
+ if (!obj) {
85
+ throw new ArchiveError(
86
+ "ARCHIVE_NOT_FOUND",
87
+ `Fake object does not exist at path '${filePath}'`,
88
+ { hint: "put() it first, or verify the test setup." },
89
+ );
90
+ }
91
+ return Readable.from(obj.content);
92
+ }
93
+
94
+ async delete(filePath: string): Promise<boolean> {
95
+ return this.#store.delete(filePath);
96
+ }
97
+
98
+ async exists(filePath: string): Promise<boolean> {
99
+ return this.#store.has(filePath);
100
+ }
101
+
102
+ publicUrl(filePath: string): string {
103
+ return `fake://${filePath}`;
104
+ }
105
+
106
+ async url(filePath: string): Promise<string> {
107
+ const obj = this.#store.get(filePath);
108
+ if (obj?.visibility === "private") return this.getSignedUrl(filePath);
109
+ return this.publicUrl(filePath);
110
+ }
111
+
112
+ getSignedUrl(filePath: string, options?: SignedUrlOptions): string {
113
+ const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
114
+ assertValidExpiry(expiresIn);
115
+ const exp = Math.floor(Date.now() / 1000) + expiresIn;
116
+ const sig = createHash("sha256")
117
+ .update(`${filePath}.${exp}.${FAKE_SECRET}`)
118
+ .digest("hex");
119
+ return `fake://${filePath}?exp=${exp}&sig=${sig}`;
120
+ }
121
+
122
+ async getMetadata(filePath: string): Promise<Metadata> {
123
+ const obj = this.#store.get(filePath);
124
+ if (!obj) {
125
+ throw new ArchiveError(
126
+ "ARCHIVE_NOT_FOUND",
127
+ `Fake object does not exist at path '${filePath}'`,
128
+ { hint: "put() it first, or verify the test setup." },
129
+ );
130
+ }
131
+ // Weak ETag deterministic on content hash — useful for
132
+ // assertion stability in tests.
133
+ const etagBody = createHash("sha1").update(obj.content).digest("hex");
134
+ return {
135
+ size: obj.content.length,
136
+ mimeType: obj.mimeType,
137
+ lastModified: obj.lastModified,
138
+ etag: `W/"${etagBody}"`,
139
+ visibility: obj.visibility,
140
+ };
141
+ }
142
+
143
+ async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
144
+ const obj = this.#store.get(filePath);
145
+ if (!obj) {
146
+ throw new ArchiveError(
147
+ "ARCHIVE_NOT_FOUND",
148
+ `Cannot set visibility — fake object does not exist at path '${filePath}'`,
149
+ { hint: "put() the file before calling setVisibility()." },
150
+ );
151
+ }
152
+ obj.visibility = visibility;
153
+ }
154
+
155
+ async copy(from: string, to: string): Promise<void> {
156
+ const src = this.#store.get(from);
157
+ if (!src) {
158
+ throw new ArchiveError(
159
+ "ARCHIVE_NOT_FOUND",
160
+ `Cannot copy — fake source does not exist at path '${from}'`,
161
+ { hint: "Confirm the source path was put() first." },
162
+ );
163
+ }
164
+ // Default visibility on the new object — matches LocalDriver
165
+ // semantics (AC 4 from Story 43.6).
166
+ this.#store.set(to, {
167
+ content: Buffer.from(src.content),
168
+ visibility: "public",
169
+ lastModified: new Date(),
170
+ mimeType: src.mimeType,
171
+ });
172
+ }
173
+
174
+ async move(from: string, to: string): Promise<void> {
175
+ const src = this.#store.get(from);
176
+ if (!src) {
177
+ throw new ArchiveError(
178
+ "ARCHIVE_NOT_FOUND",
179
+ `Cannot move — fake source does not exist at path '${from}'`,
180
+ { hint: "Confirm the source path was put() first." },
181
+ );
182
+ }
183
+ // Move preserves visibility — identity is preserved.
184
+ this.#store.set(to, { ...src, content: Buffer.from(src.content) });
185
+ this.#store.delete(from);
186
+ }
187
+
188
+ async *list(prefix: string): AsyncIterable<StorageEntry> {
189
+ for (const [path, obj] of this.#store) {
190
+ if (!path.startsWith(prefix)) continue;
191
+ yield { path, size: obj.content.length, lastModified: obj.lastModified };
192
+ }
193
+ }
194
+
195
+ /** Test helper — wipe all state. */
196
+ clear(): void {
197
+ this.#store.clear();
198
+ }
199
+
200
+ /** Alias for `clear()` — exists so the API matches helix's
201
+ * `storage.reset()` forwarder convention (and matches the shape
202
+ * of `FakeMail` / `FakeQueue` / `FakeLogger` / `FakeRelay`). */
203
+ reset(): void {
204
+ this.#store.clear();
205
+ }
206
+
207
+ /** Test helper — snapshot current state as `{ path: content }`.
208
+ * Kept for backwards-compat; new tests should prefer
209
+ * `getStored()` which returns richer entries. */
210
+ dump(): Record<string, Buffer> {
211
+ const out: Record<string, Buffer> = {};
212
+ for (const [path, obj] of this.#store) {
213
+ out[path] = Buffer.from(obj.content);
214
+ }
215
+ return out;
216
+ }
217
+
218
+ /**
219
+ * Defensive snapshot of stored objects, suitable for test
220
+ * assertions. Each entry is a fresh shallow clone so test-side
221
+ * mutation can't bleed back into the internal store.
222
+ */
223
+ getStored(): Array<{
224
+ path: string;
225
+ content: Buffer;
226
+ mimeType: string;
227
+ visibility: Visibility;
228
+ }> {
229
+ const out: Array<{
230
+ path: string;
231
+ content: Buffer;
232
+ mimeType: string;
233
+ visibility: Visibility;
234
+ }> = [];
235
+ for (const [path, obj] of this.#store) {
236
+ out.push({
237
+ path,
238
+ content: Buffer.from(obj.content),
239
+ mimeType: obj.mimeType,
240
+ visibility: obj.visibility,
241
+ });
242
+ }
243
+ return out;
244
+ }
245
+
246
+ assertStored(path: string, predicate?: FakeStoragePredicateArg): void {
247
+ const match = makeStorageMatcher(path, predicate);
248
+ for (const [p, obj] of this.#store) {
249
+ if (match(p, obj)) return;
250
+ }
251
+ throw new Error(
252
+ `storage.assertStored('${path}'${describeStoragePredicate(predicate)}) failed — no captured object matches.\n${describeStorageCaptured(this.#store)}`,
253
+ );
254
+ }
255
+
256
+ assertNotStored(path: string, predicate?: FakeStoragePredicateArg): void {
257
+ const match = makeStorageMatcher(path, predicate);
258
+ for (const [p, obj] of this.#store) {
259
+ if (match(p, obj)) {
260
+ throw new Error(
261
+ `storage.assertNotStored('${path}'${describeStoragePredicate(predicate)}) failed — at least one captured object matches.\n${describeStorageCaptured(this.#store)}`,
262
+ );
263
+ }
264
+ }
265
+ }
266
+ }
267
+
268
+ export interface FakeStoragePredicate {
269
+ /** Substring match against the stored content, viewed as UTF-8.
270
+ * Non-UTF-8 binary payloads (PNG, PDF, ...) will be lossily
271
+ * decoded — for binary content prefer the function-predicate
272
+ * form which receives the raw `Buffer`. */
273
+ contentContaining?: string;
274
+ /** Mime-type match. Comparison is case-insensitive — RFC 2045 §5.1
275
+ * treats media types as case-insensitive, and storage backends
276
+ * often normalise inconsistently. */
277
+ mimeType?: string;
278
+ }
279
+
280
+ export type FakeStoragePredicateArg =
281
+ | FakeStoragePredicate
282
+ | ((entry: { path: string; content: Buffer; mimeType: string }) => boolean);
283
+
284
+ function makeStorageMatcher(
285
+ path: string,
286
+ predicate: FakeStoragePredicateArg | undefined,
287
+ ): (storedPath: string, obj: { content: Buffer; mimeType: string }) => boolean {
288
+ if (typeof predicate === "function") {
289
+ return (p, obj) =>
290
+ p === path &&
291
+ predicate({ path: p, content: obj.content, mimeType: obj.mimeType });
292
+ }
293
+ if (predicate === undefined) {
294
+ return (p) => p === path;
295
+ }
296
+ // Validate the predicate AT CONSTRUCTION, not inside the closure —
297
+ // `for (...) match(...)` would silently never see the throw if the
298
+ // store happens to be empty, hiding the test-fixture mistake.
299
+ if (predicate.contentContaining === "") {
300
+ throw new Error(
301
+ "FakeStorage: `contentContaining` predicate cannot be an empty string — it would match every captured object.",
302
+ );
303
+ }
304
+ const expectedMime = predicate.mimeType?.toLowerCase();
305
+ return (p, obj) => {
306
+ if (p !== path) return false;
307
+ if (
308
+ predicate.contentContaining !== undefined &&
309
+ !obj.content.toString("utf-8").includes(predicate.contentContaining)
310
+ ) {
311
+ return false;
312
+ }
313
+ if (
314
+ expectedMime !== undefined &&
315
+ obj.mimeType.toLowerCase() !== expectedMime
316
+ ) {
317
+ return false;
318
+ }
319
+ return true;
320
+ };
321
+ }
322
+
323
+ function describeStoragePredicate(
324
+ predicate: FakeStoragePredicateArg | undefined,
325
+ ): string {
326
+ if (predicate === undefined) return "";
327
+ if (typeof predicate === "function") return ", <function predicate>";
328
+ if (Object.keys(predicate).length === 0) {
329
+ return ", <empty predicate (path-only)>";
330
+ }
331
+ return `, ${safeStringify(predicate)}`;
332
+ }
333
+
334
+ /** `JSON.stringify` with circular-ref + function-field handling.
335
+ * Functions render as `<function>`, circular refs as `<circular>`,
336
+ * unstringifiable values as `<unstringifiable>` — so an assertion
337
+ * failure message never gets eaten by a JSON throw. */
338
+ function safeStringify(value: unknown): string {
339
+ const seen = new WeakSet<object>();
340
+ try {
341
+ return JSON.stringify(value, (_key, v: unknown) => {
342
+ if (typeof v === "function") return "<function>";
343
+ if (typeof v === "object" && v !== null) {
344
+ if (seen.has(v)) return "<circular>";
345
+ seen.add(v);
346
+ }
347
+ return v;
348
+ });
349
+ } catch {
350
+ return "<unstringifiable>";
351
+ }
352
+ }
353
+
354
+ function describeStorageCaptured(
355
+ store: Map<string, { content: Buffer; mimeType: string }>,
356
+ ): string {
357
+ if (store.size === 0) return "Captured: (none)";
358
+ const lines: string[] = [];
359
+ let i = 0;
360
+ for (const [p, obj] of store) {
361
+ lines.push(
362
+ ` [${i}] path="${p}" size=${obj.content.length} mime="${obj.mimeType}"`,
363
+ );
364
+ i++;
365
+ }
366
+ return `Captured (${store.size}):\n${lines.join("\n")}`;
367
+ }
368
+
369
+ function extFromPath(filePath: string): string {
370
+ const idx = filePath.lastIndexOf(".");
371
+ return idx < 0 ? "" : filePath.slice(idx).toLowerCase();
372
+ }