@c9up/archive 0.1.6 → 0.1.8

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 (46) hide show
  1. package/dist/ArchiveProvider.d.ts +7 -1
  2. package/dist/ArchiveProvider.d.ts.map +1 -1
  3. package/dist/ArchiveProvider.js +35 -9
  4. package/dist/ArchiveProvider.js.map +1 -1
  5. package/dist/DriveManager.d.ts +80 -0
  6. package/dist/DriveManager.d.ts.map +1 -0
  7. package/dist/DriveManager.js +102 -0
  8. package/dist/DriveManager.js.map +1 -0
  9. package/dist/GcsDriver.d.ts +14 -4
  10. package/dist/GcsDriver.d.ts.map +1 -1
  11. package/dist/GcsDriver.js +126 -15
  12. package/dist/GcsDriver.js.map +1 -1
  13. package/dist/S3Driver.d.ts +14 -4
  14. package/dist/S3Driver.d.ts.map +1 -1
  15. package/dist/S3Driver.js +268 -15
  16. package/dist/S3Driver.js.map +1 -1
  17. package/dist/StorageManager.d.ts +124 -18
  18. package/dist/StorageManager.d.ts.map +1 -1
  19. package/dist/StorageManager.js +139 -13
  20. package/dist/StorageManager.js.map +1 -1
  21. package/dist/expiry.d.ts +7 -0
  22. package/dist/expiry.d.ts.map +1 -1
  23. package/dist/expiry.js +47 -0
  24. package/dist/expiry.js.map +1 -1
  25. package/dist/index.d.ts +16 -6
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +13 -4
  28. package/dist/index.js.map +1 -1
  29. package/dist/objects.d.ts +50 -0
  30. package/dist/objects.d.ts.map +1 -0
  31. package/dist/objects.js +77 -0
  32. package/dist/objects.js.map +1 -0
  33. package/dist/testing/FakeStorage.d.ts +43 -4
  34. package/dist/testing/FakeStorage.d.ts.map +1 -1
  35. package/dist/testing/FakeStorage.js +153 -12
  36. package/dist/testing/FakeStorage.js.map +1 -1
  37. package/package.json +2 -1
  38. package/src/ArchiveProvider.ts +53 -12
  39. package/src/DriveManager.ts +151 -0
  40. package/src/GcsDriver.ts +166 -15
  41. package/src/S3Driver.ts +317 -15
  42. package/src/StorageManager.ts +284 -25
  43. package/src/expiry.ts +52 -0
  44. package/src/index.ts +26 -5
  45. package/src/objects.ts +92 -0
  46. package/src/testing/FakeStorage.ts +191 -12
package/src/S3Driver.ts CHANGED
@@ -11,14 +11,22 @@ import { createHash, createHmac } from "node:crypto";
11
11
  import { Readable } from "node:stream";
12
12
  import type { ReadableStream as NodeReadableStream } from "node:stream/web";
13
13
  import { ArchiveError } from "./errors.js";
14
- import { assertValidExpiry, DEFAULT_EXPIRES_IN } from "./expiry.js";
14
+ import {
15
+ assertValidExpiry,
16
+ DEFAULT_EXPIRES_IN,
17
+ parseExpiry,
18
+ } from "./expiry.js";
19
+ import { DriveDirectory, DriveFile } from "./objects.js";
15
20
  import type {
21
+ ListAllOptions,
22
+ ListAllResult,
16
23
  Metadata,
17
24
  PutStreamOptions,
18
25
  SignedUrlOptions,
19
26
  StorageDriver,
20
27
  StorageEntry,
21
28
  Visibility,
29
+ WriteOptions,
22
30
  } from "./StorageManager.js";
23
31
 
24
32
  /** AWS minimum for a non-final multipart part. */
@@ -80,10 +88,31 @@ export class S3Driver implements StorageDriver {
80
88
  this.#endpoint = rawEndpoint.replace(/\/+$/, "");
81
89
  }
82
90
 
83
- async put(filePath: string, content: Buffer | string): Promise<void> {
91
+ async put(
92
+ filePath: string,
93
+ content: Buffer | string,
94
+ options?: WriteOptions,
95
+ ): Promise<void> {
84
96
  const body = typeof content === "string" ? Buffer.from(content) : content;
85
97
  const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
86
- const headers = this.#signRequest({ method: "PUT", key: filePath, body });
98
+ // `x-amz-acl` is signed (extraHeaders) so the requested visibility
99
+ // actually takes effect. content-* metadata headers are kept
100
+ // UNSIGNED — undici may rewrite them for Buffer bodies, which
101
+ // would break a signed value.
102
+ const extraHeaders: Record<string, string> | undefined =
103
+ options?.visibility !== undefined
104
+ ? {
105
+ "x-amz-acl":
106
+ options.visibility === "public" ? "public-read" : "private",
107
+ }
108
+ : undefined;
109
+ const signed = this.#signRequest({
110
+ method: "PUT",
111
+ key: filePath,
112
+ body,
113
+ extraHeaders,
114
+ });
115
+ const headers = { ...signed, ...unsignedMetadataHeaders(options) };
87
116
 
88
117
  const res = await fetch(url, {
89
118
  method: "PUT",
@@ -201,6 +230,23 @@ export class S3Driver implements StorageDriver {
201
230
  return Buffer.from(arrayBuffer);
202
231
  }
203
232
 
233
+ async getBytes(filePath: string): Promise<Uint8Array> {
234
+ const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
235
+ const headers = this.#signRequest({ method: "GET", key: filePath });
236
+ const res = await fetch(url, { method: "GET", headers });
237
+ if (res.status === 404) {
238
+ throw new ArchiveError(
239
+ "ARCHIVE_NOT_FOUND",
240
+ `S3 object does not exist at path '${filePath}'`,
241
+ {
242
+ hint: "Confirm the bucket + key and that the object was put() first.",
243
+ },
244
+ );
245
+ }
246
+ if (!res.ok) throw new Error(`S3 GET failed (${res.status})`);
247
+ return new Uint8Array(await res.arrayBuffer());
248
+ }
249
+
204
250
  async delete(filePath: string): Promise<boolean> {
205
251
  const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}`;
206
252
  const headers = this.#signRequest({ method: "DELETE", key: filePath });
@@ -284,7 +330,34 @@ export class S3Driver implements StorageDriver {
284
330
  // Non-2xx on ACL (e.g. 403 on a bucket without permission) falls
285
331
  // through to `private` — the safer default.
286
332
 
287
- return { size, mimeType, lastModified, etag, visibility };
333
+ return {
334
+ size,
335
+ contentLength: size,
336
+ mimeType,
337
+ contentType: mimeType,
338
+ lastModified,
339
+ etag,
340
+ visibility,
341
+ };
342
+ }
343
+
344
+ async getVisibility(filePath: string): Promise<Visibility> {
345
+ const aclUrl = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?acl`;
346
+ const aclHeaders = this.#signRequest({
347
+ method: "GET",
348
+ key: filePath,
349
+ queryParams: [["acl", ""]],
350
+ });
351
+ const aclRes = await fetch(aclUrl, { method: "GET", headers: aclHeaders });
352
+ if (aclRes.status === 404) {
353
+ throw new ArchiveError(
354
+ "ARCHIVE_NOT_FOUND",
355
+ `S3 object does not exist at path '${filePath}'`,
356
+ { hint: "Confirm the bucket + key." },
357
+ );
358
+ }
359
+ if (aclRes.ok && isPublicAcl(await aclRes.text())) return "public";
360
+ return "private";
288
361
  }
289
362
 
290
363
  async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
@@ -317,7 +390,42 @@ export class S3Driver implements StorageDriver {
317
390
  * - Credentials and expiry live in query params, not headers.
318
391
  */
319
392
  getSignedUrl(filePath: string, options?: SignedUrlOptions): string {
320
- const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
393
+ // `response-content-*` overrides are attached as extra query params;
394
+ // they participate in the signature via the canonical query string.
395
+ const responseParams: Array<[string, string]> = [];
396
+ if (options?.contentType) {
397
+ responseParams.push(["response-content-type", options.contentType]);
398
+ }
399
+ if (options?.contentDisposition) {
400
+ responseParams.push([
401
+ "response-content-disposition",
402
+ options.contentDisposition,
403
+ ]);
404
+ }
405
+ return this.#presign("GET", filePath, options, responseParams);
406
+ }
407
+
408
+ /**
409
+ * Presigned PUT URL for direct-to-S3 uploads. AdonisJS Drive parity.
410
+ * A supplied `contentType` is baked into the signature as a
411
+ * `Content-Type` header, so the client MUST send the same value.
412
+ */
413
+ getSignedUploadUrl(filePath: string, options?: SignedUrlOptions): string {
414
+ return this.#presign("PUT", filePath, options, []);
415
+ }
416
+
417
+ /**
418
+ * Shared SigV4 query-parameter presigner for GET (read) and PUT
419
+ * (upload) URLs. Extracted so both flows share one canonicalisation
420
+ * path — no copy-paste drift.
421
+ */
422
+ #presign(
423
+ method: "GET" | "PUT",
424
+ filePath: string,
425
+ options: SignedUrlOptions | undefined,
426
+ extraQueryParams: Array<[string, string]>,
427
+ ): string {
428
+ const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
321
429
  assertValidExpiry(expiresIn);
322
430
 
323
431
  const dateStamp = amzDateNow();
@@ -327,6 +435,11 @@ export class S3Driver implements StorageDriver {
327
435
  const scope = `${shortDate}/${region}/${service}/aws4_request`;
328
436
  const credential = `${this.#config.accessKeyId}/${scope}`;
329
437
 
438
+ // A PUT upload URL that pins Content-Type must sign that header.
439
+ const signContentType = method === "PUT" ? options?.contentType : undefined;
440
+ const signedHeaderNames = signContentType ? "content-type;host" : "host";
441
+ const host = new URL(this.#endpoint).host;
442
+
330
443
  // Canonical query params — names MUST be URI-encoded and the
331
444
  // whole string sorted by key before signing. Every `X-Amz-*`
332
445
  // key is already safe, so we only URI-encode values.
@@ -335,21 +448,24 @@ export class S3Driver implements StorageDriver {
335
448
  ["X-Amz-Credential", credential],
336
449
  ["X-Amz-Date", dateStamp],
337
450
  ["X-Amz-Expires", String(expiresIn)],
338
- ["X-Amz-SignedHeaders", "host"],
451
+ ["X-Amz-SignedHeaders", signedHeaderNames],
452
+ ...extraQueryParams,
339
453
  ];
340
454
  const canonicalQs = queryParams
341
455
  .slice()
342
456
  .sort((a, b) => (a[0] < b[0] ? -1 : 1))
343
- .map(([k, v]) => `${k}=${s3StrictEncode(v)}`)
457
+ .map(([k, v]) => `${s3StrictEncode(k)}=${s3StrictEncode(v)}`)
344
458
  .join("&");
345
459
 
346
- const host = new URL(this.#endpoint).host;
460
+ const canonicalHeaders = signContentType
461
+ ? `content-type:${signContentType}\nhost:${host}\n`
462
+ : `host:${host}\n`;
347
463
  const canonicalRequest = [
348
- "GET",
464
+ method,
349
465
  `/${this.#config.bucket}/${s3EncodeKey(filePath)}`,
350
466
  canonicalQs,
351
- `host:${host}\n`,
352
- "host",
467
+ canonicalHeaders,
468
+ signedHeaderNames,
353
469
  "UNSIGNED-PAYLOAD",
354
470
  ].join("\n");
355
471
 
@@ -368,13 +484,20 @@ export class S3Driver implements StorageDriver {
368
484
  return `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(filePath)}?${canonicalQs}&X-Amz-Signature=${signature}`;
369
485
  }
370
486
 
371
- async copy(from: string, to: string): Promise<void> {
487
+ async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
372
488
  const url = `${this.#endpoint}/${this.#config.bucket}/${s3EncodeKey(to)}`;
373
489
  const copySource = `/${this.#config.bucket}/${s3EncodeKey(from)}`;
490
+ const extraHeaders: Record<string, string> = {
491
+ "x-amz-copy-source": copySource,
492
+ };
493
+ if (options?.visibility !== undefined) {
494
+ extraHeaders["x-amz-acl"] =
495
+ options.visibility === "public" ? "public-read" : "private";
496
+ }
374
497
  const headers = this.#signRequest({
375
498
  method: "PUT",
376
499
  key: to,
377
- extraHeaders: { "x-amz-copy-source": copySource },
500
+ extraHeaders,
378
501
  });
379
502
  const res = await fetch(url, { method: "PUT", headers });
380
503
  if (!res.ok) {
@@ -397,13 +520,167 @@ export class S3Driver implements StorageDriver {
397
520
  }
398
521
  }
399
522
 
400
- async move(from: string, to: string): Promise<void> {
523
+ async move(from: string, to: string, options?: WriteOptions): Promise<void> {
401
524
  // Non-atomic: copy then delete. An observer between the two
402
525
  // steps sees both objects — documented in the interface JSDoc.
403
- await this.copy(from, to);
526
+ await this.copy(from, to, options);
404
527
  await this.delete(from);
405
528
  }
406
529
 
530
+ async deleteAll(prefix: string): Promise<void> {
531
+ // List one page at a time and batch-delete (up to 1000 keys per
532
+ // DeleteObjects call) until the bucket is drained of the prefix.
533
+ let continuationToken: string | undefined;
534
+ do {
535
+ const qp: Array<[string, string]> = [
536
+ ["list-type", "2"],
537
+ ["prefix", prefix],
538
+ ];
539
+ if (continuationToken) qp.push(["continuation-token", continuationToken]);
540
+ const canonicalQs = qp
541
+ .slice()
542
+ .sort((a, b) => (a[0] < b[0] ? -1 : 1))
543
+ .map(([k, v]) => `${k}=${s3StrictEncode(v)}`)
544
+ .join("&");
545
+ const listUrl = `${this.#endpoint}/${this.#config.bucket}?${canonicalQs}`;
546
+ const listHeaders = this.#signRequest({
547
+ method: "GET",
548
+ key: "",
549
+ queryParams: qp,
550
+ });
551
+ const listRes = await fetch(listUrl, {
552
+ method: "GET",
553
+ headers: listHeaders,
554
+ });
555
+ if (!listRes.ok) {
556
+ throw new Error(
557
+ `S3 LIST failed (${listRes.status}): ${await listRes.text()}`,
558
+ );
559
+ }
560
+ const xml = await listRes.text();
561
+ const keys: string[] = [];
562
+ const keyRe =
563
+ /<Contents>[\s\S]*?<Key>([^<]+)<\/Key>[\s\S]*?<\/Contents>/g;
564
+ let m: RegExpExecArray | null = keyRe.exec(xml);
565
+ while (m !== null) {
566
+ if (m[1] !== undefined) keys.push(m[1]);
567
+ m = keyRe.exec(xml);
568
+ }
569
+ if (keys.length > 0) await this.#deleteObjects(keys);
570
+ const truncated = /<IsTruncated>true<\/IsTruncated>/i.test(xml);
571
+ const tokenMatch = xml.match(
572
+ /<NextContinuationToken>([^<]+)<\/NextContinuationToken>/,
573
+ );
574
+ continuationToken = truncated && tokenMatch ? tokenMatch[1] : undefined;
575
+ } while (continuationToken);
576
+ }
577
+
578
+ /** Batch DeleteObjects (`POST ?delete`). S3 requires a `Content-MD5`. */
579
+ async #deleteObjects(keys: string[]): Promise<void> {
580
+ const body = Buffer.from(
581
+ `<Delete>${keys
582
+ .map((k) => `<Object><Key>${xmlEscape(k)}</Key></Object>`)
583
+ .join("")}<Quiet>true</Quiet></Delete>`,
584
+ );
585
+ const contentMd5 = createHash("md5").update(body).digest("base64");
586
+ const url = `${this.#endpoint}/${this.#config.bucket}?delete`;
587
+ const headers = this.#signRequest({
588
+ method: "POST",
589
+ key: "",
590
+ body,
591
+ queryParams: [["delete", ""]],
592
+ extraHeaders: { "content-md5": contentMd5 },
593
+ });
594
+ const res = await fetch(url, {
595
+ method: "POST",
596
+ headers,
597
+ body: body as BodyInit,
598
+ });
599
+ if (!res.ok) {
600
+ throw new Error(
601
+ `S3 DeleteObjects failed (${res.status}): ${await res.text()}`,
602
+ );
603
+ }
604
+ }
605
+
606
+ async listAll(
607
+ prefix: string,
608
+ options?: ListAllOptions,
609
+ ): Promise<ListAllResult> {
610
+ const recursive = options?.recursive ?? false;
611
+ const normalizedPrefix =
612
+ prefix === "" || prefix === "/"
613
+ ? ""
614
+ : !recursive && !prefix.endsWith("/")
615
+ ? `${prefix}/`
616
+ : prefix;
617
+ const qp: Array<[string, string]> = [
618
+ ["list-type", "2"],
619
+ ["prefix", normalizedPrefix],
620
+ ];
621
+ if (!recursive) qp.push(["delimiter", "/"]);
622
+ if (options?.paginationToken) {
623
+ qp.push(["continuation-token", options.paginationToken]);
624
+ }
625
+ const canonicalQs = qp
626
+ .slice()
627
+ .sort((a, b) => (a[0] < b[0] ? -1 : 1))
628
+ .map(([k, v]) => `${k}=${s3StrictEncode(v)}`)
629
+ .join("&");
630
+ const url = `${this.#endpoint}/${this.#config.bucket}?${canonicalQs}`;
631
+ const headers = this.#signRequest({
632
+ method: "GET",
633
+ key: "",
634
+ queryParams: qp,
635
+ });
636
+ const res = await fetch(url, { method: "GET", headers });
637
+ if (!res.ok) {
638
+ throw new Error(`S3 LIST failed (${res.status}): ${await res.text()}`);
639
+ }
640
+ const xml = await res.text();
641
+ const objects: Array<DriveFile | DriveDirectory> = [];
642
+ // Directories (CommonPrefixes) first, then files (Contents).
643
+ const prefixRe =
644
+ /<CommonPrefixes>[\s\S]*?<Prefix>([^<]+)<\/Prefix>[\s\S]*?<\/CommonPrefixes>/g;
645
+ let pm: RegExpExecArray | null = prefixRe.exec(xml);
646
+ while (pm !== null) {
647
+ if (pm[1] !== undefined) {
648
+ objects.push(new DriveDirectory(pm[1].replace(/\/$/, "")));
649
+ }
650
+ pm = prefixRe.exec(xml);
651
+ }
652
+ const blockRe = /<Contents>([\s\S]*?)<\/Contents>/g;
653
+ let bm: RegExpExecArray | null = blockRe.exec(xml);
654
+ while (bm !== null) {
655
+ const block = bm[1] ?? "";
656
+ const key = block.match(/<Key>([^<]+)<\/Key>/)?.[1] ?? "";
657
+ const sizeRaw = block.match(/<Size>([^<]+)<\/Size>/)?.[1] ?? "0";
658
+ const lm = block.match(/<LastModified>([^<]+)<\/LastModified>/)?.[1];
659
+ const size = Number.parseInt(sizeRaw, 10);
660
+ objects.push(
661
+ new DriveFile(key, this, {
662
+ size,
663
+ contentLength: size,
664
+ mimeType: "application/octet-stream",
665
+ contentType: "application/octet-stream",
666
+ lastModified: lm ? new Date(lm) : new Date(0),
667
+ etag:
668
+ block.match(/<ETag>([^<]+)<\/ETag>/)?.[1]?.replace(/"/g, "") ?? "",
669
+ visibility: "private",
670
+ }),
671
+ );
672
+ bm = blockRe.exec(xml);
673
+ }
674
+ const truncated = /<IsTruncated>true<\/IsTruncated>/i.test(xml);
675
+ const tokenMatch = xml.match(
676
+ /<NextContinuationToken>([^<]+)<\/NextContinuationToken>/,
677
+ );
678
+ return {
679
+ paginationToken: truncated && tokenMatch ? tokenMatch[1] : undefined,
680
+ objects,
681
+ };
682
+ }
683
+
407
684
  async *list(prefix: string): AsyncIterable<StorageEntry> {
408
685
  let continuationToken: string | undefined;
409
686
  do {
@@ -695,6 +972,31 @@ function amzDateNow(): string {
695
972
  return `${new Date().toISOString().replace(/[-:]/g, "").split(".")[0]}Z`;
696
973
  }
697
974
 
975
+ /**
976
+ * Build the UNSIGNED content-metadata headers from {@link WriteOptions}.
977
+ * Kept unsigned because undici may rewrite them for Buffer bodies, which
978
+ * would invalidate a signed value (`x-amz-acl` is signed separately).
979
+ */
980
+ function unsignedMetadataHeaders(
981
+ options: WriteOptions | undefined,
982
+ ): Record<string, string> {
983
+ const headers: Record<string, string> = {};
984
+ if (options?.contentType) headers["content-type"] = options.contentType;
985
+ if (options?.cacheControl) headers["cache-control"] = options.cacheControl;
986
+ if (options?.contentDisposition) {
987
+ headers["content-disposition"] = options.contentDisposition;
988
+ }
989
+ return headers;
990
+ }
991
+
992
+ /** Minimal XML text escaping for object keys inside a DeleteObjects body. */
993
+ function xmlEscape(value: string): string {
994
+ return value
995
+ .replace(/&/g, "&amp;")
996
+ .replace(/</g, "&lt;")
997
+ .replace(/>/g, "&gt;");
998
+ }
999
+
698
1000
  /**
699
1001
  * Drain a readable into a single Buffer, capped at `maxBytes`. Throws
700
1002
  * if the stream yields more than that — caller declared a contentLength