@c9up/archive 0.1.19 → 0.1.21
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/README.md +96 -3
- package/dist/ArchiveProvider.d.ts +8 -2
- package/dist/ArchiveProvider.d.ts.map +1 -1
- package/dist/ArchiveProvider.js +73 -1
- package/dist/ArchiveProvider.js.map +1 -1
- package/dist/DriveManager.d.ts +16 -6
- package/dist/DriveManager.d.ts.map +1 -1
- package/dist/DriveManager.js +23 -6
- package/dist/DriveManager.js.map +1 -1
- package/dist/GcsDriver.d.ts +14 -9
- package/dist/GcsDriver.d.ts.map +1 -1
- package/dist/GcsDriver.js +202 -98
- package/dist/GcsDriver.js.map +1 -1
- package/dist/S3Driver.d.ts +11 -7
- package/dist/S3Driver.d.ts.map +1 -1
- package/dist/S3Driver.js +73 -110
- package/dist/S3Driver.js.map +1 -1
- package/dist/StaticMiddleware.d.ts +5 -1
- package/dist/StaticMiddleware.d.ts.map +1 -1
- package/dist/StaticMiddleware.js +114 -13
- package/dist/StaticMiddleware.js.map +1 -1
- package/dist/StorageManager.d.ts +36 -4
- package/dist/StorageManager.d.ts.map +1 -1
- package/dist/StorageManager.js +360 -137
- package/dist/StorageManager.js.map +1 -1
- package/dist/augmentations.d.ts +17 -0
- package/dist/augmentations.d.ts.map +1 -1
- package/dist/errno.d.ts +6 -0
- package/dist/errno.d.ts.map +1 -0
- package/dist/errno.js +11 -0
- package/dist/errno.js.map +1 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/keys.d.ts +34 -0
- package/dist/keys.d.ts.map +1 -0
- package/dist/keys.js +88 -0
- package/dist/keys.js.map +1 -0
- package/dist/local-signature.d.ts +32 -0
- package/dist/local-signature.d.ts.map +1 -0
- package/dist/local-signature.js +58 -0
- package/dist/local-signature.js.map +1 -0
- package/dist/move-to-disk.d.ts +24 -0
- package/dist/move-to-disk.d.ts.map +1 -0
- package/dist/move-to-disk.js +167 -0
- package/dist/move-to-disk.js.map +1 -0
- package/dist/objects.d.ts.map +1 -1
- package/dist/objects.js +5 -2
- package/dist/objects.js.map +1 -1
- package/dist/provider-fetch.d.ts +36 -0
- package/dist/provider-fetch.d.ts.map +1 -0
- package/dist/provider-fetch.js +158 -0
- package/dist/provider-fetch.js.map +1 -0
- package/dist/services/main.d.ts +1 -1
- package/dist/services/main.d.ts.map +1 -1
- package/dist/services/main.js +14 -1
- package/dist/services/main.js.map +1 -1
- package/dist/signed-route.d.ts +18 -6
- package/dist/signed-route.d.ts.map +1 -1
- package/dist/signed-route.js +186 -31
- package/dist/signed-route.js.map +1 -1
- package/dist/streams.d.ts +36 -0
- package/dist/streams.d.ts.map +1 -0
- package/dist/streams.js +108 -0
- package/dist/streams.js.map +1 -0
- package/dist/testing/FakeStorage.d.ts.map +1 -1
- package/dist/testing/FakeStorage.js +2 -1
- package/dist/testing/FakeStorage.js.map +1 -1
- package/package.json +7 -3
- package/src/ArchiveProvider.ts +106 -4
- package/src/DriveManager.ts +38 -8
- package/src/GcsDriver.ts +256 -139
- package/src/S3Driver.ts +87 -130
- package/src/StaticMiddleware.ts +124 -13
- package/src/StorageManager.ts +433 -147
- package/src/augmentations.ts +24 -1
- package/src/errno.ts +10 -0
- package/src/index.ts +2 -0
- package/src/keys.ts +104 -0
- package/src/local-signature.ts +76 -0
- package/src/move-to-disk.ts +234 -0
- package/src/objects.ts +5 -2
- package/src/provider-fetch.ts +171 -0
- package/src/services/main.ts +15 -2
- package/src/signed-route.ts +216 -36
- package/src/streams.ts +118 -0
- package/src/testing/FakeStorage.ts +2 -3
package/src/StorageManager.ts
CHANGED
|
@@ -10,12 +10,19 @@ import * as fsp from "node:fs/promises";
|
|
|
10
10
|
import * as path from "node:path";
|
|
11
11
|
import { pipeline } from "node:stream/promises";
|
|
12
12
|
import * as url from "node:url";
|
|
13
|
+
import { errnoCode } from "./errno.js";
|
|
13
14
|
import { ArchiveError } from "./errors.js";
|
|
14
15
|
import {
|
|
15
16
|
assertValidExpiry,
|
|
16
17
|
DEFAULT_EXPIRES_IN,
|
|
17
18
|
parseExpiry,
|
|
18
19
|
} from "./expiry.js";
|
|
20
|
+
import { normalizeKey, normalizePrefix } from "./keys.js";
|
|
21
|
+
import {
|
|
22
|
+
overrideQuery,
|
|
23
|
+
requestedOverrides,
|
|
24
|
+
signedPayload,
|
|
25
|
+
} from "./local-signature.js";
|
|
19
26
|
import { inferMimeType } from "./mime-types.js";
|
|
20
27
|
import { DriveDirectory, DriveFile, type FileSnapshot } from "./objects.js";
|
|
21
28
|
|
|
@@ -29,9 +36,17 @@ export interface SignedUrlOptions {
|
|
|
29
36
|
* (5 minutes). Bounds after parsing: 1–604800.
|
|
30
37
|
*/
|
|
31
38
|
expiresIn?: number | string;
|
|
32
|
-
/**
|
|
39
|
+
/**
|
|
40
|
+
* Sets the response `Content-Type` served with the signed URL. Cloud
|
|
41
|
+
* drivers pass it to the provider; the local disk signs it into the URL
|
|
42
|
+
* and the signed route sends it.
|
|
43
|
+
*/
|
|
33
44
|
contentType?: string;
|
|
34
|
-
/**
|
|
45
|
+
/**
|
|
46
|
+
* Sets the response `Content-Disposition` served with the signed URL —
|
|
47
|
+
* `attachment; filename="…"` to download rather than display. Same
|
|
48
|
+
* handling as {@link SignedUrlOptions.contentType}.
|
|
49
|
+
*/
|
|
35
50
|
contentDisposition?: string;
|
|
36
51
|
}
|
|
37
52
|
|
|
@@ -258,8 +273,41 @@ export interface LocalDriverOptions {
|
|
|
258
273
|
* When omitted, signing is disabled and `getSignedUrl` throws
|
|
259
274
|
* `E_ARCHIVE_SIGNING_DISABLED`. The non-signing methods
|
|
260
275
|
* (`put`/`get`/`delete`/`exists`/`url`) work either way.
|
|
276
|
+
*
|
|
277
|
+
* A string, or a `Secret` (`env.get('APP_KEY')` when the env schema
|
|
278
|
+
* declares it with `Env.schema.secret()`), released once by the driver.
|
|
279
|
+
*/
|
|
280
|
+
signingSecret?: string | ReleasableSecret;
|
|
281
|
+
/**
|
|
282
|
+
* The URL path files are served under (default `/storage`). `publicUrl`,
|
|
283
|
+
* `url` and `getSignedUrl` build on it, and the signed route reads it from
|
|
284
|
+
* the driver, so the URLs handed out and the route serving them cannot
|
|
285
|
+
* disagree. A trailing `/` is dropped.
|
|
261
286
|
*/
|
|
262
|
-
|
|
287
|
+
routeBasePath?: string;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/** Anything that releases a secret string — an environment `Secret`. */
|
|
291
|
+
export interface ReleasableSecret {
|
|
292
|
+
release(): string;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* The secret as a string, or `undefined` when it is neither a string nor a
|
|
297
|
+
* Secret wrapping one. Typed configs cannot hand over anything else; the
|
|
298
|
+
* guard is for an untyped (JavaScript) config, whose `Secret` would otherwise
|
|
299
|
+
* reach the HMAC as its redacted placeholder text.
|
|
300
|
+
*/
|
|
301
|
+
function releaseSecret(secret: unknown): string | undefined {
|
|
302
|
+
if (typeof secret === "string") return secret;
|
|
303
|
+
if (typeof secret === "object" && secret !== null && "release" in secret) {
|
|
304
|
+
const release: unknown = secret.release;
|
|
305
|
+
if (typeof release === "function") {
|
|
306
|
+
const released: unknown = release.call(secret);
|
|
307
|
+
if (typeof released === "string") return released;
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
return undefined;
|
|
263
311
|
}
|
|
264
312
|
|
|
265
313
|
/**
|
|
@@ -271,9 +319,29 @@ export interface LocalDriverOptions {
|
|
|
271
319
|
*/
|
|
272
320
|
const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
|
|
273
321
|
|
|
322
|
+
/**
|
|
323
|
+
* A route base path, without its trailing `/`. Refused unless it is an
|
|
324
|
+
* absolute URL path with at least one segment and nothing a URL would read
|
|
325
|
+
* as a query, a fragment or a break.
|
|
326
|
+
*/
|
|
327
|
+
function routeBasePath(given: string): string {
|
|
328
|
+
const trimmed = given.replace(/\/+$/, "");
|
|
329
|
+
if (!/^(\/[^/?#\s]+)+$/.test(trimmed)) {
|
|
330
|
+
throw new ArchiveError(
|
|
331
|
+
"E_ARCHIVE_INVALID_ROUTE_BASE_PATH",
|
|
332
|
+
`LocalDriver routeBasePath must be an absolute URL path such as '/storage', got ${JSON.stringify(given)}`,
|
|
333
|
+
{
|
|
334
|
+
hint: "Start it with '/', name at least one segment, and leave out '?', '#' and whitespace.",
|
|
335
|
+
},
|
|
336
|
+
);
|
|
337
|
+
}
|
|
338
|
+
return trimmed;
|
|
339
|
+
}
|
|
340
|
+
|
|
274
341
|
export class LocalDriver implements StorageDriver {
|
|
275
342
|
#root: string;
|
|
276
343
|
#signingSecret: string | null;
|
|
344
|
+
#routeBasePath: string;
|
|
277
345
|
|
|
278
346
|
/**
|
|
279
347
|
* The only synchronous filesystem access left in this driver, and the only
|
|
@@ -284,6 +352,9 @@ export class LocalDriver implements StorageDriver {
|
|
|
284
352
|
* request in the process for its whole duration.
|
|
285
353
|
*/
|
|
286
354
|
constructor(root: string, options?: LocalDriverOptions) {
|
|
355
|
+
// Validated before the root is created: a refused config leaves
|
|
356
|
+
// nothing behind on disk.
|
|
357
|
+
this.#routeBasePath = routeBasePath(options?.routeBasePath ?? "/storage");
|
|
287
358
|
const resolved = path.resolve(root);
|
|
288
359
|
if (!fs.existsSync(resolved)) {
|
|
289
360
|
fs.mkdirSync(resolved, { recursive: true });
|
|
@@ -291,22 +362,25 @@ export class LocalDriver implements StorageDriver {
|
|
|
291
362
|
// Canonicalise the root once so subsequent realpath-based
|
|
292
363
|
// escape checks compare apples to apples.
|
|
293
364
|
this.#root = fs.realpathSync(resolved);
|
|
294
|
-
const
|
|
295
|
-
|
|
365
|
+
const configured = options?.signingSecret;
|
|
366
|
+
let secret: string | null = null;
|
|
367
|
+
if (configured !== undefined) {
|
|
368
|
+
const released = releaseSecret(configured);
|
|
296
369
|
// Empty or trivially short secrets defeat the whole point of
|
|
297
370
|
// HMAC signing. 16 bytes is the floor: rejects obviously weak
|
|
298
371
|
// values without being annoyingly strict about format.
|
|
299
|
-
if (
|
|
372
|
+
if (released === undefined || released.length < 16) {
|
|
300
373
|
throw new ArchiveError(
|
|
301
374
|
"E_ARCHIVE_WEAK_SIGNING_SECRET",
|
|
302
|
-
`LocalDriver signingSecret must be a string
|
|
375
|
+
`LocalDriver signingSecret must be a string or a Secret wrapping one, at least 16 chars (got ${released === undefined ? "neither" : `length ${released.length}`})`,
|
|
303
376
|
{
|
|
304
377
|
hint: "Use a cryptographically random secret, e.g. `crypto.randomBytes(32).toString('hex')`.",
|
|
305
378
|
},
|
|
306
379
|
);
|
|
307
380
|
}
|
|
381
|
+
secret = released;
|
|
308
382
|
}
|
|
309
|
-
this.#signingSecret = secret
|
|
383
|
+
this.#signingSecret = secret;
|
|
310
384
|
}
|
|
311
385
|
|
|
312
386
|
/**
|
|
@@ -320,28 +394,50 @@ export class LocalDriver implements StorageDriver {
|
|
|
320
394
|
* is the failure that matters.
|
|
321
395
|
*/
|
|
322
396
|
#lexicalPath(filePath: string): string {
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
//
|
|
326
|
-
//
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
);
|
|
333
|
-
}
|
|
334
|
-
}
|
|
335
|
-
const full = path.resolve(this.#root, filePath);
|
|
336
|
-
// Lexical guard — cheap and covers the `..` case.
|
|
337
|
-
if (!full.startsWith(this.#root + path.sep) && full !== this.#root) {
|
|
338
|
-
throw new Error(
|
|
397
|
+
const key = this.#key(filePath);
|
|
398
|
+
const full = path.resolve(this.#root, key);
|
|
399
|
+
// Lexical guard, kept behind the normaliser: a normalised key has no
|
|
400
|
+
// `..` and no leading `/`, but a drive-letter key resolves to an
|
|
401
|
+
// absolute path on Windows, and a containment check is not where to
|
|
402
|
+
// rely on one layer only.
|
|
403
|
+
if (!full.startsWith(this.#root + path.sep)) {
|
|
404
|
+
throw new ArchiveError(
|
|
405
|
+
"E_ARCHIVE_PATH_TRAVERSAL_DETECTED",
|
|
339
406
|
`Path traversal blocked: '${filePath}' resolves outside storage root`,
|
|
407
|
+
{ hint: "Keys are relative to the disk root." },
|
|
340
408
|
);
|
|
341
409
|
}
|
|
342
410
|
return full;
|
|
343
411
|
}
|
|
344
412
|
|
|
413
|
+
/**
|
|
414
|
+
* The normalised key (see `keys.ts`), refused when it names a visibility
|
|
415
|
+
* marker.
|
|
416
|
+
*
|
|
417
|
+
* Control characters are refused by the normaliser; that matters here
|
|
418
|
+
* because `\n` is the signing payload separator — a key containing one
|
|
419
|
+
* could otherwise forge `exp`.
|
|
420
|
+
*/
|
|
421
|
+
#key(filePath: string): string {
|
|
422
|
+
const key = normalizeKey(filePath);
|
|
423
|
+
// The visibility markers live beside the files they describe, so a key
|
|
424
|
+
// naming one would let a caller write, delete or read the marker of
|
|
425
|
+
// another file — `put("secret.pdf.archive-visibility.json", …)` turned a
|
|
426
|
+
// private file public. Refused on every segment (a marker name used as a
|
|
427
|
+
// directory blocks the marker write too) and case-insensitively (the
|
|
428
|
+
// same file on a case-insensitive filesystem).
|
|
429
|
+
for (const segment of key.split("/")) {
|
|
430
|
+
if (segment.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX)) {
|
|
431
|
+
throw new ArchiveError(
|
|
432
|
+
"E_ARCHIVE_INVALID_KEY",
|
|
433
|
+
`Invalid key '${filePath}': names ending in '${VISIBILITY_SIDECAR_SUFFIX}' are reserved for visibility markers`,
|
|
434
|
+
{ hint: "Store the object under a name without that suffix." },
|
|
435
|
+
);
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
return key;
|
|
439
|
+
}
|
|
440
|
+
|
|
345
441
|
/**
|
|
346
442
|
* Resolve and validate a file path — prevents traversal outside
|
|
347
443
|
* the root, INCLUDING via symlinks planted inside the root.
|
|
@@ -363,13 +459,15 @@ export class LocalDriver implements StorageDriver {
|
|
|
363
459
|
!realProbe.startsWith(this.#root + path.sep) &&
|
|
364
460
|
realProbe !== this.#root
|
|
365
461
|
) {
|
|
366
|
-
throw new
|
|
462
|
+
throw new ArchiveError(
|
|
463
|
+
"E_ARCHIVE_PATH_TRAVERSAL_DETECTED",
|
|
367
464
|
`Path traversal blocked: '${filePath}' resolves outside storage root via symlink`,
|
|
465
|
+
{ hint: "A link inside the disk root points outside it." },
|
|
368
466
|
);
|
|
369
467
|
}
|
|
370
468
|
return full;
|
|
371
469
|
} catch (err) {
|
|
372
|
-
if ((err
|
|
470
|
+
if (errnoCode(err) !== "ENOENT") throw err;
|
|
373
471
|
const parent = path.dirname(probe);
|
|
374
472
|
// The root itself is canonicalised at construction, so the walk
|
|
375
473
|
// always terminates at something that resolves.
|
|
@@ -394,8 +492,88 @@ export class LocalDriver implements StorageDriver {
|
|
|
394
492
|
// by name follows it — the check passed on one object and the write
|
|
395
493
|
// landed on another. Refusing to follow a link at open time takes the
|
|
396
494
|
// swap off the table: the open fails instead of writing outside the root.
|
|
495
|
+
//
|
|
496
|
+
// Only `visibility` has a filesystem-equivalent (the marker);
|
|
497
|
+
// contentType/cacheControl/... have no local meaning.
|
|
498
|
+
await this.#writeMarked(full, options?.visibility, async () => {
|
|
499
|
+
const handle = await fsp.open(
|
|
500
|
+
full,
|
|
501
|
+
fs.constants.O_WRONLY |
|
|
502
|
+
fs.constants.O_CREAT |
|
|
503
|
+
fs.constants.O_TRUNC |
|
|
504
|
+
O_NOFOLLOW,
|
|
505
|
+
0o666,
|
|
506
|
+
);
|
|
507
|
+
try {
|
|
508
|
+
await handle.writeFile(content);
|
|
509
|
+
} finally {
|
|
510
|
+
await handle.close();
|
|
511
|
+
}
|
|
512
|
+
});
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
/**
|
|
516
|
+
* Run `write`, which puts data at `full`, and leave the object with
|
|
517
|
+
* `visibility` — without it ever being readable as public while it should
|
|
518
|
+
* not be.
|
|
519
|
+
*
|
|
520
|
+
* The marker is a second file, and its absence means public. A PRIVATE
|
|
521
|
+
* marker therefore goes down BEFORE the data: written after, the object
|
|
522
|
+
* was public for the whole write — served unsigned by the signed route and
|
|
523
|
+
* by a static server over the disk — and stayed public for good when the
|
|
524
|
+
* marker write failed. If the data write then fails, the half-written
|
|
525
|
+
* object is removed, and its marker only once the data is gone: the object
|
|
526
|
+
* ends private or absent, never public.
|
|
527
|
+
*
|
|
528
|
+
* A PUBLIC marker goes down AFTER the data, for the same reason the other
|
|
529
|
+
* way round: the bytes being replaced may be private, and they keep their
|
|
530
|
+
* marker until the new ones have landed.
|
|
531
|
+
*/
|
|
532
|
+
async #writeMarked(
|
|
533
|
+
full: string,
|
|
534
|
+
visibility: Visibility | undefined,
|
|
535
|
+
write: () => Promise<void>,
|
|
536
|
+
): Promise<void> {
|
|
537
|
+
if (visibility !== "private") {
|
|
538
|
+
await write();
|
|
539
|
+
if (visibility !== undefined) await this.#writeMarker(full, visibility);
|
|
540
|
+
return;
|
|
541
|
+
}
|
|
542
|
+
await this.#markPrivate(full);
|
|
543
|
+
try {
|
|
544
|
+
await write();
|
|
545
|
+
} catch (err) {
|
|
546
|
+
await discardPrivate(full);
|
|
547
|
+
throw err;
|
|
548
|
+
}
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
/**
|
|
552
|
+
* Mark `full` private before its data is touched. A marker write that
|
|
553
|
+
* fails puts the previous marker back (or leaves a damaged one, which
|
|
554
|
+
* reads as undetermined and is served to nobody), and rethrows: the
|
|
555
|
+
* caller writes no data.
|
|
556
|
+
*/
|
|
557
|
+
async #markPrivate(full: string): Promise<MarkerSnapshot> {
|
|
558
|
+
const previous = await markerSnapshot(full);
|
|
559
|
+
try {
|
|
560
|
+
await this.#writeMarker(full, "private");
|
|
561
|
+
} catch (err) {
|
|
562
|
+
await restoreMarker(full, previous);
|
|
563
|
+
throw err;
|
|
564
|
+
}
|
|
565
|
+
return previous;
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
/**
|
|
569
|
+
* Write the visibility marker of the file at `full`, a path `#safePath`
|
|
570
|
+
* already resolved. Through an O_NOFOLLOW descriptor, as the data is: a
|
|
571
|
+
* link planted at the marker's name is refused rather than followed to
|
|
572
|
+
* write outside the root.
|
|
573
|
+
*/
|
|
574
|
+
async #writeMarker(full: string, visibility: Visibility): Promise<void> {
|
|
397
575
|
const handle = await fsp.open(
|
|
398
|
-
full,
|
|
576
|
+
full + VISIBILITY_SIDECAR_SUFFIX,
|
|
399
577
|
fs.constants.O_WRONLY |
|
|
400
578
|
fs.constants.O_CREAT |
|
|
401
579
|
fs.constants.O_TRUNC |
|
|
@@ -403,15 +581,10 @@ export class LocalDriver implements StorageDriver {
|
|
|
403
581
|
0o666,
|
|
404
582
|
);
|
|
405
583
|
try {
|
|
406
|
-
await handle.writeFile(
|
|
584
|
+
await handle.writeFile(JSON.stringify({ visibility }));
|
|
407
585
|
} finally {
|
|
408
586
|
await handle.close();
|
|
409
587
|
}
|
|
410
|
-
// Only `visibility` has a filesystem-equivalent (the sidecar).
|
|
411
|
-
// contentType/cacheControl/... have no local meaning.
|
|
412
|
-
if (options?.visibility !== undefined) {
|
|
413
|
-
await this.setVisibility(filePath, options.visibility);
|
|
414
|
-
}
|
|
415
588
|
}
|
|
416
589
|
|
|
417
590
|
async getBytes(filePath: string): Promise<Uint8Array> {
|
|
@@ -464,7 +637,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
464
637
|
} catch (err) {
|
|
465
638
|
// One syscall instead of exists-then-read: the pair also answered
|
|
466
639
|
// `null` for a file that was deleted between the two.
|
|
467
|
-
if ((err
|
|
640
|
+
if (errnoCode(err) === "ENOENT") return null;
|
|
468
641
|
throw err;
|
|
469
642
|
}
|
|
470
643
|
}
|
|
@@ -479,7 +652,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
479
652
|
try {
|
|
480
653
|
handle = await fsp.open(full, fs.constants.O_RDONLY | O_NOFOLLOW);
|
|
481
654
|
} catch (err) {
|
|
482
|
-
if ((err
|
|
655
|
+
if (errnoCode(err) === "ENOENT") {
|
|
483
656
|
throw new ArchiveError(
|
|
484
657
|
"E_ARCHIVE_NOT_FOUND",
|
|
485
658
|
`File does not exist at path '${filePath}'`,
|
|
@@ -497,7 +670,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
497
670
|
try {
|
|
498
671
|
await fsp.unlink(full);
|
|
499
672
|
} catch (err) {
|
|
500
|
-
if ((err
|
|
673
|
+
if (errnoCode(err) === "ENOENT") return false;
|
|
501
674
|
throw err;
|
|
502
675
|
}
|
|
503
676
|
// Sidecar cleanup is best-effort. The main file is already gone
|
|
@@ -514,9 +687,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
514
687
|
}
|
|
515
688
|
|
|
516
689
|
async exists(filePath: string): Promise<boolean> {
|
|
517
|
-
//
|
|
518
|
-
// exist from the public API's point of view.
|
|
519
|
-
if (filePath.endsWith(VISIBILITY_SIDECAR_SUFFIX)) return false;
|
|
690
|
+
// A marker name is refused by the path guard, as by every other method.
|
|
520
691
|
return exists(await this.#safePath(filePath));
|
|
521
692
|
}
|
|
522
693
|
|
|
@@ -525,11 +696,20 @@ export class LocalDriver implements StorageDriver {
|
|
|
525
696
|
// survive the trip through an HTTP layer. The middleware mirrors
|
|
526
697
|
// this by decoding each segment before recomputing the HMAC —
|
|
527
698
|
// skipping encoding here would leave the URL unparseable.
|
|
528
|
-
const encoded = filePath
|
|
699
|
+
const encoded = this.#key(filePath)
|
|
529
700
|
.split("/")
|
|
530
701
|
.map((seg) => encodeURIComponent(seg))
|
|
531
702
|
.join("/");
|
|
532
|
-
return
|
|
703
|
+
return `${this.#routeBasePath}/${encoded}`;
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
/**
|
|
707
|
+
* The URL path this driver's files are served under. The signed route
|
|
708
|
+
* reads it, so the URLs this driver builds and the route that serves them
|
|
709
|
+
* derive from one value.
|
|
710
|
+
*/
|
|
711
|
+
getRouteBasePath(): string {
|
|
712
|
+
return this.#routeBasePath;
|
|
533
713
|
}
|
|
534
714
|
|
|
535
715
|
async url(filePath: string): Promise<string> {
|
|
@@ -544,7 +724,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
544
724
|
try {
|
|
545
725
|
stat = await fsp.stat(full);
|
|
546
726
|
} catch (err) {
|
|
547
|
-
if ((err
|
|
727
|
+
if (errnoCode(err) === "ENOENT") {
|
|
548
728
|
throw new ArchiveError(
|
|
549
729
|
"E_ARCHIVE_NOT_FOUND",
|
|
550
730
|
`File does not exist at path '${filePath}'`,
|
|
@@ -585,8 +765,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
585
765
|
{ hint: "put() the file before calling setVisibility()." },
|
|
586
766
|
);
|
|
587
767
|
}
|
|
588
|
-
|
|
589
|
-
await fsp.writeFile(sidecar, JSON.stringify({ visibility }), { flag: "w" });
|
|
768
|
+
await this.#writeMarker(full, visibility);
|
|
590
769
|
}
|
|
591
770
|
|
|
592
771
|
/**
|
|
@@ -607,18 +786,18 @@ export class LocalDriver implements StorageDriver {
|
|
|
607
786
|
} catch (err) {
|
|
608
787
|
// Absent sidecar is the documented default, and it is the common
|
|
609
788
|
// case: one syscall answers both that and a real read failure.
|
|
610
|
-
if ((err
|
|
789
|
+
if (errnoCode(err) === "ENOENT") return "public";
|
|
611
790
|
throw new ArchiveError(
|
|
612
791
|
"E_ARCHIVE_VISIBILITY_CORRUPT",
|
|
613
|
-
`Failed to read visibility sidecar for '${filePath}' (${(err
|
|
792
|
+
`Failed to read visibility sidecar for '${filePath}' (${errnoCode(err) ?? "I/O error"}); refusing to default to 'public'.`,
|
|
614
793
|
{
|
|
615
794
|
hint: "Inspect the sidecar file or re-apply visibility via setVisibility().",
|
|
616
795
|
},
|
|
617
796
|
);
|
|
618
797
|
}
|
|
619
|
-
let parsed:
|
|
798
|
+
let parsed: unknown;
|
|
620
799
|
try {
|
|
621
|
-
parsed = JSON.parse(raw)
|
|
800
|
+
parsed = JSON.parse(raw);
|
|
622
801
|
} catch {
|
|
623
802
|
throw new ArchiveError(
|
|
624
803
|
"E_ARCHIVE_VISIBILITY_CORRUPT",
|
|
@@ -636,12 +815,16 @@ export class LocalDriver implements StorageDriver {
|
|
|
636
815
|
// handed out `/storage/<path>` instead of a signed URL. The doc comment
|
|
637
816
|
// above already promised this for unparseable JSON; a JSON document
|
|
638
817
|
// that parses and says nothing usable is the same situation.
|
|
639
|
-
|
|
640
|
-
|
|
818
|
+
const visibility =
|
|
819
|
+
typeof parsed === "object" && parsed !== null && "visibility" in parsed
|
|
820
|
+
? parsed.visibility
|
|
821
|
+
: undefined;
|
|
822
|
+
if (visibility === "private" || visibility === "public") {
|
|
823
|
+
return visibility;
|
|
641
824
|
}
|
|
642
825
|
throw new ArchiveError(
|
|
643
826
|
"E_ARCHIVE_VISIBILITY_CORRUPT",
|
|
644
|
-
`Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(
|
|
827
|
+
`Sidecar for '${filePath}' carries no usable visibility (${JSON.stringify(visibility)}); refusing to default to 'public'.`,
|
|
645
828
|
{
|
|
646
829
|
hint: "Delete the sidecar file and re-apply visibility via setVisibility().",
|
|
647
830
|
},
|
|
@@ -658,8 +841,10 @@ export class LocalDriver implements StorageDriver {
|
|
|
658
841
|
// signing a URL reads no file — the read it leads to goes through the
|
|
659
842
|
// full check. What must NOT be skipped here is the control-character
|
|
660
843
|
// rejection, since `\n` is this signature's own payload separator, and
|
|
661
|
-
// `#lexicalPath` is where that lives.
|
|
844
|
+
// `#lexicalPath` is where that lives. What is signed is the
|
|
845
|
+
// normalised key, which is what the route recomputes it over.
|
|
662
846
|
this.#lexicalPath(filePath);
|
|
847
|
+
const key = this.#key(filePath);
|
|
663
848
|
const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
|
|
664
849
|
assertValidExpiry(expiresIn);
|
|
665
850
|
const secret = this.#signingSecret;
|
|
@@ -676,9 +861,13 @@ export class LocalDriver implements StorageDriver {
|
|
|
676
861
|
// Newline-delimited payload: a filePath cannot forge `exp` by
|
|
677
862
|
// embedding `&exp=...` in its own bytes (URL-decoding still
|
|
678
863
|
// keeps the literal `\n` separator in the signed material).
|
|
679
|
-
|
|
864
|
+
// Response-header overrides are signed with the rest and carried in the
|
|
865
|
+
// query, where the signed route reads, verifies and emits them.
|
|
866
|
+
const overrides = requestedOverrides(options ?? {});
|
|
867
|
+
const message = signedPayload(key, exp, overrides);
|
|
680
868
|
const sig = createHmac("sha256", secret).update(message).digest("hex");
|
|
681
|
-
|
|
869
|
+
const url = `${this.publicUrl(key)}?exp=${exp}&sig=${sig}`;
|
|
870
|
+
return overrides.length === 0 ? url : `${url}&${overrideQuery(overrides)}`;
|
|
682
871
|
}
|
|
683
872
|
|
|
684
873
|
/**
|
|
@@ -715,12 +904,12 @@ export class LocalDriver implements StorageDriver {
|
|
|
715
904
|
);
|
|
716
905
|
}
|
|
717
906
|
await fsp.mkdir(path.dirname(toFull), { recursive: true });
|
|
718
|
-
await fsp.copyFile(fromFull, toFull);
|
|
719
907
|
// Intentionally do NOT copy the visibility sidecar — new object
|
|
720
|
-
// takes default visibility unless the caller asks otherwise.
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
908
|
+
// takes default visibility unless the caller asks otherwise. A private
|
|
909
|
+
// one is marked before the bytes are copied, as put() does.
|
|
910
|
+
await this.#writeMarked(toFull, options?.visibility, () =>
|
|
911
|
+
fsp.copyFile(fromFull, toFull),
|
|
912
|
+
);
|
|
724
913
|
}
|
|
725
914
|
|
|
726
915
|
async move(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
@@ -739,44 +928,54 @@ export class LocalDriver implements StorageDriver {
|
|
|
739
928
|
// silently downgrade private→public. `#readVisibility` throws on
|
|
740
929
|
// corruption, which surfaces here BEFORE we mutate anything.
|
|
741
930
|
const fromSidecar = fromFull + VISIBILITY_SIDECAR_SUFFIX;
|
|
742
|
-
const toSidecar = toFull + VISIBILITY_SIDECAR_SUFFIX;
|
|
743
931
|
const capturedVisibility: Visibility | undefined = (await exists(
|
|
744
932
|
fromSidecar,
|
|
745
933
|
))
|
|
746
934
|
? await this.#readVisibility(from)
|
|
747
935
|
: undefined;
|
|
936
|
+
// An explicit visibility override wins over the preserved value.
|
|
937
|
+
const target = options?.visibility ?? capturedVisibility;
|
|
748
938
|
await fsp.mkdir(path.dirname(toFull), { recursive: true });
|
|
939
|
+
// A private target is marked BEFORE the file arrives: renamed first, the
|
|
940
|
+
// moved private file sat at the target with no marker — public — until
|
|
941
|
+
// the second write, and for good when that write failed.
|
|
942
|
+
const previous =
|
|
943
|
+
target === "private" ? await this.#markPrivate(toFull) : undefined;
|
|
749
944
|
try {
|
|
750
945
|
await fsp.rename(fromFull, toFull);
|
|
751
946
|
} catch (err) {
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
await
|
|
755
|
-
await fsp.unlink(fromFull);
|
|
756
|
-
} else {
|
|
947
|
+
if (errnoCode(err) !== "EXDEV") {
|
|
948
|
+
// Nothing moved: the target is what it was, so is its marker.
|
|
949
|
+
if (previous !== undefined) await restoreMarker(toFull, previous);
|
|
757
950
|
throw err;
|
|
758
951
|
}
|
|
952
|
+
// Cross-device rename — fall back to copy+unlink. A half-copied
|
|
953
|
+
// target is removed, and its marker only once the data is gone.
|
|
954
|
+
try {
|
|
955
|
+
await fsp.copyFile(fromFull, toFull);
|
|
956
|
+
} catch (copyErr) {
|
|
957
|
+
await discardPrivate(toFull);
|
|
958
|
+
throw copyErr;
|
|
959
|
+
}
|
|
960
|
+
await fsp.unlink(fromFull);
|
|
759
961
|
}
|
|
760
|
-
//
|
|
761
|
-
//
|
|
762
|
-
//
|
|
763
|
-
|
|
764
|
-
if (capturedVisibility !== undefined) {
|
|
962
|
+
// A public target is marked AFTER the move: until then, whatever was at
|
|
963
|
+
// the target keeps its own marker. Public is the default, so an absent
|
|
964
|
+
// source sidecar and no override mean no work.
|
|
965
|
+
if (target === "public") {
|
|
765
966
|
try {
|
|
766
|
-
await
|
|
767
|
-
toSidecar,
|
|
768
|
-
JSON.stringify({ visibility: capturedVisibility }),
|
|
769
|
-
{ flag: "w" },
|
|
770
|
-
);
|
|
967
|
+
await this.#writeMarker(toFull, target);
|
|
771
968
|
} catch (err) {
|
|
772
969
|
throw new ArchiveError(
|
|
773
970
|
"E_ARCHIVE_VISIBILITY_MOVE_FAILED",
|
|
774
|
-
`move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${(err
|
|
971
|
+
`move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${errnoCode(err) ?? "unknown"}). Target visibility is undefined.`,
|
|
775
972
|
{
|
|
776
973
|
hint: "Re-apply visibility via setVisibility() on the target path.",
|
|
777
974
|
},
|
|
778
975
|
);
|
|
779
976
|
}
|
|
977
|
+
}
|
|
978
|
+
if (capturedVisibility !== undefined) {
|
|
780
979
|
// Best-effort cleanup of the source sidecar — visibility is already
|
|
781
980
|
// preserved on the target side. A failure here leaves a stale
|
|
782
981
|
// sidecar pointing at the now-missing source file; benign.
|
|
@@ -786,17 +985,14 @@ export class LocalDriver implements StorageDriver {
|
|
|
786
985
|
// benign — source dir may be cleaned up by later operations.
|
|
787
986
|
}
|
|
788
987
|
}
|
|
789
|
-
// An explicit visibility override wins over the preserved value.
|
|
790
|
-
if (options?.visibility !== undefined) {
|
|
791
|
-
await this.setVisibility(to, options.visibility);
|
|
792
|
-
}
|
|
793
988
|
}
|
|
794
989
|
|
|
795
990
|
async deleteAll(prefix: string): Promise<void> {
|
|
796
991
|
// Walk the existing listing (already sidecar-aware + safe) and
|
|
797
992
|
// remove every match. delete() also drops each file's sidecar.
|
|
993
|
+
const normalized = normalizePrefix(prefix);
|
|
798
994
|
const paths: string[] = [];
|
|
799
|
-
for await (const entry of this.list(
|
|
995
|
+
for await (const entry of this.list(normalized)) {
|
|
800
996
|
paths.push(entry.path);
|
|
801
997
|
}
|
|
802
998
|
for (const p of paths) {
|
|
@@ -804,8 +1000,8 @@ export class LocalDriver implements StorageDriver {
|
|
|
804
1000
|
}
|
|
805
1001
|
// Prune the prefix directory itself when it is now empty, mirroring
|
|
806
1002
|
// flydrive's "the folder is deleted" behaviour. Best-effort.
|
|
807
|
-
|
|
808
|
-
|
|
1003
|
+
if (normalized !== "") {
|
|
1004
|
+
const dir = await this.#safePath(normalized);
|
|
809
1005
|
try {
|
|
810
1006
|
const stat = await fsp.stat(dir);
|
|
811
1007
|
if (stat.isDirectory() && (await fsp.readdir(dir)).length === 0) {
|
|
@@ -824,12 +1020,9 @@ export class LocalDriver implements StorageDriver {
|
|
|
824
1020
|
const recursive = options?.recursive ?? false;
|
|
825
1021
|
const files: DriveFile[] = [];
|
|
826
1022
|
const directories = new Map<string, DriveDirectory>();
|
|
1023
|
+
const given = normalizePrefix(prefix);
|
|
827
1024
|
const normalizedPrefix =
|
|
828
|
-
|
|
829
|
-
? ""
|
|
830
|
-
: prefix.endsWith("/")
|
|
831
|
-
? prefix
|
|
832
|
-
: `${prefix}/`;
|
|
1025
|
+
given === "" || given.endsWith("/") ? given : `${given}/`;
|
|
833
1026
|
for await (const entry of this.list(normalizedPrefix)) {
|
|
834
1027
|
if (recursive) {
|
|
835
1028
|
files.push(
|
|
@@ -852,6 +1045,9 @@ export class LocalDriver implements StorageDriver {
|
|
|
852
1045
|
}
|
|
853
1046
|
}
|
|
854
1047
|
}
|
|
1048
|
+
// Sorted by key, as upstream lists: the walk's order is the
|
|
1049
|
+
// filesystem's, which differs between machines.
|
|
1050
|
+
files.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
|
|
855
1051
|
return { objects: [...directories.values(), ...files] };
|
|
856
1052
|
}
|
|
857
1053
|
|
|
@@ -869,31 +1065,33 @@ export class LocalDriver implements StorageDriver {
|
|
|
869
1065
|
};
|
|
870
1066
|
}
|
|
871
1067
|
|
|
872
|
-
async *list(
|
|
873
|
-
|
|
874
|
-
//
|
|
875
|
-
//
|
|
876
|
-
|
|
1068
|
+
async *list(given: string): AsyncIterable<StorageEntry> {
|
|
1069
|
+
const prefix = normalizePrefix(given);
|
|
1070
|
+
// Start the walk at the deepest directory the prefix names, not at the
|
|
1071
|
+
// root: `avatars/42/` reads `avatars/42`, `avatars/4` reads
|
|
1072
|
+
// `avatars`. Walking the whole root and filtering afterwards cost the
|
|
1073
|
+
// size of the entire disk for every listing, however narrow.
|
|
1074
|
+
const slash = prefix.lastIndexOf("/");
|
|
1075
|
+
const dir = slash === -1 ? "" : prefix.slice(0, slash);
|
|
1076
|
+
const start = dir === "" ? this.#root : await this.#safePath(dir);
|
|
1077
|
+
let walk: fs.Dir;
|
|
877
1078
|
try {
|
|
878
|
-
entries
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
});
|
|
1079
|
+
// Read lazily: entries arrive as the walk reaches them instead of
|
|
1080
|
+
// the whole subtree being held in memory first. Links are listed,
|
|
1081
|
+
// not followed, so the walk stays inside the root.
|
|
1082
|
+
walk = await fsp.opendir(start, { recursive: true });
|
|
882
1083
|
} catch (err) {
|
|
883
|
-
|
|
1084
|
+
const code = errnoCode(err);
|
|
1085
|
+
// Nothing stored under that prefix, or it names a file.
|
|
1086
|
+
if (code === "ENOENT" || code === "ENOTDIR") return;
|
|
884
1087
|
throw err;
|
|
885
1088
|
}
|
|
886
|
-
for (const entry of
|
|
1089
|
+
for await (const entry of walk) {
|
|
887
1090
|
if (!entry.isFile()) continue;
|
|
888
|
-
|
|
889
|
-
// range already requires — the double cast that used to read it
|
|
890
|
-
// (and its `path` fallback for older shapes) is no longer buying
|
|
891
|
-
// anything.
|
|
892
|
-
const parent = entry.parentPath ?? this.#root;
|
|
893
|
-
const full = path.join(parent, entry.name);
|
|
1091
|
+
const full = path.join(entry.parentPath, entry.name);
|
|
894
1092
|
const rel = path.relative(this.#root, full).split(path.sep).join("/");
|
|
895
1093
|
// Exclude sidecars — implementation detail.
|
|
896
|
-
if (rel.endsWith(VISIBILITY_SIDECAR_SUFFIX)) continue;
|
|
1094
|
+
if (rel.toLowerCase().endsWith(VISIBILITY_SIDECAR_SUFFIX)) continue;
|
|
897
1095
|
if (!rel.startsWith(prefix)) continue;
|
|
898
1096
|
const stat = await fsp.stat(full);
|
|
899
1097
|
yield { path: rel, size: stat.size, lastModified: stat.mtime };
|
|
@@ -901,6 +1099,82 @@ export class LocalDriver implements StorageDriver {
|
|
|
901
1099
|
}
|
|
902
1100
|
}
|
|
903
1101
|
|
|
1102
|
+
/**
|
|
1103
|
+
* What a visibility marker held before a write replaced it, so a write that
|
|
1104
|
+
* fails can put it back. `unknown` — a marker that could not be read, a link
|
|
1105
|
+
* planted at its name — is never touched again.
|
|
1106
|
+
*/
|
|
1107
|
+
type MarkerSnapshot =
|
|
1108
|
+
| { readonly state: "absent" }
|
|
1109
|
+
| { readonly state: "present"; readonly bytes: Buffer }
|
|
1110
|
+
| { readonly state: "unknown" };
|
|
1111
|
+
|
|
1112
|
+
/** The marker of the file at `full` as it is now. */
|
|
1113
|
+
async function markerSnapshot(full: string): Promise<MarkerSnapshot> {
|
|
1114
|
+
try {
|
|
1115
|
+
const handle = await fsp.open(
|
|
1116
|
+
full + VISIBILITY_SIDECAR_SUFFIX,
|
|
1117
|
+
fs.constants.O_RDONLY | O_NOFOLLOW,
|
|
1118
|
+
);
|
|
1119
|
+
try {
|
|
1120
|
+
return { state: "present", bytes: await handle.readFile() };
|
|
1121
|
+
} finally {
|
|
1122
|
+
await handle.close();
|
|
1123
|
+
}
|
|
1124
|
+
} catch (err) {
|
|
1125
|
+
return errnoCode(err) === "ENOENT"
|
|
1126
|
+
? { state: "absent" }
|
|
1127
|
+
: { state: "unknown" };
|
|
1128
|
+
}
|
|
1129
|
+
}
|
|
1130
|
+
|
|
1131
|
+
/**
|
|
1132
|
+
* Put back the marker `snapshot` recorded. Best-effort, never throws: it runs
|
|
1133
|
+
* on a path that is already failing, and a restore that fails leaves the
|
|
1134
|
+
* private marker (or a damaged one, read as undetermined) — closed either way.
|
|
1135
|
+
*/
|
|
1136
|
+
async function restoreMarker(
|
|
1137
|
+
full: string,
|
|
1138
|
+
snapshot: MarkerSnapshot,
|
|
1139
|
+
): Promise<void> {
|
|
1140
|
+
const marker = full + VISIBILITY_SIDECAR_SUFFIX;
|
|
1141
|
+
try {
|
|
1142
|
+
if (snapshot.state === "absent") {
|
|
1143
|
+
await fsp.unlink(marker);
|
|
1144
|
+
} else if (snapshot.state === "present") {
|
|
1145
|
+
const handle = await fsp.open(
|
|
1146
|
+
marker,
|
|
1147
|
+
fs.constants.O_WRONLY | fs.constants.O_TRUNC | O_NOFOLLOW,
|
|
1148
|
+
);
|
|
1149
|
+
try {
|
|
1150
|
+
await handle.writeFile(snapshot.bytes);
|
|
1151
|
+
} finally {
|
|
1152
|
+
await handle.close();
|
|
1153
|
+
}
|
|
1154
|
+
}
|
|
1155
|
+
} catch {
|
|
1156
|
+
// Closed either way — see above.
|
|
1157
|
+
}
|
|
1158
|
+
}
|
|
1159
|
+
|
|
1160
|
+
/**
|
|
1161
|
+
* Remove a private object whose data write failed half-way: the data first,
|
|
1162
|
+
* then its marker — only once the data is gone, so the bytes are never left
|
|
1163
|
+
* without the marker that keeps them private. Never throws.
|
|
1164
|
+
*/
|
|
1165
|
+
async function discardPrivate(full: string): Promise<void> {
|
|
1166
|
+
try {
|
|
1167
|
+
await fsp.unlink(full);
|
|
1168
|
+
} catch (err) {
|
|
1169
|
+
if (errnoCode(err) !== "ENOENT") return;
|
|
1170
|
+
}
|
|
1171
|
+
try {
|
|
1172
|
+
await fsp.unlink(full + VISIBILITY_SIDECAR_SUFFIX);
|
|
1173
|
+
} catch {
|
|
1174
|
+
// An orphan marker serves nothing.
|
|
1175
|
+
}
|
|
1176
|
+
}
|
|
1177
|
+
|
|
904
1178
|
/**
|
|
905
1179
|
* Whether a path exists, without `existsSync` blocking the event loop.
|
|
906
1180
|
*
|
|
@@ -922,6 +1196,10 @@ function localPath(source: string | URL): string {
|
|
|
922
1196
|
return source instanceof URL ? url.fileURLToPath(source) : source;
|
|
923
1197
|
}
|
|
924
1198
|
|
|
1199
|
+
/**
|
|
1200
|
+
* The disk an application talks to: one driver behind it, and every key
|
|
1201
|
+
* normalised (see `keys.ts`) before that driver sees it, whatever the driver.
|
|
1202
|
+
*/
|
|
925
1203
|
export class StorageManager {
|
|
926
1204
|
#driver: StorageDriver;
|
|
927
1205
|
|
|
@@ -929,12 +1207,12 @@ export class StorageManager {
|
|
|
929
1207
|
this.#driver = driver;
|
|
930
1208
|
}
|
|
931
1209
|
|
|
932
|
-
put(
|
|
1210
|
+
async put(
|
|
933
1211
|
filePath: string,
|
|
934
1212
|
content: Buffer | string,
|
|
935
1213
|
options?: WriteOptions,
|
|
936
1214
|
): Promise<void> {
|
|
937
|
-
return this.#driver.put(filePath, content, options);
|
|
1215
|
+
return this.#driver.put(normalizeKey(filePath), content, options);
|
|
938
1216
|
}
|
|
939
1217
|
|
|
940
1218
|
/**
|
|
@@ -980,9 +1258,12 @@ export class StorageManager {
|
|
|
980
1258
|
destination: string,
|
|
981
1259
|
options?: WriteOptions,
|
|
982
1260
|
): Promise<void> {
|
|
1261
|
+
// Before the source is opened: a destination that is not a valid key
|
|
1262
|
+
// is refused without a descriptor to clean up.
|
|
1263
|
+
const key = normalizeKey(destination);
|
|
983
1264
|
const stream = fs.createReadStream(localPath(source));
|
|
984
1265
|
try {
|
|
985
|
-
await this.#driver.putStream(
|
|
1266
|
+
await this.#driver.putStream(key, stream, options);
|
|
986
1267
|
} catch (error) {
|
|
987
1268
|
// The driver can reject BEFORE reading a byte — a destination outside
|
|
988
1269
|
// the disk is rejected up front. The stream is then never consumed:
|
|
@@ -1016,102 +1297,107 @@ export class StorageManager {
|
|
|
1016
1297
|
await fs.promises.unlink(from);
|
|
1017
1298
|
}
|
|
1018
1299
|
|
|
1019
|
-
putStream(
|
|
1300
|
+
async putStream(
|
|
1020
1301
|
filePath: string,
|
|
1021
1302
|
readable: NodeJS.ReadableStream,
|
|
1022
1303
|
options?: PutStreamOptions,
|
|
1023
1304
|
): Promise<void> {
|
|
1024
|
-
return this.#driver.putStream(filePath, readable, options);
|
|
1305
|
+
return this.#driver.putStream(normalizeKey(filePath), readable, options);
|
|
1025
1306
|
}
|
|
1026
1307
|
|
|
1027
|
-
get(filePath: string): Promise<Buffer | null> {
|
|
1028
|
-
return this.#driver.get(filePath);
|
|
1308
|
+
async get(filePath: string): Promise<Buffer | null> {
|
|
1309
|
+
return this.#driver.get(normalizeKey(filePath));
|
|
1029
1310
|
}
|
|
1030
1311
|
|
|
1031
1312
|
/** Contents as a `Uint8Array`. Throws `E_ARCHIVE_NOT_FOUND` if absent. */
|
|
1032
|
-
getBytes(filePath: string): Promise<Uint8Array> {
|
|
1033
|
-
return this.#driver.getBytes(filePath);
|
|
1313
|
+
async getBytes(filePath: string): Promise<Uint8Array> {
|
|
1314
|
+
return this.#driver.getBytes(normalizeKey(filePath));
|
|
1034
1315
|
}
|
|
1035
1316
|
|
|
1036
1317
|
/** @deprecated AdonisJS Drive alias — use {@link StorageManager.getBytes}. */
|
|
1037
|
-
getArrayBuffer(filePath: string): Promise<Uint8Array> {
|
|
1038
|
-
return this.#driver.getBytes(filePath);
|
|
1318
|
+
async getArrayBuffer(filePath: string): Promise<Uint8Array> {
|
|
1319
|
+
return this.#driver.getBytes(normalizeKey(filePath));
|
|
1039
1320
|
}
|
|
1040
1321
|
|
|
1041
|
-
getStream(filePath: string): Promise<NodeJS.ReadableStream> {
|
|
1042
|
-
return this.#driver.getStream(filePath);
|
|
1322
|
+
async getStream(filePath: string): Promise<NodeJS.ReadableStream> {
|
|
1323
|
+
return this.#driver.getStream(normalizeKey(filePath));
|
|
1043
1324
|
}
|
|
1044
1325
|
|
|
1045
|
-
delete(filePath: string): Promise<boolean> {
|
|
1046
|
-
return this.#driver.delete(filePath);
|
|
1326
|
+
async delete(filePath: string): Promise<boolean> {
|
|
1327
|
+
return this.#driver.delete(normalizeKey(filePath));
|
|
1047
1328
|
}
|
|
1048
1329
|
|
|
1049
|
-
exists(filePath: string): Promise<boolean> {
|
|
1050
|
-
return this.#driver.exists(filePath);
|
|
1330
|
+
async exists(filePath: string): Promise<boolean> {
|
|
1331
|
+
return this.#driver.exists(normalizeKey(filePath));
|
|
1051
1332
|
}
|
|
1052
1333
|
|
|
1053
|
-
url(filePath: string): Promise<string> {
|
|
1054
|
-
return this.#driver.url(filePath);
|
|
1334
|
+
async url(filePath: string): Promise<string> {
|
|
1335
|
+
return this.#driver.url(normalizeKey(filePath));
|
|
1055
1336
|
}
|
|
1056
1337
|
|
|
1057
1338
|
/** AdonisJS Drive name for {@link url}. */
|
|
1058
|
-
getUrl(filePath: string): Promise<string> {
|
|
1059
|
-
return this.#driver.url(filePath);
|
|
1339
|
+
async getUrl(filePath: string): Promise<string> {
|
|
1340
|
+
return this.#driver.url(normalizeKey(filePath));
|
|
1060
1341
|
}
|
|
1061
1342
|
|
|
1062
1343
|
publicUrl(filePath: string): string {
|
|
1063
|
-
return this.#driver.publicUrl(filePath);
|
|
1344
|
+
return this.#driver.publicUrl(normalizeKey(filePath));
|
|
1064
1345
|
}
|
|
1065
1346
|
|
|
1066
1347
|
getSignedUrl(
|
|
1067
1348
|
filePath: string,
|
|
1068
1349
|
options?: SignedUrlOptions,
|
|
1069
1350
|
): string | Promise<string> {
|
|
1070
|
-
return this.#driver.getSignedUrl(filePath, options);
|
|
1351
|
+
return this.#driver.getSignedUrl(normalizeKey(filePath), options);
|
|
1071
1352
|
}
|
|
1072
1353
|
|
|
1073
1354
|
getSignedUploadUrl(
|
|
1074
1355
|
filePath: string,
|
|
1075
1356
|
options?: SignedUrlOptions,
|
|
1076
1357
|
): string | Promise<string> {
|
|
1077
|
-
return this.#driver.getSignedUploadUrl(filePath, options);
|
|
1358
|
+
return this.#driver.getSignedUploadUrl(normalizeKey(filePath), options);
|
|
1078
1359
|
}
|
|
1079
1360
|
|
|
1080
|
-
getMetadata(filePath: string): Promise<Metadata> {
|
|
1081
|
-
return this.#driver.getMetadata(filePath);
|
|
1361
|
+
async getMetadata(filePath: string): Promise<Metadata> {
|
|
1362
|
+
return this.#driver.getMetadata(normalizeKey(filePath));
|
|
1082
1363
|
}
|
|
1083
1364
|
|
|
1084
1365
|
/** AdonisJS Drive casing for {@link getMetadata}. */
|
|
1085
|
-
getMetaData(filePath: string): Promise<Metadata> {
|
|
1086
|
-
return this.#driver.getMetadata(filePath);
|
|
1366
|
+
async getMetaData(filePath: string): Promise<Metadata> {
|
|
1367
|
+
return this.#driver.getMetadata(normalizeKey(filePath));
|
|
1087
1368
|
}
|
|
1088
1369
|
|
|
1089
|
-
getVisibility(filePath: string): Promise<Visibility> {
|
|
1090
|
-
return this.#driver.getVisibility(filePath);
|
|
1370
|
+
async getVisibility(filePath: string): Promise<Visibility> {
|
|
1371
|
+
return this.#driver.getVisibility(normalizeKey(filePath));
|
|
1091
1372
|
}
|
|
1092
1373
|
|
|
1093
|
-
setVisibility(filePath: string, visibility: Visibility): Promise<void> {
|
|
1094
|
-
return this.#driver.setVisibility(filePath, visibility);
|
|
1374
|
+
async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
|
|
1375
|
+
return this.#driver.setVisibility(normalizeKey(filePath), visibility);
|
|
1095
1376
|
}
|
|
1096
1377
|
|
|
1097
|
-
copy(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
1098
|
-
return this.#driver.copy(from, to, options);
|
|
1378
|
+
async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
1379
|
+
return this.#driver.copy(normalizeKey(from), normalizeKey(to), options);
|
|
1099
1380
|
}
|
|
1100
1381
|
|
|
1101
|
-
move(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
1102
|
-
return this.#driver.move(from, to, options);
|
|
1382
|
+
async move(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
1383
|
+
return this.#driver.move(normalizeKey(from), normalizeKey(to), options);
|
|
1103
1384
|
}
|
|
1104
1385
|
|
|
1105
|
-
deleteAll(prefix: string): Promise<void> {
|
|
1106
|
-
return this.#driver.deleteAll(prefix);
|
|
1386
|
+
async deleteAll(prefix: string): Promise<void> {
|
|
1387
|
+
return this.#driver.deleteAll(normalizePrefix(prefix));
|
|
1107
1388
|
}
|
|
1108
1389
|
|
|
1109
1390
|
list(prefix: string): AsyncIterable<StorageEntry> {
|
|
1110
|
-
|
|
1391
|
+
// Validated now, not on the first iteration: a refused prefix is the
|
|
1392
|
+
// caller's mistake and should surface where the call was made.
|
|
1393
|
+
return this.#driver.list(normalizePrefix(prefix));
|
|
1111
1394
|
}
|
|
1112
1395
|
|
|
1113
1396
|
/** AdonisJS Drive `listAll` — paged {@link DriveFile}/{@link DriveDirectory}. */
|
|
1114
|
-
listAll(
|
|
1115
|
-
|
|
1397
|
+
async listAll(
|
|
1398
|
+
prefix: string,
|
|
1399
|
+
options?: ListAllOptions,
|
|
1400
|
+
): Promise<ListAllResult> {
|
|
1401
|
+
return this.#driver.listAll(normalizePrefix(prefix), options);
|
|
1116
1402
|
}
|
|
1117
1403
|
}
|