@c9up/archive 0.1.20 → 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.
Files changed (87) hide show
  1. package/README.md +96 -3
  2. package/dist/ArchiveProvider.d.ts +6 -1
  3. package/dist/ArchiveProvider.d.ts.map +1 -1
  4. package/dist/ArchiveProvider.js +73 -1
  5. package/dist/ArchiveProvider.js.map +1 -1
  6. package/dist/DriveManager.d.ts +10 -3
  7. package/dist/DriveManager.d.ts.map +1 -1
  8. package/dist/DriveManager.js +23 -6
  9. package/dist/DriveManager.js.map +1 -1
  10. package/dist/GcsDriver.d.ts +14 -9
  11. package/dist/GcsDriver.d.ts.map +1 -1
  12. package/dist/GcsDriver.js +202 -98
  13. package/dist/GcsDriver.js.map +1 -1
  14. package/dist/S3Driver.d.ts +11 -7
  15. package/dist/S3Driver.d.ts.map +1 -1
  16. package/dist/S3Driver.js +73 -110
  17. package/dist/S3Driver.js.map +1 -1
  18. package/dist/StaticMiddleware.d.ts +5 -1
  19. package/dist/StaticMiddleware.d.ts.map +1 -1
  20. package/dist/StaticMiddleware.js +114 -13
  21. package/dist/StaticMiddleware.js.map +1 -1
  22. package/dist/StorageManager.d.ts +28 -3
  23. package/dist/StorageManager.d.ts.map +1 -1
  24. package/dist/StorageManager.js +333 -132
  25. package/dist/StorageManager.js.map +1 -1
  26. package/dist/augmentations.d.ts +17 -0
  27. package/dist/augmentations.d.ts.map +1 -1
  28. package/dist/errno.d.ts +6 -0
  29. package/dist/errno.d.ts.map +1 -0
  30. package/dist/errno.js +11 -0
  31. package/dist/errno.js.map +1 -0
  32. package/dist/index.d.ts +1 -0
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js.map +1 -1
  35. package/dist/keys.d.ts +34 -0
  36. package/dist/keys.d.ts.map +1 -0
  37. package/dist/keys.js +88 -0
  38. package/dist/keys.js.map +1 -0
  39. package/dist/local-signature.d.ts +32 -0
  40. package/dist/local-signature.d.ts.map +1 -0
  41. package/dist/local-signature.js +58 -0
  42. package/dist/local-signature.js.map +1 -0
  43. package/dist/move-to-disk.d.ts +24 -0
  44. package/dist/move-to-disk.d.ts.map +1 -0
  45. package/dist/move-to-disk.js +167 -0
  46. package/dist/move-to-disk.js.map +1 -0
  47. package/dist/objects.d.ts.map +1 -1
  48. package/dist/objects.js +5 -2
  49. package/dist/objects.js.map +1 -1
  50. package/dist/provider-fetch.d.ts +36 -0
  51. package/dist/provider-fetch.d.ts.map +1 -0
  52. package/dist/provider-fetch.js +158 -0
  53. package/dist/provider-fetch.js.map +1 -0
  54. package/dist/services/main.d.ts +1 -1
  55. package/dist/services/main.d.ts.map +1 -1
  56. package/dist/services/main.js +14 -1
  57. package/dist/services/main.js.map +1 -1
  58. package/dist/signed-route.d.ts +18 -6
  59. package/dist/signed-route.d.ts.map +1 -1
  60. package/dist/signed-route.js +186 -31
  61. package/dist/signed-route.js.map +1 -1
  62. package/dist/streams.d.ts +36 -0
  63. package/dist/streams.d.ts.map +1 -0
  64. package/dist/streams.js +108 -0
  65. package/dist/streams.js.map +1 -0
  66. package/dist/testing/FakeStorage.d.ts.map +1 -1
  67. package/dist/testing/FakeStorage.js +2 -1
  68. package/dist/testing/FakeStorage.js.map +1 -1
  69. package/package.json +7 -3
  70. package/src/ArchiveProvider.ts +105 -4
  71. package/src/DriveManager.ts +32 -6
  72. package/src/GcsDriver.ts +256 -139
  73. package/src/S3Driver.ts +87 -130
  74. package/src/StaticMiddleware.ts +124 -13
  75. package/src/StorageManager.ts +398 -141
  76. package/src/augmentations.ts +24 -1
  77. package/src/errno.ts +10 -0
  78. package/src/index.ts +1 -0
  79. package/src/keys.ts +104 -0
  80. package/src/local-signature.ts +76 -0
  81. package/src/move-to-disk.ts +234 -0
  82. package/src/objects.ts +5 -2
  83. package/src/provider-fetch.ts +171 -0
  84. package/src/services/main.ts +15 -2
  85. package/src/signed-route.ts +216 -36
  86. package/src/streams.ts +118 -0
  87. package/src/testing/FakeStorage.ts +2 -3
@@ -15,12 +15,35 @@
15
15
  * simply inert.
16
16
  */
17
17
 
18
- // Referenced so the augmentation below resolves the module it augments.
18
+ // Referenced so the augmentations below resolve the modules they augment.
19
+ import type {} from "@c9up/ream";
19
20
  import type {} from "@c9up/ream/types";
20
21
 
21
22
  import type { DriveManager } from "./DriveManager.js";
23
+ import type { MoveToDiskOptions } from "./move-to-disk.js";
22
24
  import type { StorageManager } from "./StorageManager.js";
23
25
 
26
+ declare module "@c9up/ream" {
27
+ interface MultipartFile {
28
+ /**
29
+ * Write the upload into a disk (the default one when `disk` is
30
+ * omitted), set `meta.url` to its URL when the disk can name one, and
31
+ * mark the file as moved under its key.
32
+ *
33
+ * Attached by `ArchiveProvider` at boot. The key is normalised like any
34
+ * other: a `..` segment or a backslash is refused before anything is
35
+ * written.
36
+ */
37
+ moveToDisk(
38
+ key: string,
39
+ disk?: string,
40
+ options?: MoveToDiskOptions,
41
+ ): Promise<void>;
42
+ /** Same, on the default disk. */
43
+ moveToDisk(key: string, options?: MoveToDiskOptions): Promise<void>;
44
+ }
45
+ }
46
+
24
47
  declare module "@c9up/ream/types" {
25
48
  interface ContainerBindings {
26
49
  /** The drive manager, bound by `ArchiveProvider`. */
package/src/errno.ts ADDED
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The `code` a Node system error carries (`ENOENT`, `EXDEV`, …), or
3
+ * `undefined` for anything else — read through a guard, not a cast.
4
+ */
5
+ export function errnoCode(err: unknown): string | undefined {
6
+ if (typeof err !== "object" || err === null || !("code" in err)) {
7
+ return undefined;
8
+ }
9
+ return typeof err.code === "string" ? err.code : undefined;
10
+ }
package/src/index.ts CHANGED
@@ -27,6 +27,7 @@ export {
27
27
  GcsDriver,
28
28
  type GcsServiceAccount,
29
29
  } from "./GcsDriver.js";
30
+ export type { MoveToDiskOptions } from "./move-to-disk.js";
30
31
  export type { FileSnapshot } from "./objects.js";
31
32
  export { DriveDirectory, DriveFile } from "./objects.js";
32
33
  export { type S3Config, S3Driver } from "./S3Driver.js";
package/src/keys.ts ADDED
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Key normalisation, applied before any driver sees a key.
3
+ *
4
+ * Same rules as the upstream storage library's key normaliser, so `/a.txt`,
5
+ * `a//b` and `./a` name the objects `a.txt`, `a/b` and `a` on every disk, and
6
+ * a `..` segment is refused rather than resolved. Only the local disk used to
7
+ * check containment, so on S3/GCS `publicUrl("../other-bucket/file.txt")`
8
+ * built a link every URL parser resolves into another bucket on the same host.
9
+ *
10
+ * NAMED DEVIATION — the character set is wider and the refusals are stricter.
11
+ * Upstream accepts only `[A-Za-z0-9-_!/. \s]`; here spaces, unicode and
12
+ * dotfiles stay valid names (upstream also strips a leading `.`, turning
13
+ * `.env` into `env`). In exchange, what upstream rewrites is refused: a
14
+ * backslash (upstream turns it into `/`), control characters (upstream folds
15
+ * them into a space), a dot-only segment of any length, and percent-encoded
16
+ * dots, slashes, backslashes and NUL — a key that would turn into a traversal
17
+ * or a separator once some layer decodes it.
18
+ */
19
+
20
+ import { ArchiveError } from "./errors.js";
21
+
22
+ /** `%2e` (`.`), `%2f` (`/`), `%5c` (`\`), `%00` (NUL), any case. */
23
+ const ENCODED_SEPARATOR = /%(2f|5c|00)/i;
24
+ const ENCODED_DOT = /%2e/gi;
25
+
26
+ function unallowed(key: string, what: string): ArchiveError {
27
+ return new ArchiveError(
28
+ "E_ARCHIVE_UNALLOWED_CHARACTERS",
29
+ `The key ${JSON.stringify(key)} has unallowed characters: ${what}`,
30
+ {
31
+ hint: "Use '/' as the only separator, and no control characters.",
32
+ },
33
+ );
34
+ }
35
+
36
+ function traversal(key: string): ArchiveError {
37
+ return new ArchiveError(
38
+ "E_ARCHIVE_PATH_TRAVERSAL_DETECTED",
39
+ `Path traversal segment detected in key ${JSON.stringify(key)}`,
40
+ {
41
+ hint: "Keys are relative to the disk: build them without '..' segments.",
42
+ },
43
+ );
44
+ }
45
+
46
+ /**
47
+ * The segments of `key`, validated, with empty and `.` segments dropped.
48
+ * Throws on anything that is not a plain relative name.
49
+ */
50
+ function segments(key: string): string[] {
51
+ for (let i = 0; i < key.length; i++) {
52
+ const code = key.charCodeAt(i);
53
+ if (code < 0x20 || code === 0x7f) {
54
+ throw unallowed(key, "control characters are not allowed");
55
+ }
56
+ }
57
+ if (key.includes("\\")) {
58
+ throw unallowed(key, "a backslash is not a separator");
59
+ }
60
+ if (ENCODED_SEPARATOR.test(key)) {
61
+ throw unallowed(key, "an encoded separator or NUL");
62
+ }
63
+ const kept: string[] = [];
64
+ for (const segment of key.split("/")) {
65
+ if (segment === "" || segment === ".") continue;
66
+ // `..`, `...` and their encoded forms: never a name worth the risk.
67
+ if (/^\.+$/.test(segment.replace(ENCODED_DOT, "."))) {
68
+ throw traversal(key);
69
+ }
70
+ kept.push(segment);
71
+ }
72
+ return kept;
73
+ }
74
+
75
+ /**
76
+ * Normalise an object key: collapse repeated `/`, drop `.` segments and the
77
+ * leading/trailing `/`. Throws `E_ARCHIVE_PATH_TRAVERSAL_DETECTED` on a
78
+ * dot-only segment, `E_ARCHIVE_UNALLOWED_CHARACTERS` on a control character,
79
+ * a backslash or an encoded separator, and `E_ARCHIVE_INVALID_KEY` when
80
+ * nothing is left.
81
+ */
82
+ export function normalizeKey(key: string): string {
83
+ const normalized = segments(key).join("/");
84
+ if (normalized === "") {
85
+ throw new ArchiveError(
86
+ "E_ARCHIVE_INVALID_KEY",
87
+ `Invalid key ${JSON.stringify(key)}. After normalization results in an empty string`,
88
+ { hint: "Name the object: a key cannot be empty or only separators." },
89
+ );
90
+ }
91
+ return normalized;
92
+ }
93
+
94
+ /**
95
+ * Normalise a listing prefix. Same rules as {@link normalizeKey}, except that
96
+ * the root (`""` or `/`) is a valid prefix and a trailing `/` is kept: it is
97
+ * what tells `avatars/` (that directory) from `avatars` (anything starting
98
+ * with those letters).
99
+ */
100
+ export function normalizePrefix(prefix: string): string {
101
+ const normalized = segments(prefix).join("/");
102
+ if (normalized === "") return "";
103
+ return prefix.endsWith("/") ? `${normalized}/` : normalized;
104
+ }
@@ -0,0 +1,76 @@
1
+ /**
2
+ * What a local signed URL signs, shared by the driver that builds the URL and
3
+ * the route that verifies it, so the two cannot drift apart.
4
+ *
5
+ * The payload is `<key>\n<exp>`, followed — only when the URL carries
6
+ * response-header overrides — by `\n` and those overrides as an encoded query
7
+ * string in a fixed order. A key cannot contain `\n` (the key normaliser
8
+ * refuses control characters), `exp` is digits and the overrides line is
9
+ * percent-encoded, so no part can pose as another. A URL signed without
10
+ * overrides keeps the payload it always had.
11
+ */
12
+
13
+ import { ArchiveError } from "./errors.js";
14
+
15
+ /** Override query parameters, in signing order, and the header each sets. */
16
+ export const HEADER_OVERRIDES = [
17
+ ["contentType", "Content-Type"],
18
+ ["contentDisposition", "Content-Disposition"],
19
+ ] as const;
20
+
21
+ export type HeaderOverrideParam = (typeof HEADER_OVERRIDES)[number][0];
22
+
23
+ /** One override as it travels: query parameter name, header value. */
24
+ export type HeaderOverride = readonly [HeaderOverrideParam, string];
25
+
26
+ /**
27
+ * Whether `value` can be sent as a header value: no control character
28
+ * (horizontal tab aside), so it can neither end the header line nor split
29
+ * the response.
30
+ */
31
+ export function isHeaderValue(value: string): boolean {
32
+ for (let i = 0; i < value.length; i++) {
33
+ const code = value.charCodeAt(i);
34
+ if ((code < 0x20 && code !== 0x09) || code === 0x7f) return false;
35
+ }
36
+ return true;
37
+ }
38
+
39
+ /** The overrides requested by signing options, validated, in signing order. */
40
+ export function requestedOverrides(options: {
41
+ contentType?: string;
42
+ contentDisposition?: string;
43
+ }): HeaderOverride[] {
44
+ const overrides: HeaderOverride[] = [];
45
+ for (const [param, header] of HEADER_OVERRIDES) {
46
+ const value = options[param];
47
+ if (value === undefined || value === "") continue;
48
+ if (!isHeaderValue(value)) {
49
+ throw new ArchiveError(
50
+ "E_ARCHIVE_INVALID_HEADER_VALUE",
51
+ `${param} cannot be signed as a ${header} value: it contains a control character`,
52
+ { hint: "Header values cannot carry CR, LF, NUL or other controls." },
53
+ );
54
+ }
55
+ overrides.push([param, value]);
56
+ }
57
+ return overrides;
58
+ }
59
+
60
+ /** The HMAC input for a key, an expiry and its overrides. */
61
+ export function signedPayload(
62
+ key: string,
63
+ exp: number,
64
+ overrides: readonly HeaderOverride[],
65
+ ): string {
66
+ const base = `${key}\n${exp}`;
67
+ if (overrides.length === 0) return base;
68
+ return `${base}\n${overrideQuery(overrides)}`;
69
+ }
70
+
71
+ /** The overrides as `name=value&…`, values percent-encoded. */
72
+ export function overrideQuery(overrides: readonly HeaderOverride[]): string {
73
+ return overrides
74
+ .map(([param, value]) => `${param}=${encodeURIComponent(value)}`)
75
+ .join("&");
76
+ }
@@ -0,0 +1,234 @@
1
+ /**
2
+ * `MultipartFile.moveToDisk(key, disk?, options?)` — the storage half of an
3
+ * upload, attached to ream's `MultipartFile` as a macro by `ArchiveProvider`.
4
+ *
5
+ * await request.file('avatar')?.moveToDisk(`avatars/${user.id}.png`)
6
+ * await request.file('invoice')?.moveToDisk('invoices/a.pdf', 's3', {
7
+ * visibility: 'private',
8
+ * })
9
+ *
10
+ * The upload is written to the disk, `file.meta.url` is set to its URL when
11
+ * the disk can name one, and the file is marked as moved under its key.
12
+ */
13
+ import type { MultipartFile } from "@c9up/ream";
14
+ import type { DriveManager } from "./DriveManager.js";
15
+ import { ArchiveError } from "./errors.js";
16
+ import { normalizeKey } from "./keys.js";
17
+ import type { Visibility, WriteOptions } from "./StorageManager.js";
18
+
19
+ /** What `moveToDisk` accepts on top of the disk's write options. */
20
+ export interface MoveToDiskOptions extends WriteOptions {
21
+ /**
22
+ * `'stream'` (the default) pipes the upload into the disk, which lets a
23
+ * cloud disk send a large file in bounded parts. `'buffer'` hands the
24
+ * disk the whole file in one write.
25
+ */
26
+ moveAs?: "stream" | "buffer";
27
+ }
28
+
29
+ /** The class side of ream's `MultipartFile`: what attaching a macro needs. */
30
+ interface MacroableClass {
31
+ macro(name: string, fn: (...args: unknown[]) => unknown): void;
32
+ }
33
+
34
+ function isMacroableClass(value: unknown): value is MacroableClass {
35
+ return (
36
+ typeof value === "function" &&
37
+ "macro" in value &&
38
+ typeof value.macro === "function"
39
+ );
40
+ }
41
+
42
+ /** Node's refusal when `@c9up/ream` itself is not installed. */
43
+ function isReamMissing(error: unknown): boolean {
44
+ return (
45
+ error instanceof Error &&
46
+ "code" in error &&
47
+ error.code === "ERR_MODULE_NOT_FOUND" &&
48
+ error.message.includes("'@c9up/ream'")
49
+ );
50
+ }
51
+
52
+ /**
53
+ * Attach `moveToDisk` to ream's `MultipartFile`, writing into the disks
54
+ * `drive` resolves.
55
+ *
56
+ * ream is an optional peer: in a host without it there are no uploads to
57
+ * extend, and nothing is done. A ream whose `MultipartFile` cannot take a
58
+ * macro is refused at boot rather than left alone — its own
59
+ * `moveToDisk(directory, name)` would take `file.moveToDisk('a.png', 's3')`
60
+ * as a local directory and a file name, and write the upload to the local
61
+ * filesystem instead of the disk the application named.
62
+ */
63
+ export async function extendMultipartFile(
64
+ drive: () => DriveManager,
65
+ ): Promise<void> {
66
+ // Computed: ream is an optional peer, so a bundler must not try to
67
+ // resolve it for a host that does not install it.
68
+ const specifier = "@c9up/ream";
69
+ let loaded: unknown;
70
+ try {
71
+ loaded = await import(/* @vite-ignore */ specifier);
72
+ } catch (error) {
73
+ if (isReamMissing(error)) return;
74
+ throw error;
75
+ }
76
+ const multipartFile =
77
+ typeof loaded === "object" && loaded !== null
78
+ ? Reflect.get(loaded, "MultipartFile")
79
+ : undefined;
80
+ if (!isMacroableClass(multipartFile)) {
81
+ throw new ArchiveError(
82
+ "E_ARCHIVE_MULTIPART_NOT_MACROABLE",
83
+ "The installed @c9up/ream has no macroable MultipartFile: uploads cannot be given moveToDisk().",
84
+ {
85
+ hint: "Upgrade @c9up/ream to a version whose MultipartFile extends Macroable.",
86
+ },
87
+ );
88
+ }
89
+ multipartFile.macro(
90
+ "moveToDisk",
91
+ async function (this: MultipartFile, ...args: unknown[]): Promise<void> {
92
+ await moveToDisk(drive, this, args);
93
+ },
94
+ );
95
+ }
96
+
97
+ /**
98
+ * Write `file` into a disk. `args` is what the application passed:
99
+ * `(key, disk?, options?)` or `(key, options?)`.
100
+ */
101
+ async function moveToDisk(
102
+ drive: () => DriveManager,
103
+ file: MultipartFile,
104
+ args: unknown[],
105
+ ): Promise<void> {
106
+ const [key, diskOrOptions, writeOptions] = args;
107
+ if (typeof key !== "string") {
108
+ throw new ArchiveError(
109
+ "E_ARCHIVE_INVALID_KEY",
110
+ `moveToDisk() takes the object key as a string, got ${typeof key}`,
111
+ { hint: "Pass the key first: file.moveToDisk('avatars/1.png')." },
112
+ );
113
+ }
114
+ let diskName: string | undefined;
115
+ let options: MoveToDiskOptions;
116
+ if (typeof diskOrOptions === "string") {
117
+ diskName = diskOrOptions;
118
+ options = parseOptions(writeOptions);
119
+ } else if (writeOptions === undefined) {
120
+ options = parseOptions(diskOrOptions);
121
+ } else if (diskOrOptions === undefined) {
122
+ options = parseOptions(writeOptions);
123
+ } else {
124
+ // NAMED DEVIATION: two option objects are refused. Upstream keeps the
125
+ // second and drops the first, which silently discards a
126
+ // `visibility: 'private'` written there.
127
+ throw invalidOptions(
128
+ "two option objects were passed; give the disk name as a string, or one options object",
129
+ );
130
+ }
131
+
132
+ // Before the disk is touched: a key that names no object, or one that
133
+ // climbs out of the disk, is refused with nothing written.
134
+ const normalized = normalizeKey(key);
135
+ const disk = drive().use(diskName);
136
+ const { moveAs = "stream", ...write } = options;
137
+
138
+ // NAMED DEVIATION: upstream streams from the temporary file the body
139
+ // parser left on disk; ream holds the upload in memory, so 'stream'
140
+ // pipes that buffer into the disk (a cloud disk still sends a large file
141
+ // in bounded parts).
142
+ //
143
+ // The stream path carries what a streamed write carries: the content
144
+ // type and the length. Anything else — visibility above all — goes
145
+ // through put(), which applies it WITH the write. Streaming first and
146
+ // setting visibility after would leave a `private` upload public on the
147
+ // local disk (public is its default) until the second call ran.
148
+ const streamable =
149
+ write.visibility === undefined &&
150
+ write.cacheControl === undefined &&
151
+ write.contentDisposition === undefined;
152
+ if (moveAs === "stream" && streamable) {
153
+ await disk.putStream(normalized, file.stream(), {
154
+ contentType: write.contentType,
155
+ contentLength: file.size,
156
+ });
157
+ } else {
158
+ await disk.put(normalized, file.content, write);
159
+ }
160
+
161
+ try {
162
+ file.meta.url = await disk.getUrl(normalized);
163
+ } catch {
164
+ // The object is stored: a disk that cannot name a URL for it (a
165
+ // private local file without a signing secret) leaves `meta.url`
166
+ // unset rather than failing a move that succeeded.
167
+ }
168
+ // NAMED DEVIATION: recorded under the key the object is actually stored
169
+ // at, not the one passed in (upstream records the raw key):
170
+ // `/avatars//1.png` is recorded as `avatars/1.png`.
171
+ file.markAsMoved(normalized, normalized);
172
+ }
173
+
174
+ function invalidOptions(what: string): ArchiveError {
175
+ return new ArchiveError(
176
+ "E_ARCHIVE_INVALID_MOVE_OPTIONS",
177
+ `Invalid moveToDisk() options: ${what}`,
178
+ {
179
+ hint: "moveToDisk(key, disk?, { visibility, contentType, cacheControl, contentDisposition, contentLength, moveAs }).",
180
+ },
181
+ );
182
+ }
183
+
184
+ function optionalString(
185
+ value: object,
186
+ name: "contentType" | "cacheControl" | "contentDisposition",
187
+ ): string | undefined {
188
+ const field: unknown = Reflect.get(value, name);
189
+ if (field === undefined || typeof field === "string") return field;
190
+ throw invalidOptions(`${name} must be a string`);
191
+ }
192
+
193
+ /**
194
+ * Read the options the application passed. A value outside what a field
195
+ * accepts is refused, not ignored: `visibility: 'privat'` must not store a
196
+ * public object.
197
+ */
198
+ function parseOptions(value: unknown): MoveToDiskOptions {
199
+ if (value === undefined) return {};
200
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
201
+ throw invalidOptions("expected an object");
202
+ }
203
+ const visibility: unknown = Reflect.get(value, "visibility");
204
+ if (!(visibility === undefined || isVisibility(visibility))) {
205
+ throw invalidOptions("visibility must be 'public' or 'private'");
206
+ }
207
+ const moveAs: unknown = Reflect.get(value, "moveAs");
208
+ if (!(moveAs === undefined || moveAs === "stream" || moveAs === "buffer")) {
209
+ throw invalidOptions("moveAs must be 'stream' or 'buffer'");
210
+ }
211
+ const contentLength: unknown = Reflect.get(value, "contentLength");
212
+ if (
213
+ !(
214
+ contentLength === undefined ||
215
+ (typeof contentLength === "number" &&
216
+ Number.isSafeInteger(contentLength) &&
217
+ contentLength >= 0)
218
+ )
219
+ ) {
220
+ throw invalidOptions("contentLength must be a non-negative integer");
221
+ }
222
+ return {
223
+ visibility,
224
+ moveAs,
225
+ contentLength,
226
+ contentType: optionalString(value, "contentType"),
227
+ cacheControl: optionalString(value, "cacheControl"),
228
+ contentDisposition: optionalString(value, "contentDisposition"),
229
+ };
230
+ }
231
+
232
+ function isVisibility(value: unknown): value is Visibility {
233
+ return value === "public" || value === "private";
234
+ }
package/src/objects.ts CHANGED
@@ -10,6 +10,7 @@
10
10
  */
11
11
 
12
12
  import { basename } from "node:path";
13
+ import { normalizeKey } from "./keys.js";
13
14
  import type {
14
15
  Metadata,
15
16
  SignedUrlOptions,
@@ -57,8 +58,10 @@ export class DriveFile {
57
58
  #metadata?: Metadata;
58
59
 
59
60
  constructor(key: string, driver: StorageDriver, metadata?: Metadata) {
60
- this.key = key;
61
- this.name = basename(key);
61
+ // Normalised like every key a disk accepts, so a handle built from a
62
+ // stored snapshot or an untrusted name cannot address outside the disk.
63
+ this.key = normalizeKey(key);
64
+ this.name = basename(this.key);
62
65
  this.#driver = driver;
63
66
  this.#metadata = metadata;
64
67
  }
@@ -0,0 +1,171 @@
1
+ /// <reference lib="dom" />
2
+ // Uses the WHATWG fetch/streams globals, which live in the DOM lib even on
3
+ // Node. Referenced here so a consumer whose `lib` omits DOM still typechecks
4
+ // our sources.
5
+ /**
6
+ * One request to a storage provider, bounded by an IDLE timeout.
7
+ *
8
+ * The bound has to catch a provider that stops answering, and nothing else.
9
+ * A wall-clock signal on the whole exchange (`AbortSignal.timeout` handed to
10
+ * `fetch`) also covers the body, in both directions: a 2 GB download piped to
11
+ * a slow client, or a 5 MiB part sent over a slow uplink, failed once it had
12
+ * been running for the configured time, however steadily it was progressing.
13
+ *
14
+ * So the timer measures only the time spent WAITING ON THE PROVIDER:
15
+ *
16
+ * - while the request body goes out, it restarts every time the transport
17
+ * asks for the next slice (the provider is accepting bytes);
18
+ * - while the response headers are awaited, it runs;
19
+ * - while the response body is read, it runs only between asking the
20
+ * provider for a chunk and receiving it. A consumer that reads slowly is
21
+ * not the provider stalling, so the clock is stopped while the consumer
22
+ * holds a chunk.
23
+ */
24
+
25
+ import { ArchiveError } from "./errors.js";
26
+
27
+ /** Size of the slices an outgoing body is handed to the transport in. */
28
+ const UPLOAD_SLICE = 64 * 1024;
29
+
30
+ /** Statuses a `Response` may not be constructed with a body for. */
31
+ const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
32
+
33
+ function timeoutError(ms: number): ArchiveError {
34
+ return new ArchiveError(
35
+ "E_ARCHIVE_REQUEST_TIMEOUT",
36
+ `The storage provider did not answer within ${ms}ms.`,
37
+ {
38
+ hint: "The bound is an idle timeout: raise `requestTimeoutMs` for a slow link, or check connectivity to the bucket.",
39
+ },
40
+ );
41
+ }
42
+
43
+ /**
44
+ * `fetch` with an idle timeout of `ms` (0 or less disables it).
45
+ *
46
+ * The returned response's body, when it has one, is a stream that keeps the
47
+ * same idle bound while it is read; a stall surfaces as
48
+ * `E_ARCHIVE_REQUEST_TIMEOUT` from the read, not as a hang.
49
+ */
50
+ export async function fetchWithIdleTimeout(
51
+ url: string,
52
+ init: RequestInit,
53
+ ms: number,
54
+ ): Promise<Response> {
55
+ if (ms <= 0) return fetch(url, init);
56
+
57
+ const controller = new AbortController();
58
+ let timer: ReturnType<typeof setTimeout> | undefined;
59
+ let timedOut = false;
60
+ const stop = (): void => {
61
+ if (timer !== undefined) clearTimeout(timer);
62
+ timer = undefined;
63
+ };
64
+ const arm = (): void => {
65
+ stop();
66
+ timer = setTimeout(() => {
67
+ timedOut = true;
68
+ controller.abort(timeoutError(ms));
69
+ }, ms);
70
+ };
71
+
72
+ // `duplex` is what Node's fetch requires for a stream body; the DOM lib's
73
+ // RequestInit predates it.
74
+ const request: RequestInit & { duplex?: "half" } = {
75
+ ...init,
76
+ signal: controller.signal,
77
+ };
78
+ const body = init.body;
79
+ if (body instanceof Uint8Array && body.byteLength > UPLOAD_SLICE) {
80
+ // Handed over slice by slice, so each request for the next slice is
81
+ // evidence the provider is still taking bytes. The declared length
82
+ // keeps the request a plain fixed-length one: providers refuse a
83
+ // chunked PUT, and a stream body would otherwise be sent chunked.
84
+ const headers = new Headers(init.headers);
85
+ headers.set("content-length", String(body.byteLength));
86
+ let offset = 0;
87
+ request.headers = headers;
88
+ request.body = new ReadableStream<Uint8Array>(
89
+ {
90
+ pull(stream) {
91
+ arm();
92
+ const end = Math.min(offset + UPLOAD_SLICE, body.byteLength);
93
+ stream.enqueue(body.subarray(offset, end));
94
+ offset = end;
95
+ if (offset >= body.byteLength) stream.close();
96
+ },
97
+ },
98
+ { highWaterMark: 0 },
99
+ );
100
+ request.duplex = "half";
101
+ }
102
+
103
+ arm();
104
+ let response: Response;
105
+ try {
106
+ response = await fetch(url, request);
107
+ } catch (err) {
108
+ stop();
109
+ if (timedOut) throw timeoutError(ms);
110
+ throw err;
111
+ }
112
+ stop();
113
+
114
+ const source = response.body;
115
+ // A null-body status cannot be rebuilt with a body, and has none to read.
116
+ if (source === null || NULL_BODY_STATUSES.has(response.status)) {
117
+ return response;
118
+ }
119
+ // Locked on the first read only: a caller that never reads the body (a
120
+ // DELETE, a HEAD-like check) leaves it exactly as fetch returned it.
121
+ let locked: ReadableStreamDefaultReader<Uint8Array> | undefined;
122
+ const reader = (): ReadableStreamDefaultReader<Uint8Array> => {
123
+ locked ??= source.getReader();
124
+ return locked;
125
+ };
126
+ const guarded = new ReadableStream<Uint8Array>(
127
+ {
128
+ async pull(stream) {
129
+ const upstream = reader();
130
+ arm();
131
+ let chunk: ReadableStreamReadResult<Uint8Array>;
132
+ try {
133
+ chunk = await upstream.read();
134
+ } catch (err) {
135
+ stop();
136
+ if (timedOut) throw timeoutError(ms);
137
+ throw err;
138
+ }
139
+ stop();
140
+ if (chunk.done) stream.close();
141
+ else stream.enqueue(chunk.value);
142
+ },
143
+ cancel(reason) {
144
+ stop();
145
+ return reader().cancel(reason);
146
+ },
147
+ },
148
+ // Pull only on demand: the clock must not run on read-ahead the
149
+ // consumer has not asked for.
150
+ { highWaterMark: 0 },
151
+ );
152
+ return new Response(guarded, {
153
+ status: response.status,
154
+ statusText: response.statusText,
155
+ headers: response.headers,
156
+ });
157
+ }
158
+
159
+ /**
160
+ * Bytes as a request body, without copying when they can be shared.
161
+ *
162
+ * A Node `Buffer` may sit on a `SharedArrayBuffer`, which a request body
163
+ * cannot be: the view is reused as is over a plain `ArrayBuffer`, and copied
164
+ * only otherwise.
165
+ */
166
+ export function requestBody(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
167
+ const { buffer } = bytes;
168
+ return buffer instanceof ArrayBuffer
169
+ ? new Uint8Array(buffer, bytes.byteOffset, bytes.byteLength)
170
+ : new Uint8Array(bytes);
171
+ }
@@ -10,7 +10,7 @@
10
10
  * Populated by `ArchiveProvider.boot()`.
11
11
  */
12
12
 
13
- import type { StorageManager } from "../StorageManager.js";
13
+ import { StorageManager } from "../StorageManager.js";
14
14
 
15
15
  let instance: StorageManager | undefined;
16
16
  let resolve: (() => StorageManager) | undefined;
@@ -53,7 +53,20 @@ export function clearStorage(): void {
53
53
  instance = undefined;
54
54
  }
55
55
 
56
- const storage: StorageManager = new Proxy({} as StorageManager, {
56
+ /**
57
+ * The proxy's target: an object of the right type that is never used —
58
+ * every read goes to the bound instance through the `get` trap. Built from
59
+ * the prototype and proven by `instanceof`, so no cast stands in for it.
60
+ */
61
+ function inertTarget(): StorageManager {
62
+ const target: unknown = Object.create(StorageManager.prototype);
63
+ if (!(target instanceof StorageManager)) {
64
+ throw new Error("[archive] could not build the storage accessor");
65
+ }
66
+ return target;
67
+ }
68
+
69
+ const storage: StorageManager = new Proxy(inertTarget(), {
57
70
  get(_target, prop) {
58
71
  // A module loader inspects what it imports before anyone uses it: it reads
59
72
  // `then` to decide whether the namespace is thenable, and various symbols