@c9up/archive 0.1.6 → 0.1.7
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 +6 -0
- package/dist/ArchiveProvider.d.ts.map +1 -1
- package/dist/ArchiveProvider.js +33 -7
- package/dist/ArchiveProvider.js.map +1 -1
- package/dist/DriveManager.d.ts +80 -0
- package/dist/DriveManager.d.ts.map +1 -0
- package/dist/DriveManager.js +102 -0
- package/dist/DriveManager.js.map +1 -0
- package/dist/GcsDriver.d.ts +14 -4
- package/dist/GcsDriver.d.ts.map +1 -1
- package/dist/GcsDriver.js +126 -15
- package/dist/GcsDriver.js.map +1 -1
- package/dist/S3Driver.d.ts +14 -4
- package/dist/S3Driver.d.ts.map +1 -1
- package/dist/S3Driver.js +268 -15
- package/dist/S3Driver.js.map +1 -1
- package/dist/StorageManager.d.ts +124 -18
- package/dist/StorageManager.d.ts.map +1 -1
- package/dist/StorageManager.js +139 -13
- package/dist/StorageManager.js.map +1 -1
- package/dist/expiry.d.ts +7 -0
- package/dist/expiry.d.ts.map +1 -1
- package/dist/expiry.js +47 -0
- package/dist/expiry.js.map +1 -1
- package/dist/index.d.ts +16 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +13 -4
- package/dist/index.js.map +1 -1
- package/dist/objects.d.ts +50 -0
- package/dist/objects.d.ts.map +1 -0
- package/dist/objects.js +77 -0
- package/dist/objects.js.map +1 -0
- package/dist/testing/FakeStorage.d.ts +43 -4
- package/dist/testing/FakeStorage.d.ts.map +1 -1
- package/dist/testing/FakeStorage.js +153 -12
- package/dist/testing/FakeStorage.js.map +1 -1
- package/package.json +2 -1
- package/src/ArchiveProvider.ts +49 -9
- package/src/DriveManager.ts +151 -0
- package/src/GcsDriver.ts +166 -15
- package/src/S3Driver.ts +317 -15
- package/src/StorageManager.ts +284 -25
- package/src/expiry.ts +52 -0
- package/src/index.ts +26 -5
- package/src/objects.ts +92 -0
- package/src/testing/FakeStorage.ts +191 -12
package/src/StorageManager.ts
CHANGED
|
@@ -9,13 +9,63 @@ import * as fs from "node:fs";
|
|
|
9
9
|
import * as path from "node:path";
|
|
10
10
|
import { pipeline } from "node:stream/promises";
|
|
11
11
|
import { ArchiveError } from "./errors.js";
|
|
12
|
-
import {
|
|
12
|
+
import {
|
|
13
|
+
assertValidExpiry,
|
|
14
|
+
DEFAULT_EXPIRES_IN,
|
|
15
|
+
parseExpiry,
|
|
16
|
+
} from "./expiry.js";
|
|
13
17
|
import { inferMimeType } from "./mime-types.js";
|
|
18
|
+
import { DriveDirectory, DriveFile } from "./objects.js";
|
|
19
|
+
|
|
20
|
+
export { DriveDirectory, DriveFile } from "./objects.js";
|
|
14
21
|
|
|
15
22
|
/** Options for {@link StorageDriver.getSignedUrl}. */
|
|
16
23
|
export interface SignedUrlOptions {
|
|
17
|
-
/**
|
|
18
|
-
|
|
24
|
+
/**
|
|
25
|
+
* URL lifetime. Either a number of seconds or an AdonisJS-style
|
|
26
|
+
* duration string (`'30mins'`, `'7 days'`, `'1h'`). Default: 300
|
|
27
|
+
* (5 minutes). Bounds after parsing: 1–604800.
|
|
28
|
+
*/
|
|
29
|
+
expiresIn?: number | string;
|
|
30
|
+
/** Sets the response `Content-Type` served with the signed URL (cloud drivers). */
|
|
31
|
+
contentType?: string;
|
|
32
|
+
/** Sets the response `Content-Disposition` served with the signed URL (cloud drivers). */
|
|
33
|
+
contentDisposition?: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Options accepted by the write operations (`put`/`putStream`) and by
|
|
38
|
+
* `copy`/`move`. AdonisJS Drive `WriteOptions` parity. Cloud drivers map
|
|
39
|
+
* these onto object metadata headers; the LocalDriver honours only
|
|
40
|
+
* `visibility` (the rest have no filesystem equivalent).
|
|
41
|
+
*/
|
|
42
|
+
export interface WriteOptions {
|
|
43
|
+
/** Visibility to apply to the written / copied object. */
|
|
44
|
+
visibility?: Visibility;
|
|
45
|
+
/** `Content-Type` metadata. Falls back to extension-based inference. */
|
|
46
|
+
contentType?: string;
|
|
47
|
+
/** `Cache-Control` metadata (cloud drivers). */
|
|
48
|
+
cacheControl?: string;
|
|
49
|
+
/** `Content-Disposition` metadata (cloud drivers). */
|
|
50
|
+
contentDisposition?: string;
|
|
51
|
+
/** Declared byte length. Used by S3 to choose single-PUT vs multipart. */
|
|
52
|
+
contentLength?: number;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Result shape of {@link StorageDriver.listAll} — AdonisJS Drive parity. */
|
|
56
|
+
export interface ListAllResult {
|
|
57
|
+
/** Continuation token to fetch the next page (cloud drivers only). */
|
|
58
|
+
paginationToken?: string;
|
|
59
|
+
/** Files and (non-recursive only) directories under the prefix. */
|
|
60
|
+
objects: Iterable<DriveFile | DriveDirectory>;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Options accepted by {@link StorageDriver.listAll}. */
|
|
64
|
+
export interface ListAllOptions {
|
|
65
|
+
/** Recurse into sub-prefixes. When true, no directories are yielded. */
|
|
66
|
+
recursive?: boolean;
|
|
67
|
+
/** Continuation token from a previous page (cloud drivers only). */
|
|
68
|
+
paginationToken?: string;
|
|
19
69
|
}
|
|
20
70
|
|
|
21
71
|
/** Options for {@link StorageDriver.putStream}. */
|
|
@@ -55,9 +105,13 @@ export interface StorageEntry {
|
|
|
55
105
|
export interface Metadata {
|
|
56
106
|
/** Size in bytes. */
|
|
57
107
|
size: number;
|
|
108
|
+
/** AdonisJS `ObjectMetaData` alias of {@link Metadata.size}. Same value. */
|
|
109
|
+
contentLength: number;
|
|
58
110
|
/** Content type. Driver-inferred for Local (extension-based), server-
|
|
59
111
|
* reported for S3. Falls back to `application/octet-stream`. */
|
|
60
112
|
mimeType: string;
|
|
113
|
+
/** AdonisJS `ObjectMetaData` alias of {@link Metadata.mimeType}. Same value. */
|
|
114
|
+
contentType: string;
|
|
61
115
|
/** Last-modified timestamp as a `Date` — not a string, not epoch ms. */
|
|
62
116
|
lastModified: Date;
|
|
63
117
|
/** Strong or weak ETag with surrounding quotes stripped. `W/` prefix
|
|
@@ -68,16 +122,20 @@ export interface Metadata {
|
|
|
68
122
|
}
|
|
69
123
|
|
|
70
124
|
/**
|
|
71
|
-
* StorageDriver contract —
|
|
125
|
+
* StorageDriver contract — v1.1 (Epic 43, extended for AdonisJS Drive /
|
|
126
|
+
* flydrive parity 2026-07-06).
|
|
72
127
|
*
|
|
73
128
|
* Driver authors implement this interface verbatim. The interface is treated
|
|
74
|
-
* as a stable contract:
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
* method + the old one delegating, deprecated for ≥1 epic.
|
|
129
|
+
* as a stable contract: methods are added only to track upstream Drive
|
|
130
|
+
* parity. Method signatures never change in-place — a renamed method ships as
|
|
131
|
+
* a new method + the old one delegating, deprecated for ≥1 epic.
|
|
78
132
|
*/
|
|
79
133
|
export interface StorageDriver {
|
|
80
|
-
put(
|
|
134
|
+
put(
|
|
135
|
+
filePath: string,
|
|
136
|
+
content: Buffer | string,
|
|
137
|
+
options?: WriteOptions,
|
|
138
|
+
): Promise<void>;
|
|
81
139
|
/**
|
|
82
140
|
* Upload from a readable stream. Local pipes to disk; S3 uses
|
|
83
141
|
* single-PUT if `contentLength ≤ 5 MiB`, otherwise multipart.
|
|
@@ -87,7 +145,22 @@ export interface StorageDriver {
|
|
|
87
145
|
readable: NodeJS.ReadableStream,
|
|
88
146
|
options?: PutStreamOptions,
|
|
89
147
|
): Promise<void>;
|
|
148
|
+
/**
|
|
149
|
+
* Raw contents as a `Buffer`, or `null` when the object is absent.
|
|
150
|
+
*
|
|
151
|
+
* DIVERGENCE from AdonisJS Drive (documented, deliberate): Adonis
|
|
152
|
+
* `get()` returns a UTF-8 `string` and throws on absence. Ream keeps
|
|
153
|
+
* the binary-safe `Buffer | null` shape as a superset. Use
|
|
154
|
+
* {@link StorageDriver.getBytes} for the Adonis-shaped, throw-on-
|
|
155
|
+
* absence accessor.
|
|
156
|
+
*/
|
|
90
157
|
get(filePath: string): Promise<Buffer | null>;
|
|
158
|
+
/**
|
|
159
|
+
* Contents as a `Uint8Array`. AdonisJS Drive parity. Throws
|
|
160
|
+
* `ARCHIVE_NOT_FOUND` when the object is absent (unlike {@link get},
|
|
161
|
+
* a byte accessor can't express absence as a value).
|
|
162
|
+
*/
|
|
163
|
+
getBytes(filePath: string): Promise<Uint8Array>;
|
|
91
164
|
/**
|
|
92
165
|
* Download as a readable stream. Throws `ARCHIVE_NOT_FOUND` when
|
|
93
166
|
* the object is missing — streams can't express absence as a value.
|
|
@@ -117,11 +190,26 @@ export interface StorageDriver {
|
|
|
117
190
|
filePath: string,
|
|
118
191
|
options?: SignedUrlOptions,
|
|
119
192
|
): string | Promise<string>;
|
|
193
|
+
/**
|
|
194
|
+
* Return a time-boxed URL that grants **write** (PUT) access, letting
|
|
195
|
+
* a client upload directly to the backend. AdonisJS Drive parity.
|
|
196
|
+
* Cloud-only — the LocalDriver has no presigned-upload equivalent and
|
|
197
|
+
* throws `ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED`.
|
|
198
|
+
*/
|
|
199
|
+
getSignedUploadUrl(
|
|
200
|
+
filePath: string,
|
|
201
|
+
options?: SignedUrlOptions,
|
|
202
|
+
): string | Promise<string>;
|
|
120
203
|
/**
|
|
121
204
|
* Resolve object metadata. Throws `ArchiveError('ARCHIVE_NOT_FOUND', ...)`
|
|
122
205
|
* when the object does not exist.
|
|
123
206
|
*/
|
|
124
207
|
getMetadata(filePath: string): Promise<Metadata>;
|
|
208
|
+
/**
|
|
209
|
+
* Resolve the `public` / `private` visibility of an object on its own,
|
|
210
|
+
* without a full metadata round-trip. AdonisJS Drive parity.
|
|
211
|
+
*/
|
|
212
|
+
getVisibility(filePath: string): Promise<Visibility>;
|
|
125
213
|
/**
|
|
126
214
|
* Set `public` / `private` visibility. Idempotent — re-applying the
|
|
127
215
|
* same visibility succeeds silently.
|
|
@@ -130,22 +218,36 @@ export interface StorageDriver {
|
|
|
130
218
|
/**
|
|
131
219
|
* Duplicate an object. Throws `ARCHIVE_NOT_FOUND` if `from` is
|
|
132
220
|
* missing. Target is overwritten if it exists. Visibility is NOT
|
|
133
|
-
* carried over — the new object
|
|
221
|
+
* carried over unless `options.visibility` is passed — the new object
|
|
222
|
+
* takes default visibility.
|
|
134
223
|
*/
|
|
135
|
-
copy(from: string, to: string): Promise<void>;
|
|
224
|
+
copy(from: string, to: string, options?: WriteOptions): Promise<void>;
|
|
136
225
|
/**
|
|
137
226
|
* Relocate an object. Equivalent to `copy` + `delete` on cloud
|
|
138
227
|
* drivers (non-atomic between the two steps); atomic `rename` on
|
|
139
228
|
* Local. Visibility IS preserved because identity is preserved.
|
|
140
229
|
*/
|
|
141
|
-
move(from: string, to: string): Promise<void>;
|
|
230
|
+
move(from: string, to: string, options?: WriteOptions): Promise<void>;
|
|
231
|
+
/**
|
|
232
|
+
* Delete every object whose path starts with `prefix`. Local removes
|
|
233
|
+
* the matching files (and prunes emptied directories); S3 batch-deletes;
|
|
234
|
+
* GCS deletes per object. AdonisJS Drive parity.
|
|
235
|
+
*/
|
|
236
|
+
deleteAll(prefix: string): Promise<void>;
|
|
142
237
|
/**
|
|
143
238
|
* Yield one {@link StorageEntry} per object whose path starts with
|
|
144
239
|
* `prefix`. Pagination (S3/GCS) and filesystem walk (Local) happen
|
|
145
240
|
* lazily — callers can `break` early and no further requests are
|
|
146
|
-
* issued.
|
|
241
|
+
* issued. Ream superset — kept alongside the Adonis-shaped
|
|
242
|
+
* {@link StorageDriver.listAll}.
|
|
147
243
|
*/
|
|
148
244
|
list(prefix: string): AsyncIterable<StorageEntry>;
|
|
245
|
+
/**
|
|
246
|
+
* AdonisJS Drive `listAll`: a single page of {@link DriveFile} (and,
|
|
247
|
+
* when non-recursive, {@link DriveDirectory}) entries plus an optional
|
|
248
|
+
* pagination token.
|
|
249
|
+
*/
|
|
250
|
+
listAll(prefix: string, options?: ListAllOptions): Promise<ListAllResult>;
|
|
149
251
|
}
|
|
150
252
|
|
|
151
253
|
export interface LocalDriverOptions {
|
|
@@ -238,13 +340,34 @@ export class LocalDriver implements StorageDriver {
|
|
|
238
340
|
return full;
|
|
239
341
|
}
|
|
240
342
|
|
|
241
|
-
async put(
|
|
343
|
+
async put(
|
|
344
|
+
filePath: string,
|
|
345
|
+
content: Buffer | string,
|
|
346
|
+
options?: WriteOptions,
|
|
347
|
+
): Promise<void> {
|
|
242
348
|
const full = this.#safePath(filePath);
|
|
243
349
|
const dir = path.dirname(full);
|
|
244
350
|
if (!fs.existsSync(dir)) {
|
|
245
351
|
fs.mkdirSync(dir, { recursive: true });
|
|
246
352
|
}
|
|
247
353
|
fs.writeFileSync(full, content);
|
|
354
|
+
// Only `visibility` has a filesystem-equivalent (the sidecar).
|
|
355
|
+
// contentType/cacheControl/... have no local meaning.
|
|
356
|
+
if (options?.visibility !== undefined) {
|
|
357
|
+
await this.setVisibility(filePath, options.visibility);
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
async getBytes(filePath: string): Promise<Uint8Array> {
|
|
362
|
+
const buf = await this.get(filePath);
|
|
363
|
+
if (buf === null) {
|
|
364
|
+
throw new ArchiveError(
|
|
365
|
+
"ARCHIVE_NOT_FOUND",
|
|
366
|
+
`File does not exist at path '${filePath}'`,
|
|
367
|
+
{ hint: "Confirm the path and that the file was put() first." },
|
|
368
|
+
);
|
|
369
|
+
}
|
|
370
|
+
return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
|
|
248
371
|
}
|
|
249
372
|
|
|
250
373
|
async putStream(
|
|
@@ -346,15 +469,22 @@ export class LocalDriver implements StorageDriver {
|
|
|
346
469
|
const etagBody = createHash("sha1")
|
|
347
470
|
.update(`${stat.ino}-${stat.size}-${stat.mtimeMs}`)
|
|
348
471
|
.digest("hex");
|
|
472
|
+
const mimeType = inferMimeType(path.extname(filePath).toLowerCase());
|
|
349
473
|
return {
|
|
350
474
|
size: stat.size,
|
|
351
|
-
|
|
475
|
+
contentLength: stat.size,
|
|
476
|
+
mimeType,
|
|
477
|
+
contentType: mimeType,
|
|
352
478
|
lastModified: stat.mtime,
|
|
353
479
|
etag: `W/"${etagBody}"`,
|
|
354
480
|
visibility: this.#readVisibility(filePath),
|
|
355
481
|
};
|
|
356
482
|
}
|
|
357
483
|
|
|
484
|
+
async getVisibility(filePath: string): Promise<Visibility> {
|
|
485
|
+
return this.#readVisibility(filePath);
|
|
486
|
+
}
|
|
487
|
+
|
|
358
488
|
async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
|
|
359
489
|
const full = this.#safePath(filePath);
|
|
360
490
|
if (!fs.existsSync(full)) {
|
|
@@ -412,7 +542,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
412
542
|
// can never be served — `storage.get()` would reject it later via
|
|
413
543
|
// `#safePath`, but signing-time errors are easier to diagnose.
|
|
414
544
|
this.#safePath(filePath);
|
|
415
|
-
const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
|
|
545
|
+
const expiresIn = parseExpiry(options?.expiresIn ?? DEFAULT_EXPIRES_IN);
|
|
416
546
|
assertValidExpiry(expiresIn);
|
|
417
547
|
const secret = this.#signingSecret;
|
|
418
548
|
if (secret === null) {
|
|
@@ -433,6 +563,21 @@ export class LocalDriver implements StorageDriver {
|
|
|
433
563
|
return `${this.publicUrl(filePath)}?exp=${exp}&sig=${sig}`;
|
|
434
564
|
}
|
|
435
565
|
|
|
566
|
+
/**
|
|
567
|
+
* The LocalDriver serves uploads through the app (not a presigned
|
|
568
|
+
* PUT to an object store), so there is no presigned-upload URL to
|
|
569
|
+
* hand out. Fail loudly rather than return an unusable value.
|
|
570
|
+
*/
|
|
571
|
+
getSignedUploadUrl(_filePath: string, _options?: SignedUrlOptions): string {
|
|
572
|
+
throw new ArchiveError(
|
|
573
|
+
"ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED",
|
|
574
|
+
"LocalDriver does not support presigned upload URLs",
|
|
575
|
+
{
|
|
576
|
+
hint: "Presigned uploads are an S3/GCS feature. For local storage, upload through your app's HTTP handler.",
|
|
577
|
+
},
|
|
578
|
+
);
|
|
579
|
+
}
|
|
580
|
+
|
|
436
581
|
/**
|
|
437
582
|
* @internal Used by the signed-route middleware to re-compute the
|
|
438
583
|
* HMAC server-side. Not part of the public `StorageDriver` contract.
|
|
@@ -441,7 +586,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
441
586
|
return this.#signingSecret;
|
|
442
587
|
}
|
|
443
588
|
|
|
444
|
-
async copy(from: string, to: string): Promise<void> {
|
|
589
|
+
async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
445
590
|
const fromFull = this.#safePath(from);
|
|
446
591
|
const toFull = this.#safePath(to);
|
|
447
592
|
if (!fs.existsSync(fromFull)) {
|
|
@@ -455,10 +600,13 @@ export class LocalDriver implements StorageDriver {
|
|
|
455
600
|
if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
|
|
456
601
|
fs.copyFileSync(fromFull, toFull);
|
|
457
602
|
// Intentionally do NOT copy the visibility sidecar — new object
|
|
458
|
-
// takes default visibility
|
|
603
|
+
// takes default visibility unless the caller asks otherwise.
|
|
604
|
+
if (options?.visibility !== undefined) {
|
|
605
|
+
await this.setVisibility(to, options.visibility);
|
|
606
|
+
}
|
|
459
607
|
}
|
|
460
608
|
|
|
461
|
-
async move(from: string, to: string): Promise<void> {
|
|
609
|
+
async move(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
462
610
|
const fromFull = this.#safePath(from);
|
|
463
611
|
const toFull = this.#safePath(to);
|
|
464
612
|
if (!fs.existsSync(fromFull)) {
|
|
@@ -524,6 +672,83 @@ export class LocalDriver implements StorageDriver {
|
|
|
524
672
|
}
|
|
525
673
|
}
|
|
526
674
|
}
|
|
675
|
+
// An explicit visibility override wins over the preserved value.
|
|
676
|
+
if (options?.visibility !== undefined) {
|
|
677
|
+
await this.setVisibility(to, options.visibility);
|
|
678
|
+
}
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
async deleteAll(prefix: string): Promise<void> {
|
|
682
|
+
// Walk the existing listing (already sidecar-aware + safe) and
|
|
683
|
+
// remove every match. delete() also drops each file's sidecar.
|
|
684
|
+
const paths: string[] = [];
|
|
685
|
+
for await (const entry of this.list(prefix)) {
|
|
686
|
+
paths.push(entry.path);
|
|
687
|
+
}
|
|
688
|
+
for (const p of paths) {
|
|
689
|
+
await this.delete(p);
|
|
690
|
+
}
|
|
691
|
+
// Prune the prefix directory itself when it is now empty, mirroring
|
|
692
|
+
// flydrive's "the folder is deleted" behaviour. Best-effort.
|
|
693
|
+
const dir = this.#safePath(prefix);
|
|
694
|
+
if (dir !== this.#root && fs.existsSync(dir)) {
|
|
695
|
+
try {
|
|
696
|
+
const stat = fs.statSync(dir);
|
|
697
|
+
if (stat.isDirectory() && fs.readdirSync(dir).length === 0) {
|
|
698
|
+
fs.rmdirSync(dir);
|
|
699
|
+
}
|
|
700
|
+
} catch {
|
|
701
|
+
// benign — leave non-empty / vanished dirs alone.
|
|
702
|
+
}
|
|
703
|
+
}
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
async listAll(
|
|
707
|
+
prefix: string,
|
|
708
|
+
options?: ListAllOptions,
|
|
709
|
+
): Promise<ListAllResult> {
|
|
710
|
+
const recursive = options?.recursive ?? false;
|
|
711
|
+
const files: DriveFile[] = [];
|
|
712
|
+
const directories = new Map<string, DriveDirectory>();
|
|
713
|
+
const normalizedPrefix =
|
|
714
|
+
prefix === "" || prefix === "/"
|
|
715
|
+
? ""
|
|
716
|
+
: prefix.endsWith("/")
|
|
717
|
+
? prefix
|
|
718
|
+
: `${prefix}/`;
|
|
719
|
+
for await (const entry of this.list(normalizedPrefix)) {
|
|
720
|
+
if (recursive) {
|
|
721
|
+
files.push(new DriveFile(entry.path, this, this.#entryMetadata(entry)));
|
|
722
|
+
continue;
|
|
723
|
+
}
|
|
724
|
+
// Non-recursive: collapse anything below the immediate level
|
|
725
|
+
// into a DriveDirectory marker.
|
|
726
|
+
const rest = entry.path.slice(normalizedPrefix.length);
|
|
727
|
+
const slash = rest.indexOf("/");
|
|
728
|
+
if (slash === -1) {
|
|
729
|
+
files.push(new DriveFile(entry.path, this, this.#entryMetadata(entry)));
|
|
730
|
+
} else {
|
|
731
|
+
const dirPrefix = normalizedPrefix + rest.slice(0, slash);
|
|
732
|
+
if (!directories.has(dirPrefix)) {
|
|
733
|
+
directories.set(dirPrefix, new DriveDirectory(dirPrefix));
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
}
|
|
737
|
+
return { objects: [...directories.values(), ...files] };
|
|
738
|
+
}
|
|
739
|
+
|
|
740
|
+
/** Build a metadata snapshot from a cheap `list()` entry (no extra stat). */
|
|
741
|
+
#entryMetadata(entry: StorageEntry): Metadata {
|
|
742
|
+
const mimeType = inferMimeType(path.extname(entry.path).toLowerCase());
|
|
743
|
+
return {
|
|
744
|
+
size: entry.size,
|
|
745
|
+
contentLength: entry.size,
|
|
746
|
+
mimeType,
|
|
747
|
+
contentType: mimeType,
|
|
748
|
+
lastModified: entry.lastModified,
|
|
749
|
+
etag: "",
|
|
750
|
+
visibility: this.#readVisibility(entry.path),
|
|
751
|
+
};
|
|
527
752
|
}
|
|
528
753
|
|
|
529
754
|
async *list(prefix: string): AsyncIterable<StorageEntry> {
|
|
@@ -562,8 +787,12 @@ export class StorageManager {
|
|
|
562
787
|
this.#driver = driver;
|
|
563
788
|
}
|
|
564
789
|
|
|
565
|
-
put(
|
|
566
|
-
|
|
790
|
+
put(
|
|
791
|
+
filePath: string,
|
|
792
|
+
content: Buffer | string,
|
|
793
|
+
options?: WriteOptions,
|
|
794
|
+
): Promise<void> {
|
|
795
|
+
return this.#driver.put(filePath, content, options);
|
|
567
796
|
}
|
|
568
797
|
|
|
569
798
|
putStream(
|
|
@@ -578,6 +807,16 @@ export class StorageManager {
|
|
|
578
807
|
return this.#driver.get(filePath);
|
|
579
808
|
}
|
|
580
809
|
|
|
810
|
+
/** Contents as a `Uint8Array`. Throws `ARCHIVE_NOT_FOUND` if absent. */
|
|
811
|
+
getBytes(filePath: string): Promise<Uint8Array> {
|
|
812
|
+
return this.#driver.getBytes(filePath);
|
|
813
|
+
}
|
|
814
|
+
|
|
815
|
+
/** @deprecated AdonisJS Drive alias — use {@link StorageManager.getBytes}. */
|
|
816
|
+
getArrayBuffer(filePath: string): Promise<Uint8Array> {
|
|
817
|
+
return this.#driver.getBytes(filePath);
|
|
818
|
+
}
|
|
819
|
+
|
|
581
820
|
getStream(filePath: string): Promise<NodeJS.ReadableStream> {
|
|
582
821
|
return this.#driver.getStream(filePath);
|
|
583
822
|
}
|
|
@@ -610,6 +849,13 @@ export class StorageManager {
|
|
|
610
849
|
return this.#driver.getSignedUrl(filePath, options);
|
|
611
850
|
}
|
|
612
851
|
|
|
852
|
+
getSignedUploadUrl(
|
|
853
|
+
filePath: string,
|
|
854
|
+
options?: SignedUrlOptions,
|
|
855
|
+
): string | Promise<string> {
|
|
856
|
+
return this.#driver.getSignedUploadUrl(filePath, options);
|
|
857
|
+
}
|
|
858
|
+
|
|
613
859
|
getMetadata(filePath: string): Promise<Metadata> {
|
|
614
860
|
return this.#driver.getMetadata(filePath);
|
|
615
861
|
}
|
|
@@ -619,19 +865,32 @@ export class StorageManager {
|
|
|
619
865
|
return this.#driver.getMetadata(filePath);
|
|
620
866
|
}
|
|
621
867
|
|
|
868
|
+
getVisibility(filePath: string): Promise<Visibility> {
|
|
869
|
+
return this.#driver.getVisibility(filePath);
|
|
870
|
+
}
|
|
871
|
+
|
|
622
872
|
setVisibility(filePath: string, visibility: Visibility): Promise<void> {
|
|
623
873
|
return this.#driver.setVisibility(filePath, visibility);
|
|
624
874
|
}
|
|
625
875
|
|
|
626
|
-
copy(from: string, to: string): Promise<void> {
|
|
627
|
-
return this.#driver.copy(from, to);
|
|
876
|
+
copy(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
877
|
+
return this.#driver.copy(from, to, options);
|
|
878
|
+
}
|
|
879
|
+
|
|
880
|
+
move(from: string, to: string, options?: WriteOptions): Promise<void> {
|
|
881
|
+
return this.#driver.move(from, to, options);
|
|
628
882
|
}
|
|
629
883
|
|
|
630
|
-
|
|
631
|
-
return this.#driver.
|
|
884
|
+
deleteAll(prefix: string): Promise<void> {
|
|
885
|
+
return this.#driver.deleteAll(prefix);
|
|
632
886
|
}
|
|
633
887
|
|
|
634
888
|
list(prefix: string): AsyncIterable<StorageEntry> {
|
|
635
889
|
return this.#driver.list(prefix);
|
|
636
890
|
}
|
|
891
|
+
|
|
892
|
+
/** AdonisJS Drive `listAll` — paged {@link DriveFile}/{@link DriveDirectory}. */
|
|
893
|
+
listAll(prefix: string, options?: ListAllOptions): Promise<ListAllResult> {
|
|
894
|
+
return this.#driver.listAll(prefix, options);
|
|
895
|
+
}
|
|
637
896
|
}
|
package/src/expiry.ts
CHANGED
|
@@ -12,6 +12,58 @@ export const DEFAULT_EXPIRES_IN = 300; // 5 minutes
|
|
|
12
12
|
/** Maximum allowed expiry (AWS SigV4 cap). */
|
|
13
13
|
export const MAX_EXPIRES_IN = 604_800; // 7 days
|
|
14
14
|
|
|
15
|
+
/**
|
|
16
|
+
* Multipliers (in seconds) for the human-friendly duration suffixes
|
|
17
|
+
* accepted by {@link parseExpiry}. Mirrors the units understood by
|
|
18
|
+
* AdonisJS Drive's `string.seconds.parse` helper.
|
|
19
|
+
*/
|
|
20
|
+
const UNIT_SECONDS: Record<string, number> = {
|
|
21
|
+
s: 1,
|
|
22
|
+
sec: 1,
|
|
23
|
+
secs: 1,
|
|
24
|
+
second: 1,
|
|
25
|
+
seconds: 1,
|
|
26
|
+
m: 60,
|
|
27
|
+
min: 60,
|
|
28
|
+
mins: 60,
|
|
29
|
+
minute: 60,
|
|
30
|
+
minutes: 60,
|
|
31
|
+
h: 3600,
|
|
32
|
+
hr: 3600,
|
|
33
|
+
hrs: 3600,
|
|
34
|
+
hour: 3600,
|
|
35
|
+
hours: 3600,
|
|
36
|
+
d: 86_400,
|
|
37
|
+
day: 86_400,
|
|
38
|
+
days: 86_400,
|
|
39
|
+
w: 604_800,
|
|
40
|
+
week: 604_800,
|
|
41
|
+
weeks: 604_800,
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Normalise a signed-URL `expiresIn` into a number of seconds. Accepts
|
|
46
|
+
* either a raw number of seconds (returned as-is) or a human-friendly
|
|
47
|
+
* duration string such as `'30mins'`, `'7 days'`, `'1h'` — AdonisJS
|
|
48
|
+
* Drive parity. Unrecognised strings throw `ARCHIVE_INVALID_EXPIRY`.
|
|
49
|
+
*/
|
|
50
|
+
export function parseExpiry(expiresIn: number | string): number {
|
|
51
|
+
if (typeof expiresIn === "number") return expiresIn;
|
|
52
|
+
const match = /^\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*$/i.exec(expiresIn);
|
|
53
|
+
const unitKey = match?.[2]?.toLowerCase() ?? "";
|
|
54
|
+
const multiplier = unitKey === "" ? 1 : UNIT_SECONDS[unitKey];
|
|
55
|
+
if (match === undefined || match === null || multiplier === undefined) {
|
|
56
|
+
throw new ArchiveError(
|
|
57
|
+
"ARCHIVE_INVALID_EXPIRY",
|
|
58
|
+
`Signed-URL expiresIn string '${expiresIn}' could not be parsed`,
|
|
59
|
+
{
|
|
60
|
+
hint: "Use a number of seconds, or a duration like '30mins', '1h', '7 days'.",
|
|
61
|
+
},
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
return Math.round(Number.parseFloat(match[1]) * multiplier);
|
|
65
|
+
}
|
|
66
|
+
|
|
15
67
|
/**
|
|
16
68
|
* Reject non-finite, zero, negative, or out-of-range expiries. Throws
|
|
17
69
|
* `ARCHIVE_INVALID_EXPIRY` so callers get a typed error with a hint.
|
package/src/index.ts
CHANGED
|
@@ -4,18 +4,28 @@
|
|
|
4
4
|
* Drivers:
|
|
5
5
|
* - LocalDriver (filesystem)
|
|
6
6
|
* - S3Driver (S3 / R2 / MinIO via SigV4)
|
|
7
|
+
* - GcsDriver (Google Cloud Storage)
|
|
7
8
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
9
|
+
* A `DriveManager` provides AdonisJS Drive-style multi-disk resolution
|
|
10
|
+
* (`use(name?)`), plus a `StaticMiddleware` for serving files over HTTP
|
|
11
|
+
* and a signed-route handler for serving HMAC-signed Local URLs.
|
|
10
12
|
*/
|
|
11
13
|
|
|
12
14
|
export type { ArchiveConfig } from "./ArchiveProvider.js";
|
|
15
|
+
export {
|
|
16
|
+
type DriveConfig,
|
|
17
|
+
DriveManager,
|
|
18
|
+
type DriveServiceFactory,
|
|
19
|
+
type FsServiceOptions,
|
|
20
|
+
services,
|
|
21
|
+
} from "./DriveManager.js";
|
|
13
22
|
export { ArchiveError } from "./errors.js";
|
|
14
23
|
export {
|
|
15
24
|
type GcsConfig,
|
|
16
25
|
GcsDriver,
|
|
17
26
|
type GcsServiceAccount,
|
|
18
27
|
} from "./GcsDriver.js";
|
|
28
|
+
export { DriveDirectory, DriveFile } from "./objects.js";
|
|
19
29
|
export { type S3Config, S3Driver } from "./S3Driver.js";
|
|
20
30
|
export {
|
|
21
31
|
type StaticConfig,
|
|
@@ -24,6 +34,8 @@ export {
|
|
|
24
34
|
type StaticMiddlewareResponse,
|
|
25
35
|
} from "./StaticMiddleware.js";
|
|
26
36
|
export {
|
|
37
|
+
type ListAllOptions,
|
|
38
|
+
type ListAllResult,
|
|
27
39
|
LocalDriver,
|
|
28
40
|
type LocalDriverOptions,
|
|
29
41
|
type Metadata,
|
|
@@ -33,6 +45,7 @@ export {
|
|
|
33
45
|
type StorageEntry,
|
|
34
46
|
StorageManager,
|
|
35
47
|
type Visibility,
|
|
48
|
+
type WriteOptions,
|
|
36
49
|
} from "./StorageManager.js";
|
|
37
50
|
export {
|
|
38
51
|
createSignedRouteHandler,
|
|
@@ -42,11 +55,19 @@ export {
|
|
|
42
55
|
} from "./signed-route.js";
|
|
43
56
|
|
|
44
57
|
import type { ArchiveConfig } from "./ArchiveProvider.js";
|
|
58
|
+
import type { DriveConfig } from "./DriveManager.js";
|
|
45
59
|
|
|
46
60
|
/**
|
|
47
|
-
* Author-time config helper for `config/
|
|
48
|
-
* parity. Identity at runtime; the generic preserves
|
|
61
|
+
* Author-time config helper for `config/archive.ts` — AdonisJS Drive
|
|
62
|
+
* `defineConfig` parity. Identity at runtime; the generic preserves
|
|
63
|
+
* literal types for inference.
|
|
64
|
+
*
|
|
65
|
+
* Accepts the multi-disk shape `{ default, services, fakes }` (build the
|
|
66
|
+
* services with the `services.*` helpers) or the legacy single-disk
|
|
67
|
+
* `{ driver, local, s3, gcs }` shape.
|
|
49
68
|
*/
|
|
50
|
-
export function defineConfig<T extends ArchiveConfig>(
|
|
69
|
+
export function defineConfig<T extends DriveConfig | ArchiveConfig>(
|
|
70
|
+
config: T,
|
|
71
|
+
): T {
|
|
51
72
|
return config;
|
|
52
73
|
}
|
package/src/objects.ts
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DriveFile / DriveDirectory — the object types yielded by
|
|
3
|
+
* {@link StorageDriver.listAll} (AdonisJS Drive / flydrive parity).
|
|
4
|
+
*
|
|
5
|
+
* `listAll` returns a mix of these: files carry a lazy pointer to the
|
|
6
|
+
* driver (so `getBytes()`/`getMetaData()` can be resolved on demand)
|
|
7
|
+
* plus an optional metadata snapshot captured during the listing;
|
|
8
|
+
* directories are prefix markers surfaced only for non-recursive
|
|
9
|
+
* listings.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { basename } from "node:path";
|
|
13
|
+
import type {
|
|
14
|
+
Metadata,
|
|
15
|
+
SignedUrlOptions,
|
|
16
|
+
StorageDriver,
|
|
17
|
+
Visibility,
|
|
18
|
+
} from "./StorageManager.js";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Representation of a directory in a non-recursive listing. Mirrors
|
|
22
|
+
* flydrive's `DriveDirectory`.
|
|
23
|
+
*/
|
|
24
|
+
export class DriveDirectory {
|
|
25
|
+
isFile: false = false;
|
|
26
|
+
isDirectory: true = true;
|
|
27
|
+
name: string;
|
|
28
|
+
|
|
29
|
+
constructor(public prefix: string) {
|
|
30
|
+
this.name = basename(prefix);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Pointer to a stored object. Returned by `listAll`; also usable as a
|
|
36
|
+
* lazy handle for reading contents / metadata. Mirrors flydrive's
|
|
37
|
+
* `DriveFile` but built on the in-package {@link StorageDriver} contract
|
|
38
|
+
* (no router coupling — the legitimate ream divergence).
|
|
39
|
+
*/
|
|
40
|
+
export class DriveFile {
|
|
41
|
+
isFile: true = true;
|
|
42
|
+
isDirectory: false = false;
|
|
43
|
+
key: string;
|
|
44
|
+
name: string;
|
|
45
|
+
#driver: StorageDriver;
|
|
46
|
+
#metadata?: Metadata;
|
|
47
|
+
|
|
48
|
+
constructor(key: string, driver: StorageDriver, metadata?: Metadata) {
|
|
49
|
+
this.key = key;
|
|
50
|
+
this.name = basename(key);
|
|
51
|
+
this.#driver = driver;
|
|
52
|
+
this.#metadata = metadata;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
exists(): Promise<boolean> {
|
|
56
|
+
return this.#driver.exists(this.key);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Raw contents (`Buffer | null`). See {@link StorageDriver.get}. */
|
|
60
|
+
get(): Promise<Buffer | null> {
|
|
61
|
+
return this.#driver.get(this.key);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
getBytes(): Promise<Uint8Array> {
|
|
65
|
+
return this.#driver.getBytes(this.key);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
getStream(): Promise<NodeJS.ReadableStream> {
|
|
69
|
+
return this.#driver.getStream(this.key);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Metadata for the object. Returns the snapshot captured during the
|
|
74
|
+
* listing when present; otherwise resolves it from the driver.
|
|
75
|
+
*/
|
|
76
|
+
getMetaData(): Promise<Metadata> {
|
|
77
|
+
if (this.#metadata) return Promise.resolve(this.#metadata);
|
|
78
|
+
return this.#driver.getMetadata(this.key);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
getVisibility(): Promise<Visibility> {
|
|
82
|
+
return this.#driver.getVisibility(this.key);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
getUrl(): Promise<string> {
|
|
86
|
+
return this.#driver.url(this.key);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
getSignedUrl(options?: SignedUrlOptions): string | Promise<string> {
|
|
90
|
+
return this.#driver.getSignedUrl(this.key, options);
|
|
91
|
+
}
|
|
92
|
+
}
|