@c9up/archive 0.1.14 → 0.1.16

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.
@@ -6,6 +6,7 @@
6
6
 
7
7
  import { createHash, createHmac } from "node:crypto";
8
8
  import * as fs from "node:fs";
9
+ import * as fsp from "node:fs/promises";
9
10
  import * as path from "node:path";
10
11
  import { pipeline } from "node:stream/promises";
11
12
  import * as url from "node:url";
@@ -265,6 +266,14 @@ export class LocalDriver implements StorageDriver {
265
266
  #root: string;
266
267
  #signingSecret: string | null;
267
268
 
269
+ /**
270
+ * The only synchronous filesystem access left in this driver, and the only
271
+ * one that cannot be anything else: a constructor cannot await. It runs
272
+ * once, at boot, before the server is serving. Every method below is
273
+ * asynchronous — they used to be async signatures over `writeFileSync` /
274
+ * `readFileSync`, so a large upload or download stalled every other
275
+ * request in the process for its whole duration.
276
+ */
268
277
  constructor(root: string, options?: LocalDriverOptions) {
269
278
  const resolved = path.resolve(root);
270
279
  if (!fs.existsSync(resolved)) {
@@ -292,16 +301,16 @@ export class LocalDriver implements StorageDriver {
292
301
  }
293
302
 
294
303
  /**
295
- * Resolve and validate a file path — prevents traversal outside
296
- * the root, INCLUDING via symlinks planted inside the root.
304
+ * The half of the guard that touches nothing: control characters and
305
+ * lexical containment.
297
306
  *
298
- * For existing files the check walks `fs.realpathSync(full)` to
299
- * defeat symlink redirection. For new writes (target doesn't exist
300
- * yet) we walk the nearest existing ancestor via `realpathSync` so
301
- * an attacker who planted a symlink at `<root>/evil -> /etc`
302
- * cannot redirect a put through it.
307
+ * Split out because `getSignedUrl` is synchronous in the driver contract
308
+ * and cannot await the symlink walk. Keeping ONE implementation of each
309
+ * half — rather than a sync copy of the whole check beside an async one —
310
+ * is what stops the two from drifting apart, which for a containment guard
311
+ * is the failure that matters.
303
312
  */
304
- #safePath(filePath: string): string {
313
+ #lexicalPath(filePath: string): string {
305
314
  // Reject control chars that would smuggle HMAC delimiters or
306
315
  // confuse path handling. `\n` (10) is the signing payload
307
316
  // separator — a filename containing `\n` could otherwise forge
@@ -315,30 +324,50 @@ export class LocalDriver implements StorageDriver {
315
324
  }
316
325
  }
317
326
  const full = path.resolve(this.#root, filePath);
318
- // Lexical guard first — cheap and covers the `..` case.
327
+ // Lexical guard — cheap and covers the `..` case.
319
328
  if (!full.startsWith(this.#root + path.sep) && full !== this.#root) {
320
329
  throw new Error(
321
330
  `Path traversal blocked: '${filePath}' resolves outside storage root`,
322
331
  );
323
332
  }
333
+ return full;
334
+ }
335
+
336
+ /**
337
+ * Resolve and validate a file path — prevents traversal outside
338
+ * the root, INCLUDING via symlinks planted inside the root.
339
+ *
340
+ * For existing files the check walks `realpath(full)` to defeat symlink
341
+ * redirection. For new writes (target doesn't exist yet) we walk the
342
+ * nearest existing ancestor so an attacker who planted a symlink at
343
+ * `<root>/evil -> /etc` cannot redirect a put through it.
344
+ */
345
+ async #safePath(filePath: string): Promise<string> {
346
+ const full = this.#lexicalPath(filePath);
324
347
  // Realpath guard — walk up to the nearest existing ancestor and
325
348
  // confirm its canonical form is still under root.
326
349
  let probe = full;
327
- while (!fs.existsSync(probe)) {
328
- const parent = path.dirname(probe);
329
- if (parent === probe) break;
330
- probe = parent;
331
- }
332
- const realProbe = fs.realpathSync(probe);
333
- if (
334
- !realProbe.startsWith(this.#root + path.sep) &&
335
- realProbe !== this.#root
336
- ) {
337
- throw new Error(
338
- `Path traversal blocked: '${filePath}' resolves outside storage root via symlink`,
339
- );
350
+ for (;;) {
351
+ try {
352
+ const realProbe = await fsp.realpath(probe);
353
+ if (
354
+ !realProbe.startsWith(this.#root + path.sep) &&
355
+ realProbe !== this.#root
356
+ ) {
357
+ throw new Error(
358
+ `Path traversal blocked: '${filePath}' resolves outside storage root via symlink`,
359
+ );
360
+ }
361
+ return full;
362
+ } catch (err) {
363
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
364
+ const parent = path.dirname(probe);
365
+ // The root itself is canonicalised at construction, so the walk
366
+ // always terminates at something that resolves.
367
+ if (parent === probe) return full;
368
+ probe = parent;
369
+ }
340
370
  }
341
- return full;
342
371
  }
343
372
 
344
373
  async put(
@@ -346,12 +375,9 @@ export class LocalDriver implements StorageDriver {
346
375
  content: Buffer | string,
347
376
  options?: WriteOptions,
348
377
  ): Promise<void> {
349
- const full = this.#safePath(filePath);
350
- const dir = path.dirname(full);
351
- if (!fs.existsSync(dir)) {
352
- fs.mkdirSync(dir, { recursive: true });
353
- }
354
- fs.writeFileSync(full, content);
378
+ const full = await this.#safePath(filePath);
379
+ await fsp.mkdir(path.dirname(full), { recursive: true });
380
+ await fsp.writeFile(full, content);
355
381
  // Only `visibility` has a filesystem-equivalent (the sidecar).
356
382
  // contentType/cacheControl/... have no local meaning.
357
383
  if (options?.visibility !== undefined) {
@@ -378,25 +404,28 @@ export class LocalDriver implements StorageDriver {
378
404
  // getMetadata) and contentLength (FS knows its own size).
379
405
  _options?: PutStreamOptions,
380
406
  ): Promise<void> {
381
- const full = this.#safePath(filePath);
382
- const dir = path.dirname(full);
383
- if (!fs.existsSync(dir)) {
384
- fs.mkdirSync(dir, { recursive: true });
385
- }
407
+ const full = await this.#safePath(filePath);
408
+ await fsp.mkdir(path.dirname(full), { recursive: true });
386
409
  // `pipeline` propagates errors and destroys the write target on
387
410
  // failure — no manual cleanup needed.
388
411
  await pipeline(readable, fs.createWriteStream(full));
389
412
  }
390
413
 
391
414
  async get(filePath: string): Promise<Buffer | null> {
392
- const full = this.#safePath(filePath);
393
- if (!fs.existsSync(full)) return null;
394
- return fs.readFileSync(full);
415
+ const full = await this.#safePath(filePath);
416
+ try {
417
+ return await fsp.readFile(full);
418
+ } catch (err) {
419
+ // One syscall instead of exists-then-read: the pair also answered
420
+ // `null` for a file that was deleted between the two.
421
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
422
+ throw err;
423
+ }
395
424
  }
396
425
 
397
426
  async getStream(filePath: string): Promise<NodeJS.ReadableStream> {
398
- const full = this.#safePath(filePath);
399
- if (!fs.existsSync(full)) {
427
+ const full = await this.#safePath(filePath);
428
+ if (!(await exists(full))) {
400
429
  throw new ArchiveError(
401
430
  "E_ARCHIVE_NOT_FOUND",
402
431
  `File does not exist at path '${filePath}'`,
@@ -407,16 +436,20 @@ export class LocalDriver implements StorageDriver {
407
436
  }
408
437
 
409
438
  async delete(filePath: string): Promise<boolean> {
410
- const full = this.#safePath(filePath);
411
- if (!fs.existsSync(full)) return false;
412
- fs.unlinkSync(full);
439
+ const full = await this.#safePath(filePath);
440
+ try {
441
+ await fsp.unlink(full);
442
+ } catch (err) {
443
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
444
+ throw err;
445
+ }
413
446
  // Sidecar cleanup is best-effort. The main file is already gone
414
447
  // — any sidecar failure (ENOENT, EACCES, EPERM) would corrupt
415
448
  // the `delete` contract if we threw here (caller would see a
416
449
  // rejected Promise AFTER the file was already deleted).
417
450
  const sidecar = full + VISIBILITY_SIDECAR_SUFFIX;
418
451
  try {
419
- fs.unlinkSync(sidecar);
452
+ await fsp.unlink(sidecar);
420
453
  } catch {
421
454
  // swallow: cleanup is best-effort.
422
455
  }
@@ -427,7 +460,7 @@ export class LocalDriver implements StorageDriver {
427
460
  // Sidecars are an implementation detail — pretend they don't
428
461
  // exist from the public API's point of view.
429
462
  if (filePath.endsWith(VISIBILITY_SIDECAR_SUFFIX)) return false;
430
- return fs.existsSync(this.#safePath(filePath));
463
+ return exists(await this.#safePath(filePath));
431
464
  }
432
465
 
433
466
  publicUrl(filePath: string): string {
@@ -443,16 +476,16 @@ export class LocalDriver implements StorageDriver {
443
476
  }
444
477
 
445
478
  async url(filePath: string): Promise<string> {
446
- const visibility = this.#readVisibility(filePath);
479
+ const visibility = await this.#readVisibility(filePath);
447
480
  if (visibility === "public") return this.publicUrl(filePath);
448
481
  return this.getSignedUrl(filePath);
449
482
  }
450
483
 
451
484
  async getMetadata(filePath: string): Promise<Metadata> {
452
- const full = this.#safePath(filePath);
485
+ const full = await this.#safePath(filePath);
453
486
  let stat: fs.Stats;
454
487
  try {
455
- stat = fs.statSync(full);
488
+ stat = await fsp.stat(full);
456
489
  } catch (err) {
457
490
  if ((err as NodeJS.ErrnoException).code === "ENOENT") {
458
491
  throw new ArchiveError(
@@ -478,7 +511,7 @@ export class LocalDriver implements StorageDriver {
478
511
  contentType: mimeType,
479
512
  lastModified: stat.mtime,
480
513
  etag: `W/"${etagBody}"`,
481
- visibility: this.#readVisibility(filePath),
514
+ visibility: await this.#readVisibility(filePath),
482
515
  };
483
516
  }
484
517
 
@@ -487,8 +520,8 @@ export class LocalDriver implements StorageDriver {
487
520
  }
488
521
 
489
522
  async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
490
- const full = this.#safePath(filePath);
491
- if (!fs.existsSync(full)) {
523
+ const full = await this.#safePath(filePath);
524
+ if (!(await exists(full))) {
492
525
  throw new ArchiveError(
493
526
  "E_ARCHIVE_NOT_FOUND",
494
527
  `Cannot set visibility — file does not exist at path '${filePath}'`,
@@ -496,7 +529,7 @@ export class LocalDriver implements StorageDriver {
496
529
  );
497
530
  }
498
531
  const sidecar = full + VISIBILITY_SIDECAR_SUFFIX;
499
- fs.writeFileSync(sidecar, JSON.stringify({ visibility }), { flag: "w" });
532
+ await fsp.writeFile(sidecar, JSON.stringify({ visibility }), { flag: "w" });
500
533
  }
501
534
 
502
535
  /**
@@ -508,13 +541,16 @@ export class LocalDriver implements StorageDriver {
508
541
  * blip into a private→public downgrade for an existing private file.
509
542
  * Refuse to serve undetermined visibility instead.
510
543
  */
511
- #readVisibility(filePath: string): Visibility {
512
- const sidecar = this.#safePath(filePath) + VISIBILITY_SIDECAR_SUFFIX;
513
- if (!fs.existsSync(sidecar)) return "public";
544
+ async #readVisibility(filePath: string): Promise<Visibility> {
545
+ const sidecar =
546
+ (await this.#safePath(filePath)) + VISIBILITY_SIDECAR_SUFFIX;
514
547
  let raw: string;
515
548
  try {
516
- raw = fs.readFileSync(sidecar, "utf8");
549
+ raw = await fsp.readFile(sidecar, "utf8");
517
550
  } catch (err) {
551
+ // Absent sidecar is the documented default, and it is the common
552
+ // case: one syscall answers both that and a real read failure.
553
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return "public";
518
554
  throw new ArchiveError(
519
555
  "E_ARCHIVE_VISIBILITY_CORRUPT",
520
556
  `Failed to read visibility sidecar for '${filePath}' (${(err as NodeJS.ErrnoException).code ?? "I/O error"}); refusing to default to 'public'.`,
@@ -535,14 +571,38 @@ export class LocalDriver implements StorageDriver {
535
571
  },
536
572
  );
537
573
  }
538
- return parsed.visibility === "private" ? "private" : "public";
574
+ // Fail CLOSED on anything that is not exactly one of the two values.
575
+ //
576
+ // `=== "private" ? "private" : "public"` treated every other input as
577
+ // public, so a sidecar holding `{}`, `{"visibility":"PRIVATE"}` or a
578
+ // truncated write silently downgraded a private file — `url()` then
579
+ // handed out `/storage/<path>` instead of a signed URL. The doc comment
580
+ // above already promised this for unparseable JSON; a JSON document
581
+ // that parses and says nothing usable is the same situation.
582
+ if (parsed.visibility === "private" || parsed.visibility === "public") {
583
+ return parsed.visibility;
584
+ }
585
+ throw new ArchiveError(
586
+ "E_ARCHIVE_VISIBILITY_CORRUPT",
587
+ `Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(parsed.visibility)}); refusing to default to 'public'.`,
588
+ {
589
+ hint: "Delete the sidecar file and re-apply visibility via setVisibility().",
590
+ },
591
+ );
539
592
  }
540
593
 
541
594
  getSignedUrl(filePath: string, options?: SignedUrlOptions): string {
542
595
  // Fail fast on unsafe paths instead of producing a signed URL that
543
596
  // can never be served — `storage.get()` would reject it later via
544
597
  // `#safePath`, but signing-time errors are easier to diagnose.
545
- this.#safePath(filePath);
598
+ //
599
+ // The lexical half only: this method is synchronous in the driver
600
+ // contract and cannot await the symlink walk. Nothing is lost, because
601
+ // signing a URL reads no file — the read it leads to goes through the
602
+ // full check. What must NOT be skipped here is the control-character
603
+ // rejection, since `\n` is this signature's own payload separator, and
604
+ // `#lexicalPath` is where that lives.
605
+ this.#lexicalPath(filePath);
546
606
  const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
547
607
  assertValidExpiry(expiresIn);
548
608
  const secret = this.#signingSecret;
@@ -588,18 +648,17 @@ export class LocalDriver implements StorageDriver {
588
648
  }
589
649
 
590
650
  async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
591
- const fromFull = this.#safePath(from);
592
- const toFull = this.#safePath(to);
593
- if (!fs.existsSync(fromFull)) {
651
+ const fromFull = await this.#safePath(from);
652
+ const toFull = await this.#safePath(to);
653
+ if (!(await exists(fromFull))) {
594
654
  throw new ArchiveError(
595
655
  "E_ARCHIVE_NOT_FOUND",
596
656
  `Cannot copy — source does not exist at path '${from}'`,
597
657
  { hint: "Confirm the source path was put() first." },
598
658
  );
599
659
  }
600
- const dir = path.dirname(toFull);
601
- if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
602
- fs.copyFileSync(fromFull, toFull);
660
+ await fsp.mkdir(path.dirname(toFull), { recursive: true });
661
+ await fsp.copyFile(fromFull, toFull);
603
662
  // Intentionally do NOT copy the visibility sidecar — new object
604
663
  // takes default visibility unless the caller asks otherwise.
605
664
  if (options?.visibility !== undefined) {
@@ -608,9 +667,9 @@ export class LocalDriver implements StorageDriver {
608
667
  }
609
668
 
610
669
  async move(from: string, to: string, options?: WriteOptions): Promise<void> {
611
- const fromFull = this.#safePath(from);
612
- const toFull = this.#safePath(to);
613
- if (!fs.existsSync(fromFull)) {
670
+ const fromFull = await this.#safePath(from);
671
+ const toFull = await this.#safePath(to);
672
+ if (!(await exists(fromFull))) {
614
673
  throw new ArchiveError(
615
674
  "E_ARCHIVE_NOT_FOUND",
616
675
  `Cannot move — source does not exist at path '${from}'`,
@@ -624,20 +683,19 @@ export class LocalDriver implements StorageDriver {
624
683
  // corruption, which surfaces here BEFORE we mutate anything.
625
684
  const fromSidecar = fromFull + VISIBILITY_SIDECAR_SUFFIX;
626
685
  const toSidecar = toFull + VISIBILITY_SIDECAR_SUFFIX;
627
- const capturedVisibility: Visibility | undefined = fs.existsSync(
686
+ const capturedVisibility: Visibility | undefined = (await exists(
628
687
  fromSidecar,
629
- )
630
- ? this.#readVisibility(from)
688
+ ))
689
+ ? await this.#readVisibility(from)
631
690
  : undefined;
632
- const dir = path.dirname(toFull);
633
- if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
691
+ await fsp.mkdir(path.dirname(toFull), { recursive: true });
634
692
  try {
635
- fs.renameSync(fromFull, toFull);
693
+ await fsp.rename(fromFull, toFull);
636
694
  } catch (err) {
637
695
  // Cross-device rename — fall back to copy+unlink.
638
696
  if ((err as NodeJS.ErrnoException).code === "EXDEV") {
639
- fs.copyFileSync(fromFull, toFull);
640
- fs.unlinkSync(fromFull);
697
+ await fsp.copyFile(fromFull, toFull);
698
+ await fsp.unlink(fromFull);
641
699
  } else {
642
700
  throw err;
643
701
  }
@@ -648,7 +706,7 @@ export class LocalDriver implements StorageDriver {
648
706
  // Public is the default, so an absent source sidecar means no work.
649
707
  if (capturedVisibility !== undefined) {
650
708
  try {
651
- fs.writeFileSync(
709
+ await fsp.writeFile(
652
710
  toSidecar,
653
711
  JSON.stringify({ visibility: capturedVisibility }),
654
712
  { flag: "w" },
@@ -665,12 +723,10 @@ export class LocalDriver implements StorageDriver {
665
723
  // Best-effort cleanup of the source sidecar — visibility is already
666
724
  // preserved on the target side. A failure here leaves a stale
667
725
  // sidecar pointing at the now-missing source file; benign.
668
- if (fs.existsSync(fromSidecar)) {
669
- try {
670
- fs.unlinkSync(fromSidecar);
671
- } catch {
672
- // benign — source dir may be cleaned up by later operations.
673
- }
726
+ try {
727
+ await fsp.unlink(fromSidecar);
728
+ } catch {
729
+ // benign — source dir may be cleaned up by later operations.
674
730
  }
675
731
  }
676
732
  // An explicit visibility override wins over the preserved value.
@@ -691,12 +747,12 @@ export class LocalDriver implements StorageDriver {
691
747
  }
692
748
  // Prune the prefix directory itself when it is now empty, mirroring
693
749
  // flydrive's "the folder is deleted" behaviour. Best-effort.
694
- const dir = this.#safePath(prefix);
695
- if (dir !== this.#root && fs.existsSync(dir)) {
750
+ const dir = await this.#safePath(prefix);
751
+ if (dir !== this.#root) {
696
752
  try {
697
- const stat = fs.statSync(dir);
698
- if (stat.isDirectory() && fs.readdirSync(dir).length === 0) {
699
- fs.rmdirSync(dir);
753
+ const stat = await fsp.stat(dir);
754
+ if (stat.isDirectory() && (await fsp.readdir(dir)).length === 0) {
755
+ await fsp.rmdir(dir);
700
756
  }
701
757
  } catch {
702
758
  // benign — leave non-empty / vanished dirs alone.
@@ -719,7 +775,9 @@ export class LocalDriver implements StorageDriver {
719
775
  : `${prefix}/`;
720
776
  for await (const entry of this.list(normalizedPrefix)) {
721
777
  if (recursive) {
722
- files.push(new DriveFile(entry.path, this, this.#entryMetadata(entry)));
778
+ files.push(
779
+ new DriveFile(entry.path, this, await this.#entryMetadata(entry)),
780
+ );
723
781
  continue;
724
782
  }
725
783
  // Non-recursive: collapse anything below the immediate level
@@ -727,7 +785,9 @@ export class LocalDriver implements StorageDriver {
727
785
  const rest = entry.path.slice(normalizedPrefix.length);
728
786
  const slash = rest.indexOf("/");
729
787
  if (slash === -1) {
730
- files.push(new DriveFile(entry.path, this, this.#entryMetadata(entry)));
788
+ files.push(
789
+ new DriveFile(entry.path, this, await this.#entryMetadata(entry)),
790
+ );
731
791
  } else {
732
792
  const dirPrefix = normalizedPrefix + rest.slice(0, slash);
733
793
  if (!directories.has(dirPrefix)) {
@@ -739,7 +799,7 @@ export class LocalDriver implements StorageDriver {
739
799
  }
740
800
 
741
801
  /** Build a metadata snapshot from a cheap `list()` entry (no extra stat). */
742
- #entryMetadata(entry: StorageEntry): Metadata {
802
+ async #entryMetadata(entry: StorageEntry): Promise<Metadata> {
743
803
  const mimeType = inferMimeType(path.extname(entry.path).toLowerCase());
744
804
  return {
745
805
  size: entry.size,
@@ -748,19 +808,24 @@ export class LocalDriver implements StorageDriver {
748
808
  contentType: mimeType,
749
809
  lastModified: entry.lastModified,
750
810
  etag: "",
751
- visibility: this.#readVisibility(entry.path),
811
+ visibility: await this.#readVisibility(entry.path),
752
812
  };
753
813
  }
754
814
 
755
815
  async *list(prefix: string): AsyncIterable<StorageEntry> {
756
- if (!fs.existsSync(this.#root)) return;
757
- // `recursive: true` on readdirSync gives us every descendant in
758
- // one call; `withFileTypes: true` lets us skip directories and
759
- // inspect each entry without a follow-up stat for type.
760
- const entries = fs.readdirSync(this.#root, {
761
- recursive: true,
762
- withFileTypes: true,
763
- });
816
+ // `recursive: true` gives us every descendant in one call;
817
+ // `withFileTypes: true` lets us skip directories and inspect each
818
+ // entry without a follow-up stat for type.
819
+ let entries: fs.Dirent[];
820
+ try {
821
+ entries = await fsp.readdir(this.#root, {
822
+ recursive: true,
823
+ withFileTypes: true,
824
+ });
825
+ } catch (err) {
826
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
827
+ throw err;
828
+ }
764
829
  for (const entry of entries) {
765
830
  if (!entry.isFile()) continue;
766
831
  // `parentPath` is typed on Dirent since Node 20.12, which the engine
@@ -773,12 +838,28 @@ export class LocalDriver implements StorageDriver {
773
838
  // Exclude sidecars — implementation detail.
774
839
  if (rel.endsWith(VISIBILITY_SIDECAR_SUFFIX)) continue;
775
840
  if (!rel.startsWith(prefix)) continue;
776
- const stat = fs.statSync(full);
841
+ const stat = await fsp.stat(full);
777
842
  yield { path: rel, size: stat.size, lastModified: stat.mtime };
778
843
  }
779
844
  }
780
845
  }
781
846
 
847
+ /**
848
+ * Whether a path exists, without `existsSync` blocking the event loop.
849
+ *
850
+ * Used only where the answer is genuinely needed on its own; where a read or
851
+ * unlink follows, the operation's own ENOENT answers it in one syscall and
852
+ * without the window between the two.
853
+ */
854
+ async function exists(target: string): Promise<boolean> {
855
+ try {
856
+ await fsp.access(target);
857
+ return true;
858
+ } catch {
859
+ return false;
860
+ }
861
+ }
862
+
782
863
  /** A local path, given either plainly or as a `file:` URL. */
783
864
  function localPath(source: string | URL): string {
784
865
  return source instanceof URL ? url.fileURLToPath(source) : source;
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Teach ream's `ContainerBindings` what `container.make(...)` returns for the
3
+ * tokens archive binds.
4
+ *
5
+ * ream declares that interface open on purpose: it registers its own entries
6
+ * and expects each package to contribute the ones it owns. Nothing filled
7
+ * these in, so resolving by the string token answered `unknown` and every call
8
+ * site had to assert a type it could not prove.
9
+ *
10
+ * Loaded from the package barrel, so importing Archive anywhere in the
11
+ * application is enough — nobody writes a `declare module` of their own.
12
+ *
13
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
14
+ * import, and a `declare module` for a specifier that does not resolve is
15
+ * simply inert.
16
+ */
17
+
18
+ // Referenced so the augmentation below resolves the module it augments.
19
+ import type {} from "@c9up/ream/types";
20
+
21
+ import type { DriveManager } from "./DriveManager.js";
22
+ import type { StorageManager } from "./StorageManager.js";
23
+
24
+ declare module "@c9up/ream/types" {
25
+ interface ContainerBindings {
26
+ /** The drive manager, bound by `ArchiveProvider`. */
27
+ "archive.drive": DriveManager;
28
+ /**
29
+ * The same binding under the name it had before the token carried its
30
+ * package. Kept bound so an existing `container.make(...)` resolves.
31
+ */
32
+ drive: DriveManager;
33
+ /** The default disk, bound by `ArchiveProvider`. */
34
+ "archive.storage": StorageManager;
35
+ /**
36
+ * The same binding under the name it had before the token carried its
37
+ * package. Kept bound so an existing `container.make(...)` resolves.
38
+ */
39
+ storage: StorageManager;
40
+ }
41
+ }
package/src/etag.ts ADDED
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Entity tags for static responses.
3
+ *
4
+ * Two rules from RFC 9110 that a hand-rolled digest tends to miss, and that
5
+ * both cost a conditional request when missed:
6
+ *
7
+ * - §8.8.3 — an entity-tag IS a quoted string. A bare hex digest is not one,
8
+ * and a strict cache is entitled to ignore it, which turns every
9
+ * revalidation back into a full transfer.
10
+ * - §13.1.2 — `If-None-Match` is a LIST, compared with the WEAK comparison
11
+ * function, so `W/"x"` and `"x"` match. Raw equality against the whole
12
+ * header value fails a client that sends two tags, and fails every client
13
+ * that sends back the weak form of a strong tag.
14
+ *
15
+ * Archive is agnostic, so this lives here rather than being imported from the
16
+ * framework; `@c9up/ream` carries the same two rules in its own `http/etag`.
17
+ */
18
+
19
+ /**
20
+ * The tag for a file, from its metadata rather than its bytes.
21
+ *
22
+ * `W/"<size hex>-<mtime hex>"`, which is what the `etag` package produces for
23
+ * a `Stats` and therefore what every static file server people have cached
24
+ * against emits. Weak because it is derived from metadata: two files with the
25
+ * same size and mtime are equivalent for caching, not provably identical.
26
+ */
27
+ export function statTag(stat: { size: number; mtimeMs: number }): string {
28
+ return `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
29
+ }
30
+
31
+ /** Whether `If-None-Match` covers `tag` (RFC 9110 §13.1.2). */
32
+ export function matchesIfNoneMatch(
33
+ header: string | undefined,
34
+ tag: string,
35
+ ): boolean {
36
+ if (!header || tag === "") return false;
37
+ if (header.trim() === "*") return true;
38
+ const bare = (value: string): string =>
39
+ value.startsWith("W/") ? value.slice(2) : value;
40
+ const current = bare(tag);
41
+ return header
42
+ .split(",")
43
+ .some((candidate) => bare(candidate.trim()) === current);
44
+ }
package/src/expiry.ts CHANGED
@@ -61,7 +61,8 @@ export function parseExpiry(expiresIn: number | string): number {
61
61
  },
62
62
  );
63
63
  }
64
- return Math.round(Number.parseFloat(match[1]) * multiplier);
64
+ const [, amount] = match;
65
+ return Math.round(Number.parseFloat(amount ?? "0") * multiplier);
65
66
  }
66
67
 
67
68
  /**
package/src/index.ts CHANGED
@@ -11,6 +11,8 @@
11
11
  * and a signed-route handler for serving HMAC-signed Local URLs.
12
12
  */
13
13
 
14
+ import "./augmentations.js";
15
+
14
16
  export type { ArchiveConfig } from "./ArchiveProvider.js";
15
17
  export {
16
18
  type DriveConfig,
@@ -13,10 +13,27 @@
13
13
  import type { StorageManager } from "../StorageManager.js";
14
14
 
15
15
  let instance: StorageManager | undefined;
16
+ let resolve: (() => StorageManager) | undefined;
16
17
 
17
18
  /** @internal Bind the singleton (called by ArchiveProvider). */
18
19
  export function setStorage(value: StorageManager): void {
19
20
  instance = value;
21
+ resolve = undefined;
22
+ }
23
+
24
+ /**
25
+ * @internal Bind a way to build the singleton on first genuine use.
26
+ *
27
+ * For the unconfigured case, where building it at boot would create
28
+ * `./storage` for an application that may never touch storage — and fail
29
+ * outright on a read-only rootfs. Skipping it entirely left the container
30
+ * serving `storage` while this accessor threw "before boot": the same
31
+ * application, two answers. Nothing is built until something reaches for it,
32
+ * and then both paths give the same manager.
33
+ */
34
+ export function setStorageResolver(factory: () => StorageManager): void {
35
+ if (instance !== undefined) return;
36
+ resolve = factory;
20
37
  }
21
38
 
22
39
  /** @internal Read the singleton (or `undefined` pre-boot). */
@@ -35,6 +52,10 @@ const storage: StorageManager = new Proxy({} as StorageManager, {
35
52
  if (typeof prop === "symbol" || prop === "then") {
36
53
  return undefined;
37
54
  }
55
+ if (instance === undefined && resolve !== undefined) {
56
+ instance = resolve();
57
+ resolve = undefined;
58
+ }
38
59
  if (!instance) {
39
60
  throw new Error(
40
61
  "[archive] StorageManager singleton accessed before ArchiveProvider.boot() ran. " +