@c9up/archive 0.1.13 → 0.1.14
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.js +3 -3
- package/dist/ArchiveProvider.js.map +1 -1
- package/dist/DriveManager.js +2 -2
- package/dist/DriveManager.js.map +1 -1
- package/dist/GcsDriver.js +5 -5
- package/dist/GcsDriver.js.map +1 -1
- package/dist/S3Driver.js +6 -6
- package/dist/S3Driver.js.map +1 -1
- package/dist/StorageManager.d.ts +8 -8
- package/dist/StorageManager.d.ts.map +1 -1
- package/dist/StorageManager.js +13 -13
- package/dist/StorageManager.js.map +1 -1
- package/dist/expiry.d.ts +2 -2
- package/dist/expiry.js +6 -6
- package/dist/expiry.js.map +1 -1
- package/dist/testing/FakeStorage.js +7 -7
- package/dist/testing/FakeStorage.js.map +1 -1
- package/package.json +1 -1
- package/src/ArchiveProvider.ts +3 -3
- package/src/DriveManager.ts +2 -2
- package/src/GcsDriver.ts +5 -5
- package/src/S3Driver.ts +6 -6
- package/src/StorageManager.ts +20 -20
- package/src/expiry.ts +6 -6
- package/src/testing/FakeStorage.ts +7 -7
package/src/StorageManager.ts
CHANGED
|
@@ -158,12 +158,12 @@ export interface StorageDriver {
|
|
|
158
158
|
get(filePath: string): Promise<Buffer | null>;
|
|
159
159
|
/**
|
|
160
160
|
* Contents as a `Uint8Array`. AdonisJS Drive parity. Throws
|
|
161
|
-
* `
|
|
161
|
+
* `E_ARCHIVE_NOT_FOUND` when the object is absent (unlike {@link get},
|
|
162
162
|
* a byte accessor can't express absence as a value).
|
|
163
163
|
*/
|
|
164
164
|
getBytes(filePath: string): Promise<Uint8Array>;
|
|
165
165
|
/**
|
|
166
|
-
* Download as a readable stream. Throws `
|
|
166
|
+
* Download as a readable stream. Throws `E_ARCHIVE_NOT_FOUND` when
|
|
167
167
|
* the object is missing — streams can't express absence as a value.
|
|
168
168
|
*/
|
|
169
169
|
getStream(filePath: string): Promise<NodeJS.ReadableStream>;
|
|
@@ -185,7 +185,7 @@ export interface StorageDriver {
|
|
|
185
185
|
* Return a time-boxed URL that grants read access to `filePath`.
|
|
186
186
|
* Implementations must validate `options.expiresIn` via
|
|
187
187
|
* {@link assertValidExpiry} and reject out-of-range values with
|
|
188
|
-
* `
|
|
188
|
+
* `E_ARCHIVE_INVALID_EXPIRY`.
|
|
189
189
|
*/
|
|
190
190
|
getSignedUrl(
|
|
191
191
|
filePath: string,
|
|
@@ -195,14 +195,14 @@ export interface StorageDriver {
|
|
|
195
195
|
* Return a time-boxed URL that grants **write** (PUT) access, letting
|
|
196
196
|
* a client upload directly to the backend. AdonisJS Drive parity.
|
|
197
197
|
* Cloud-only — the LocalDriver has no presigned-upload equivalent and
|
|
198
|
-
* throws `
|
|
198
|
+
* throws `E_ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED`.
|
|
199
199
|
*/
|
|
200
200
|
getSignedUploadUrl(
|
|
201
201
|
filePath: string,
|
|
202
202
|
options?: SignedUrlOptions,
|
|
203
203
|
): string | Promise<string>;
|
|
204
204
|
/**
|
|
205
|
-
* Resolve object metadata. Throws `ArchiveError('
|
|
205
|
+
* Resolve object metadata. Throws `ArchiveError('E_ARCHIVE_NOT_FOUND', ...)`
|
|
206
206
|
* when the object does not exist.
|
|
207
207
|
*/
|
|
208
208
|
getMetadata(filePath: string): Promise<Metadata>;
|
|
@@ -217,7 +217,7 @@ export interface StorageDriver {
|
|
|
217
217
|
*/
|
|
218
218
|
setVisibility(filePath: string, visibility: Visibility): Promise<void>;
|
|
219
219
|
/**
|
|
220
|
-
* Duplicate an object. Throws `
|
|
220
|
+
* Duplicate an object. Throws `E_ARCHIVE_NOT_FOUND` if `from` is
|
|
221
221
|
* missing. Target is overwritten if it exists. Visibility is NOT
|
|
222
222
|
* carried over unless `options.visibility` is passed — the new object
|
|
223
223
|
* takes default visibility.
|
|
@@ -255,7 +255,7 @@ export interface LocalDriverOptions {
|
|
|
255
255
|
/**
|
|
256
256
|
* HMAC-SHA256 secret used by {@link LocalDriver.getSignedUrl}.
|
|
257
257
|
* When omitted, signing is disabled and `getSignedUrl` throws
|
|
258
|
-
* `
|
|
258
|
+
* `E_ARCHIVE_SIGNING_DISABLED`. The non-signing methods
|
|
259
259
|
* (`put`/`get`/`delete`/`exists`/`url`) work either way.
|
|
260
260
|
*/
|
|
261
261
|
signingSecret?: string;
|
|
@@ -280,7 +280,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
280
280
|
// values without being annoyingly strict about format.
|
|
281
281
|
if (typeof secret !== "string" || secret.length < 16) {
|
|
282
282
|
throw new ArchiveError(
|
|
283
|
-
"
|
|
283
|
+
"E_ARCHIVE_WEAK_SIGNING_SECRET",
|
|
284
284
|
`LocalDriver signingSecret must be a string of at least 16 chars (got length ${typeof secret === "string" ? secret.length : "non-string"})`,
|
|
285
285
|
{
|
|
286
286
|
hint: "Use a cryptographically random secret, e.g. `crypto.randomBytes(32).toString('hex')`.",
|
|
@@ -363,7 +363,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
363
363
|
const buf = await this.get(filePath);
|
|
364
364
|
if (buf === null) {
|
|
365
365
|
throw new ArchiveError(
|
|
366
|
-
"
|
|
366
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
367
367
|
`File does not exist at path '${filePath}'`,
|
|
368
368
|
{ hint: "Confirm the path and that the file was put() first." },
|
|
369
369
|
);
|
|
@@ -398,7 +398,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
398
398
|
const full = this.#safePath(filePath);
|
|
399
399
|
if (!fs.existsSync(full)) {
|
|
400
400
|
throw new ArchiveError(
|
|
401
|
-
"
|
|
401
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
402
402
|
`File does not exist at path '${filePath}'`,
|
|
403
403
|
{ hint: "Confirm the path and that the file was put() first." },
|
|
404
404
|
);
|
|
@@ -456,7 +456,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
456
456
|
} catch (err) {
|
|
457
457
|
if ((err as NodeJS.ErrnoException).code === "ENOENT") {
|
|
458
458
|
throw new ArchiveError(
|
|
459
|
-
"
|
|
459
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
460
460
|
`File does not exist at path '${filePath}'`,
|
|
461
461
|
{ hint: "Confirm the path and that the file was put() first." },
|
|
462
462
|
);
|
|
@@ -490,7 +490,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
490
490
|
const full = this.#safePath(filePath);
|
|
491
491
|
if (!fs.existsSync(full)) {
|
|
492
492
|
throw new ArchiveError(
|
|
493
|
-
"
|
|
493
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
494
494
|
`Cannot set visibility — file does not exist at path '${filePath}'`,
|
|
495
495
|
{ hint: "put() the file before calling setVisibility()." },
|
|
496
496
|
);
|
|
@@ -516,7 +516,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
516
516
|
raw = fs.readFileSync(sidecar, "utf8");
|
|
517
517
|
} catch (err) {
|
|
518
518
|
throw new ArchiveError(
|
|
519
|
-
"
|
|
519
|
+
"E_ARCHIVE_VISIBILITY_CORRUPT",
|
|
520
520
|
`Failed to read visibility sidecar for '${filePath}' (${(err as NodeJS.ErrnoException).code ?? "I/O error"}); refusing to default to 'public'.`,
|
|
521
521
|
{
|
|
522
522
|
hint: "Inspect the sidecar file or re-apply visibility via setVisibility().",
|
|
@@ -528,7 +528,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
528
528
|
parsed = JSON.parse(raw) as { visibility?: unknown };
|
|
529
529
|
} catch {
|
|
530
530
|
throw new ArchiveError(
|
|
531
|
-
"
|
|
531
|
+
"E_ARCHIVE_VISIBILITY_CORRUPT",
|
|
532
532
|
`Sidecar for '${filePath}' is not valid JSON; refusing to default to 'public'.`,
|
|
533
533
|
{
|
|
534
534
|
hint: "Delete the sidecar file and re-apply visibility via setVisibility().",
|
|
@@ -548,7 +548,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
548
548
|
const secret = this.#signingSecret;
|
|
549
549
|
if (secret === null) {
|
|
550
550
|
throw new ArchiveError(
|
|
551
|
-
"
|
|
551
|
+
"E_ARCHIVE_SIGNING_DISABLED",
|
|
552
552
|
"LocalDriver.getSignedUrl requires a signingSecret at construction time",
|
|
553
553
|
{
|
|
554
554
|
hint: "Pass { signingSecret: <hex or random string> } to the LocalDriver constructor, or set config.archive.local.signingSecret. Private files require a signing secret.",
|
|
@@ -571,7 +571,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
571
571
|
*/
|
|
572
572
|
getSignedUploadUrl(_filePath: string, _options?: SignedUrlOptions): string {
|
|
573
573
|
throw new ArchiveError(
|
|
574
|
-
"
|
|
574
|
+
"E_ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED",
|
|
575
575
|
"LocalDriver does not support presigned upload URLs",
|
|
576
576
|
{
|
|
577
577
|
hint: "Presigned uploads are an S3/GCS feature. For local storage, upload through your app's HTTP handler.",
|
|
@@ -592,7 +592,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
592
592
|
const toFull = this.#safePath(to);
|
|
593
593
|
if (!fs.existsSync(fromFull)) {
|
|
594
594
|
throw new ArchiveError(
|
|
595
|
-
"
|
|
595
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
596
596
|
`Cannot copy — source does not exist at path '${from}'`,
|
|
597
597
|
{ hint: "Confirm the source path was put() first." },
|
|
598
598
|
);
|
|
@@ -612,7 +612,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
612
612
|
const toFull = this.#safePath(to);
|
|
613
613
|
if (!fs.existsSync(fromFull)) {
|
|
614
614
|
throw new ArchiveError(
|
|
615
|
-
"
|
|
615
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
616
616
|
`Cannot move — source does not exist at path '${from}'`,
|
|
617
617
|
{ hint: "Confirm the source path was put() first." },
|
|
618
618
|
);
|
|
@@ -655,7 +655,7 @@ export class LocalDriver implements StorageDriver {
|
|
|
655
655
|
);
|
|
656
656
|
} catch (err) {
|
|
657
657
|
throw new ArchiveError(
|
|
658
|
-
"
|
|
658
|
+
"E_ARCHIVE_VISIBILITY_MOVE_FAILED",
|
|
659
659
|
`move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${(err as NodeJS.ErrnoException).code ?? "unknown"}). Target visibility is undefined.`,
|
|
660
660
|
{
|
|
661
661
|
hint: "Re-apply visibility via setVisibility() on the target path.",
|
|
@@ -890,7 +890,7 @@ export class StorageManager {
|
|
|
890
890
|
return this.#driver.get(filePath);
|
|
891
891
|
}
|
|
892
892
|
|
|
893
|
-
/** Contents as a `Uint8Array`. Throws `
|
|
893
|
+
/** Contents as a `Uint8Array`. Throws `E_ARCHIVE_NOT_FOUND` if absent. */
|
|
894
894
|
getBytes(filePath: string): Promise<Uint8Array> {
|
|
895
895
|
return this.#driver.getBytes(filePath);
|
|
896
896
|
}
|
package/src/expiry.ts
CHANGED
|
@@ -45,7 +45,7 @@ const UNIT_SECONDS: Record<string, number> = {
|
|
|
45
45
|
* Normalise a signed-URL `expiresIn` into a number of seconds. Accepts
|
|
46
46
|
* either a raw number of seconds (returned as-is) or a human-friendly
|
|
47
47
|
* duration string such as `'30mins'`, `'7 days'`, `'1h'` — AdonisJS
|
|
48
|
-
* Drive parity. Unrecognised strings throw `
|
|
48
|
+
* Drive parity. Unrecognised strings throw `E_ARCHIVE_INVALID_EXPIRY`.
|
|
49
49
|
*/
|
|
50
50
|
export function parseExpiry(expiresIn: number | string): number {
|
|
51
51
|
if (typeof expiresIn === "number") return expiresIn;
|
|
@@ -54,7 +54,7 @@ export function parseExpiry(expiresIn: number | string): number {
|
|
|
54
54
|
const multiplier = unitKey === "" ? 1 : UNIT_SECONDS[unitKey];
|
|
55
55
|
if (match === undefined || match === null || multiplier === undefined) {
|
|
56
56
|
throw new ArchiveError(
|
|
57
|
-
"
|
|
57
|
+
"E_ARCHIVE_INVALID_EXPIRY",
|
|
58
58
|
`Signed-URL expiresIn string '${expiresIn}' could not be parsed`,
|
|
59
59
|
{
|
|
60
60
|
hint: "Use a number of seconds, or a duration like '30mins', '1h', '7 days'.",
|
|
@@ -66,26 +66,26 @@ export function parseExpiry(expiresIn: number | string): number {
|
|
|
66
66
|
|
|
67
67
|
/**
|
|
68
68
|
* Reject non-finite, zero, negative, or out-of-range expiries. Throws
|
|
69
|
-
* `
|
|
69
|
+
* `E_ARCHIVE_INVALID_EXPIRY` so callers get a typed error with a hint.
|
|
70
70
|
*/
|
|
71
71
|
export function assertValidExpiry(expiresIn: number): void {
|
|
72
72
|
if (!Number.isFinite(expiresIn)) {
|
|
73
73
|
throw new ArchiveError(
|
|
74
|
-
"
|
|
74
|
+
"E_ARCHIVE_INVALID_EXPIRY",
|
|
75
75
|
`Signed-URL expiresIn must be finite, got ${expiresIn}`,
|
|
76
76
|
{ hint: "Pass a positive number of seconds between 1 and 604800." },
|
|
77
77
|
);
|
|
78
78
|
}
|
|
79
79
|
if (expiresIn <= 0) {
|
|
80
80
|
throw new ArchiveError(
|
|
81
|
-
"
|
|
81
|
+
"E_ARCHIVE_INVALID_EXPIRY",
|
|
82
82
|
`Signed-URL expiresIn must be > 0 seconds, got ${expiresIn}`,
|
|
83
83
|
{ hint: "Pass a positive number of seconds between 1 and 604800." },
|
|
84
84
|
);
|
|
85
85
|
}
|
|
86
86
|
if (expiresIn > MAX_EXPIRES_IN) {
|
|
87
87
|
throw new ArchiveError(
|
|
88
|
-
"
|
|
88
|
+
"E_ARCHIVE_INVALID_EXPIRY",
|
|
89
89
|
`Signed-URL expiresIn must be <= ${MAX_EXPIRES_IN} seconds (7 days), got ${expiresIn}`,
|
|
90
90
|
{ hint: "AWS SigV4 caps presigned URLs at 7 days." },
|
|
91
91
|
);
|
|
@@ -75,7 +75,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
75
75
|
const obj = this.#store.get(filePath);
|
|
76
76
|
if (!obj) {
|
|
77
77
|
throw new ArchiveError(
|
|
78
|
-
"
|
|
78
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
79
79
|
`Fake object does not exist at path '${filePath}'`,
|
|
80
80
|
{ hint: "put() it first, or verify the test setup." },
|
|
81
81
|
);
|
|
@@ -114,7 +114,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
114
114
|
const obj = this.#store.get(filePath);
|
|
115
115
|
if (!obj) {
|
|
116
116
|
throw new ArchiveError(
|
|
117
|
-
"
|
|
117
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
118
118
|
`Fake object does not exist at path '${filePath}'`,
|
|
119
119
|
{ hint: "put() it first, or verify the test setup." },
|
|
120
120
|
);
|
|
@@ -164,7 +164,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
164
164
|
const obj = this.#store.get(filePath);
|
|
165
165
|
if (!obj) {
|
|
166
166
|
throw new ArchiveError(
|
|
167
|
-
"
|
|
167
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
168
168
|
`Fake object does not exist at path '${filePath}'`,
|
|
169
169
|
{ hint: "put() it first, or verify the test setup." },
|
|
170
170
|
);
|
|
@@ -176,7 +176,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
176
176
|
const obj = this.#store.get(filePath);
|
|
177
177
|
if (!obj) {
|
|
178
178
|
throw new ArchiveError(
|
|
179
|
-
"
|
|
179
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
180
180
|
`Fake object does not exist at path '${filePath}'`,
|
|
181
181
|
{ hint: "put() it first, or verify the test setup." },
|
|
182
182
|
);
|
|
@@ -199,7 +199,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
199
199
|
const obj = this.#store.get(filePath);
|
|
200
200
|
if (!obj) {
|
|
201
201
|
throw new ArchiveError(
|
|
202
|
-
"
|
|
202
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
203
203
|
`Cannot set visibility — fake object does not exist at path '${filePath}'`,
|
|
204
204
|
{ hint: "put() the file before calling setVisibility()." },
|
|
205
205
|
);
|
|
@@ -211,7 +211,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
211
211
|
const src = this.#store.get(from);
|
|
212
212
|
if (!src) {
|
|
213
213
|
throw new ArchiveError(
|
|
214
|
-
"
|
|
214
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
215
215
|
`Cannot copy — fake source does not exist at path '${from}'`,
|
|
216
216
|
{ hint: "Confirm the source path was put() first." },
|
|
217
217
|
);
|
|
@@ -230,7 +230,7 @@ export class FakeStorage implements StorageDriver {
|
|
|
230
230
|
const src = this.#store.get(from);
|
|
231
231
|
if (!src) {
|
|
232
232
|
throw new ArchiveError(
|
|
233
|
-
"
|
|
233
|
+
"E_ARCHIVE_NOT_FOUND",
|
|
234
234
|
`Cannot move — fake source does not exist at path '${from}'`,
|
|
235
235
|
{ hint: "Confirm the source path was put() first." },
|
|
236
236
|
);
|