@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.
- package/dist/ArchiveProvider.d.ts +25 -0
- package/dist/ArchiveProvider.d.ts.map +1 -1
- package/dist/ArchiveProvider.js +58 -14
- package/dist/ArchiveProvider.js.map +1 -1
- package/dist/StaticMiddleware.d.ts +16 -1
- package/dist/StaticMiddleware.d.ts.map +1 -1
- package/dist/StaticMiddleware.js +36 -12
- package/dist/StaticMiddleware.js.map +1 -1
- package/dist/StorageManager.d.ts +8 -0
- package/dist/StorageManager.d.ts.map +1 -1
- package/dist/StorageManager.js +176 -102
- package/dist/StorageManager.js.map +1 -1
- package/dist/augmentations.d.ts +37 -0
- package/dist/augmentations.d.ts.map +1 -0
- package/dist/augmentations.js +18 -0
- package/dist/augmentations.js.map +1 -0
- package/dist/etag.d.ts +32 -0
- package/dist/etag.d.ts.map +1 -0
- package/dist/etag.js +41 -0
- package/dist/etag.js.map +1 -0
- package/dist/expiry.d.ts.map +1 -1
- package/dist/expiry.js +2 -1
- package/dist/expiry.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/services/main.d.ts +11 -0
- package/dist/services/main.d.ts.map +1 -1
- package/dist/services/main.js +21 -0
- package/dist/services/main.js.map +1 -1
- package/package.json +3 -2
- package/src/ArchiveProvider.ts +69 -21
- package/src/StaticMiddleware.ts +53 -13
- package/src/StorageManager.ts +180 -99
- package/src/augmentations.ts +41 -0
- package/src/etag.ts +44 -0
- package/src/expiry.ts +2 -1
- package/src/index.ts +2 -0
- package/src/services/main.ts +21 -0
package/src/StorageManager.ts
CHANGED
|
@@ -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
|
-
*
|
|
296
|
-
*
|
|
304
|
+
* The half of the guard that touches nothing: control characters and
|
|
305
|
+
* lexical containment.
|
|
297
306
|
*
|
|
298
|
-
*
|
|
299
|
-
*
|
|
300
|
-
*
|
|
301
|
-
*
|
|
302
|
-
*
|
|
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
|
-
#
|
|
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
|
|
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
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
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
|
-
|
|
351
|
-
|
|
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
|
-
|
|
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
|
-
|
|
394
|
-
|
|
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 (!
|
|
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
|
-
|
|
412
|
-
|
|
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
|
-
|
|
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
|
|
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 =
|
|
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 (!
|
|
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
|
-
|
|
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 =
|
|
513
|
-
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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 (!
|
|
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
|
-
|
|
601
|
-
|
|
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 (!
|
|
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 =
|
|
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
|
-
|
|
633
|
-
if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
|
|
691
|
+
await fsp.mkdir(path.dirname(toFull), { recursive: true });
|
|
634
692
|
try {
|
|
635
|
-
|
|
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
|
-
|
|
640
|
-
|
|
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
|
-
|
|
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
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
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
|
|
750
|
+
const dir = await this.#safePath(prefix);
|
|
751
|
+
if (dir !== this.#root) {
|
|
696
752
|
try {
|
|
697
|
-
const stat =
|
|
698
|
-
if (stat.isDirectory() &&
|
|
699
|
-
|
|
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(
|
|
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(
|
|
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
|
-
|
|
757
|
-
// `
|
|
758
|
-
//
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
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 =
|
|
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
|
-
|
|
64
|
+
const [, amount] = match;
|
|
65
|
+
return Math.round(Number.parseFloat(amount ?? "0") * multiplier);
|
|
65
66
|
}
|
|
66
67
|
|
|
67
68
|
/**
|
package/src/index.ts
CHANGED
package/src/services/main.ts
CHANGED
|
@@ -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. " +
|