@c9up/archive 0.1.3
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/LICENSE +21 -0
- package/README.md +35 -0
- package/dist/ArchiveProvider.d.ts +32 -0
- package/dist/ArchiveProvider.d.ts.map +1 -0
- package/dist/ArchiveProvider.js +91 -0
- package/dist/ArchiveProvider.js.map +1 -0
- package/dist/GcsDriver.d.ts +41 -0
- package/dist/GcsDriver.d.ts.map +1 -0
- package/dist/GcsDriver.js +387 -0
- package/dist/GcsDriver.js.map +1 -0
- package/dist/S3Driver.d.ts +50 -0
- package/dist/S3Driver.d.ts.map +1 -0
- package/dist/S3Driver.js +642 -0
- package/dist/S3Driver.js.map +1 -0
- package/dist/StaticMiddleware.d.ts +46 -0
- package/dist/StaticMiddleware.d.ts.map +1 -0
- package/dist/StaticMiddleware.js +121 -0
- package/dist/StaticMiddleware.js.map +1 -0
- package/dist/StorageManager.d.ts +178 -0
- package/dist/StorageManager.d.ts.map +1 -0
- package/dist/StorageManager.js +405 -0
- package/dist/StorageManager.js.map +1 -0
- package/dist/errors.d.ts +11 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +14 -0
- package/dist/errors.js.map +1 -0
- package/dist/expiry.d.ts +15 -0
- package/dist/expiry.d.ts.map +1 -0
- package/dist/expiry.js +26 -0
- package/dist/expiry.js.map +1 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -0
- package/dist/mime-types.d.ts +17 -0
- package/dist/mime-types.d.ts.map +1 -0
- package/dist/mime-types.js +47 -0
- package/dist/mime-types.js.map +1 -0
- package/dist/services/main.d.ts +19 -0
- package/dist/services/main.d.ts.map +1 -0
- package/dist/services/main.js +33 -0
- package/dist/services/main.js.map +1 -0
- package/dist/signed-route.d.ts +61 -0
- package/dist/signed-route.d.ts.map +1 -0
- package/dist/signed-route.js +155 -0
- package/dist/signed-route.js.map +1 -0
- package/dist/testing/FakeStorage.d.ts +72 -0
- package/dist/testing/FakeStorage.d.ts.map +1 -0
- package/dist/testing/FakeStorage.js +266 -0
- package/dist/testing/FakeStorage.js.map +1 -0
- package/package.json +67 -0
- package/src/ArchiveProvider.ts +134 -0
- package/src/GcsDriver.ts +490 -0
- package/src/S3Driver.ts +791 -0
- package/src/StaticMiddleware.ts +175 -0
- package/src/StorageManager.ts +627 -0
- package/src/errors.ts +14 -0
- package/src/expiry.ts +41 -0
- package/src/index.ts +41 -0
- package/src/mime-types.ts +51 -0
- package/src/services/main.ts +41 -0
- package/src/signed-route.ts +223 -0
- package/src/testing/FakeStorage.ts +372 -0
package/package.json
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@c9up/archive",
|
|
3
|
+
"version": "0.1.3",
|
|
4
|
+
"description": "Archive — File storage abstraction for the Ream framework (Local + S3-compatible drivers)",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js"
|
|
13
|
+
},
|
|
14
|
+
"./provider": {
|
|
15
|
+
"types": "./dist/ArchiveProvider.d.ts",
|
|
16
|
+
"import": "./dist/ArchiveProvider.js"
|
|
17
|
+
},
|
|
18
|
+
"./services/main": {
|
|
19
|
+
"types": "./dist/services/main.d.ts",
|
|
20
|
+
"import": "./dist/services/main.js"
|
|
21
|
+
},
|
|
22
|
+
"./signed-route": {
|
|
23
|
+
"types": "./dist/signed-route.d.ts",
|
|
24
|
+
"import": "./dist/signed-route.js"
|
|
25
|
+
},
|
|
26
|
+
"./testing": {
|
|
27
|
+
"types": "./dist/testing/FakeStorage.d.ts",
|
|
28
|
+
"import": "./dist/testing/FakeStorage.js"
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
"peerDependencies": {
|
|
32
|
+
"@c9up/ream": "^0.1.0"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"@types/node": "^22.19.15",
|
|
36
|
+
"typescript": "^6.0.2",
|
|
37
|
+
"vitest": "^4.1.2"
|
|
38
|
+
},
|
|
39
|
+
"files": [
|
|
40
|
+
"LICENSE",
|
|
41
|
+
"README.md",
|
|
42
|
+
"dist",
|
|
43
|
+
"src"
|
|
44
|
+
],
|
|
45
|
+
"engines": {
|
|
46
|
+
"node": ">=22.0.0"
|
|
47
|
+
},
|
|
48
|
+
"publishConfig": {
|
|
49
|
+
"access": "public"
|
|
50
|
+
},
|
|
51
|
+
"peerDependenciesMeta": {
|
|
52
|
+
"@c9up/ream": {
|
|
53
|
+
"optional": true
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
"repository": {
|
|
57
|
+
"type": "git",
|
|
58
|
+
"url": "git+https://github.com/C9up/archive.git"
|
|
59
|
+
},
|
|
60
|
+
"scripts": {
|
|
61
|
+
"build": "tsc -p tsconfig.build.json",
|
|
62
|
+
"typecheck": "tsc --noEmit",
|
|
63
|
+
"test": "vitest run",
|
|
64
|
+
"lint": "biome check src/",
|
|
65
|
+
"test:coverage": "vitest run --coverage"
|
|
66
|
+
}
|
|
67
|
+
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ArchiveProvider — registers a shared StorageManager in the host
|
|
3
|
+
* framework's container. Apps add `@c9up/archive/provider` to their
|
|
4
|
+
* `reamrc.ts` providers list and configure the driver under the
|
|
5
|
+
* `archive` config key.
|
|
6
|
+
*
|
|
7
|
+
* Duck-typed against `ArchiveAppContext` so archive does NOT import
|
|
8
|
+
* `@c9up/ream` — keeps the package publishable standalone.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* // reamrc.ts
|
|
12
|
+
* providers: [() => import('@c9up/archive/provider')]
|
|
13
|
+
*
|
|
14
|
+
* // config/archive.ts
|
|
15
|
+
* export default {
|
|
16
|
+
* driver: 'local',
|
|
17
|
+
* local: { root: './storage' },
|
|
18
|
+
* }
|
|
19
|
+
*
|
|
20
|
+
* // anywhere
|
|
21
|
+
* import storage from '@c9up/archive/services/main'
|
|
22
|
+
* await storage.put('uploads/avatar.png', buffer)
|
|
23
|
+
*/
|
|
24
|
+
import { ArchiveError } from "./errors.js";
|
|
25
|
+
|
|
26
|
+
import { type GcsConfig, GcsDriver } from "./GcsDriver.js";
|
|
27
|
+
import { type S3Config, S3Driver } from "./S3Driver.js";
|
|
28
|
+
import {
|
|
29
|
+
LocalDriver,
|
|
30
|
+
type StorageDriver,
|
|
31
|
+
StorageManager,
|
|
32
|
+
} from "./StorageManager.js";
|
|
33
|
+
import { setStorage } from "./services/main.js";
|
|
34
|
+
|
|
35
|
+
interface ArchiveContainer {
|
|
36
|
+
singleton(token: unknown, factory: () => unknown): void;
|
|
37
|
+
resolve<T = unknown>(token: unknown): T;
|
|
38
|
+
}
|
|
39
|
+
interface ArchiveConfigStore {
|
|
40
|
+
get<T = unknown>(key: string): T | undefined;
|
|
41
|
+
}
|
|
42
|
+
export interface ArchiveAppContext {
|
|
43
|
+
container: ArchiveContainer;
|
|
44
|
+
config: ArchiveConfigStore;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface ArchiveConfig {
|
|
48
|
+
driver: "local" | "s3" | "gcs";
|
|
49
|
+
local?: { root: string };
|
|
50
|
+
s3?: S3Config;
|
|
51
|
+
gcs?: GcsConfig;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const DEFAULT_CONFIG: ArchiveConfig = {
|
|
55
|
+
driver: "local",
|
|
56
|
+
local: { root: "./storage" },
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
export default class ArchiveProvider {
|
|
60
|
+
constructor(protected app: ArchiveAppContext) {}
|
|
61
|
+
|
|
62
|
+
register(): void {
|
|
63
|
+
this.app.container.singleton(StorageManager, () => {
|
|
64
|
+
const config =
|
|
65
|
+
this.app.config.get<ArchiveConfig>("archive") ?? DEFAULT_CONFIG;
|
|
66
|
+
const driver: StorageDriver = buildDriver(config);
|
|
67
|
+
return new StorageManager(driver);
|
|
68
|
+
});
|
|
69
|
+
this.app.container.singleton("storage", () =>
|
|
70
|
+
this.app.container.resolve<StorageManager>(StorageManager),
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
async boot(): Promise<void> {
|
|
75
|
+
// Skip eager validation when archive is unconfigured: an app that
|
|
76
|
+
// registers this provider but never uses storage should not trigger
|
|
77
|
+
// LocalDriver's mkdirSync of './storage' at boot (breaks on
|
|
78
|
+
// read-only rootfs). Explicit (object-shaped) configs still fail
|
|
79
|
+
// fast.
|
|
80
|
+
const archive = this.app.config.get<ArchiveConfig>("archive");
|
|
81
|
+
if (
|
|
82
|
+
archive === undefined ||
|
|
83
|
+
archive === null ||
|
|
84
|
+
typeof archive !== "object"
|
|
85
|
+
) {
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
const manager = this.app.container.resolve<StorageManager>(StorageManager);
|
|
89
|
+
setStorage(manager);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
async start(): Promise<void> {}
|
|
93
|
+
async ready(): Promise<void> {}
|
|
94
|
+
async shutdown(): Promise<void> {}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function buildDriver(config: ArchiveConfig): StorageDriver {
|
|
98
|
+
if (config.driver === "s3") {
|
|
99
|
+
if (!config.s3) {
|
|
100
|
+
throw new ArchiveError(
|
|
101
|
+
"ARCHIVE_CONFIG_MISSING",
|
|
102
|
+
"Archive config.driver is 's3' but config.s3 is missing",
|
|
103
|
+
{
|
|
104
|
+
hint: "Provide { bucket, accessKeyId, secretAccessKey, region?, endpoint? } under config.archive.s3.",
|
|
105
|
+
},
|
|
106
|
+
);
|
|
107
|
+
}
|
|
108
|
+
return new S3Driver(config.s3);
|
|
109
|
+
}
|
|
110
|
+
if (config.driver === "gcs") {
|
|
111
|
+
if (!config.gcs) {
|
|
112
|
+
throw new ArchiveError(
|
|
113
|
+
"ARCHIVE_CONFIG_MISSING",
|
|
114
|
+
"Archive config.driver is 'gcs' but config.gcs is missing",
|
|
115
|
+
{
|
|
116
|
+
hint: "Provide { bucket, serviceAccount: { client_email, private_key } } under config.archive.gcs.",
|
|
117
|
+
},
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
return new GcsDriver(config.gcs);
|
|
121
|
+
}
|
|
122
|
+
if (config.driver === "local") {
|
|
123
|
+
const root = config.local?.root ?? "./storage";
|
|
124
|
+
return new LocalDriver(root);
|
|
125
|
+
}
|
|
126
|
+
// Reject unknown driver values explicitly so a typo like
|
|
127
|
+
// `{ driver: 'locla' }` does not silently fall through to the
|
|
128
|
+
// local driver and write files to an unexpected location.
|
|
129
|
+
throw new ArchiveError(
|
|
130
|
+
"ARCHIVE_INVALID_DRIVER",
|
|
131
|
+
`Archive config.driver must be 'local', 's3', or 'gcs', got '${String(config.driver)}'`,
|
|
132
|
+
{ hint: "Set config.archive.driver to 'local', 's3', or 'gcs'." },
|
|
133
|
+
);
|
|
134
|
+
}
|
package/src/GcsDriver.ts
ADDED
|
@@ -0,0 +1,490 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GcsDriver — Google Cloud Storage driver.
|
|
3
|
+
*
|
|
4
|
+
* Uses the fetch API + a hand-rolled V4 signer — no external SDK.
|
|
5
|
+
* Implements the full StorageDriver contract: put/get/delete/exists,
|
|
6
|
+
* url/publicUrl, getSignedUrl, getMetadata, setVisibility, putStream,
|
|
7
|
+
* getStream.
|
|
8
|
+
*
|
|
9
|
+
* @implements MISS-24
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { createHash, createSign } from "node:crypto";
|
|
13
|
+
import { Readable } from "node:stream";
|
|
14
|
+
import type { ReadableStream as NodeReadableStream } from "node:stream/web";
|
|
15
|
+
import { ArchiveError } from "./errors.js";
|
|
16
|
+
import { assertValidExpiry, DEFAULT_EXPIRES_IN } from "./expiry.js";
|
|
17
|
+
import { inferMimeType } from "./mime-types.js";
|
|
18
|
+
import type {
|
|
19
|
+
Metadata,
|
|
20
|
+
PutStreamOptions,
|
|
21
|
+
SignedUrlOptions,
|
|
22
|
+
StorageDriver,
|
|
23
|
+
StorageEntry,
|
|
24
|
+
Visibility,
|
|
25
|
+
} from "./StorageManager.js";
|
|
26
|
+
|
|
27
|
+
/** GCS V4 strict URL encoding — identical to AWS's RFC3986-unreserved
|
|
28
|
+
* set. Duplicated from `S3Driver.ts` on purpose: per cerebrum rule,
|
|
29
|
+
* drivers do not share helpers even within the package. */
|
|
30
|
+
function gcsStrictEncode(str: string): string {
|
|
31
|
+
return encodeURIComponent(str).replace(
|
|
32
|
+
/[!*'()]/g,
|
|
33
|
+
(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Encode an object path segment-by-segment, preserving `/`. */
|
|
38
|
+
function gcsEncodeKey(key: string): string {
|
|
39
|
+
return key.split("/").map(gcsStrictEncode).join("/");
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Type guard matching the same pattern as `S3Driver.hasDestroy` —
|
|
43
|
+
* duplicated on purpose (package-local). */
|
|
44
|
+
function hasDestroy(x: unknown): x is { destroy(err?: Error): void } {
|
|
45
|
+
return (
|
|
46
|
+
typeof x === "object" &&
|
|
47
|
+
x !== null &&
|
|
48
|
+
typeof (x as { destroy?: unknown }).destroy === "function"
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Base64url encode a Buffer (RFC 4648 §5) — no `=` padding, `-` / `_`
|
|
53
|
+
* alphabet. Required by JWT. */
|
|
54
|
+
function base64url(buf: Buffer): string {
|
|
55
|
+
return buf
|
|
56
|
+
.toString("base64")
|
|
57
|
+
.replace(/=+$/, "")
|
|
58
|
+
.replace(/\+/g, "-")
|
|
59
|
+
.replace(/\//g, "_");
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface GcsServiceAccount {
|
|
63
|
+
client_email: string;
|
|
64
|
+
private_key: string;
|
|
65
|
+
project_id?: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface GcsConfig {
|
|
69
|
+
bucket: string;
|
|
70
|
+
serviceAccount: GcsServiceAccount;
|
|
71
|
+
/** Optional CDN prefix for public URLs (e.g. `https://cdn.example.com`). */
|
|
72
|
+
publicUrl?: string;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const GCS_API_ROOT = "https://storage.googleapis.com";
|
|
76
|
+
const GCS_UPLOAD_ROOT = "https://storage.googleapis.com/upload/storage/v1";
|
|
77
|
+
const GCS_META_ROOT = "https://storage.googleapis.com/storage/v1";
|
|
78
|
+
const GCS_OAUTH_URL = "https://oauth2.googleapis.com/token";
|
|
79
|
+
const GCS_SCOPE = "https://www.googleapis.com/auth/devstorage.read_write";
|
|
80
|
+
|
|
81
|
+
export class GcsDriver implements StorageDriver {
|
|
82
|
+
#config: GcsConfig;
|
|
83
|
+
#cachedToken: { value: string; expiresAt: number } | null = null;
|
|
84
|
+
|
|
85
|
+
constructor(config: GcsConfig) {
|
|
86
|
+
if (!config.bucket) {
|
|
87
|
+
throw new Error("GcsDriver: `bucket` is required.");
|
|
88
|
+
}
|
|
89
|
+
if (
|
|
90
|
+
!config.serviceAccount?.client_email ||
|
|
91
|
+
!config.serviceAccount?.private_key
|
|
92
|
+
) {
|
|
93
|
+
throw new Error(
|
|
94
|
+
"GcsDriver: `serviceAccount.client_email` and `serviceAccount.private_key` are required.",
|
|
95
|
+
);
|
|
96
|
+
}
|
|
97
|
+
this.#config = config;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
async put(filePath: string, content: Buffer | string): Promise<void> {
|
|
101
|
+
const body = typeof content === "string" ? Buffer.from(content) : content;
|
|
102
|
+
const token = await this.#getAccessToken();
|
|
103
|
+
const url = `${GCS_UPLOAD_ROOT}/b/${this.#config.bucket}/o?uploadType=media&name=${gcsStrictEncode(filePath)}`;
|
|
104
|
+
const mime =
|
|
105
|
+
inferMimeType(extFromPath(filePath)) || "application/octet-stream";
|
|
106
|
+
const res = await fetch(url, {
|
|
107
|
+
method: "POST",
|
|
108
|
+
headers: {
|
|
109
|
+
authorization: `Bearer ${token}`,
|
|
110
|
+
"content-type": mime,
|
|
111
|
+
},
|
|
112
|
+
body: body as BodyInit,
|
|
113
|
+
});
|
|
114
|
+
if (!res.ok) {
|
|
115
|
+
throw new Error(`GCS PUT failed (${res.status}): ${await res.text()}`);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async putStream(
|
|
120
|
+
filePath: string,
|
|
121
|
+
readable: NodeJS.ReadableStream,
|
|
122
|
+
options?: PutStreamOptions,
|
|
123
|
+
): Promise<void> {
|
|
124
|
+
// Single-PUT path only for this story. Resumable upload parity is
|
|
125
|
+
// deferred — document upgrade path here when a real large-file
|
|
126
|
+
// case appears.
|
|
127
|
+
const maxBytes = options?.contentLength ?? Number.MAX_SAFE_INTEGER;
|
|
128
|
+
const buf = await collectToBuffer(readable, maxBytes);
|
|
129
|
+
const token = await this.#getAccessToken();
|
|
130
|
+
const url = `${GCS_UPLOAD_ROOT}/b/${this.#config.bucket}/o?uploadType=media&name=${gcsStrictEncode(filePath)}`;
|
|
131
|
+
const mime =
|
|
132
|
+
options?.contentType ??
|
|
133
|
+
(inferMimeType(extFromPath(filePath)) || "application/octet-stream");
|
|
134
|
+
const res = await fetch(url, {
|
|
135
|
+
method: "POST",
|
|
136
|
+
headers: {
|
|
137
|
+
authorization: `Bearer ${token}`,
|
|
138
|
+
"content-type": mime,
|
|
139
|
+
},
|
|
140
|
+
body: buf as BodyInit,
|
|
141
|
+
});
|
|
142
|
+
if (!res.ok) {
|
|
143
|
+
throw new Error(`GCS PUT failed (${res.status}): ${await res.text()}`);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
async get(filePath: string): Promise<Buffer | null> {
|
|
148
|
+
const token = await this.#getAccessToken();
|
|
149
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}?alt=media`;
|
|
150
|
+
const res = await fetch(url, {
|
|
151
|
+
method: "GET",
|
|
152
|
+
headers: { authorization: `Bearer ${token}` },
|
|
153
|
+
});
|
|
154
|
+
if (res.status === 404) return null;
|
|
155
|
+
if (!res.ok) throw new Error(`GCS GET failed (${res.status})`);
|
|
156
|
+
return Buffer.from(await res.arrayBuffer());
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
async getStream(filePath: string): Promise<NodeJS.ReadableStream> {
|
|
160
|
+
const token = await this.#getAccessToken();
|
|
161
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}?alt=media`;
|
|
162
|
+
const res = await fetch(url, {
|
|
163
|
+
method: "GET",
|
|
164
|
+
headers: { authorization: `Bearer ${token}` },
|
|
165
|
+
});
|
|
166
|
+
if (res.status === 404) {
|
|
167
|
+
throw new ArchiveError(
|
|
168
|
+
"ARCHIVE_NOT_FOUND",
|
|
169
|
+
`GCS object does not exist at path '${filePath}'`,
|
|
170
|
+
{
|
|
171
|
+
hint: "Confirm the bucket + key and that the object was put() first.",
|
|
172
|
+
},
|
|
173
|
+
);
|
|
174
|
+
}
|
|
175
|
+
if (!res.ok) throw new Error(`GCS GET failed (${res.status})`);
|
|
176
|
+
if (res.body === null) return Readable.from(Buffer.alloc(0));
|
|
177
|
+
return Readable.fromWeb(res.body as NodeReadableStream<Uint8Array>);
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
async delete(filePath: string): Promise<boolean> {
|
|
181
|
+
const token = await this.#getAccessToken();
|
|
182
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}`;
|
|
183
|
+
const res = await fetch(url, {
|
|
184
|
+
method: "DELETE",
|
|
185
|
+
headers: { authorization: `Bearer ${token}` },
|
|
186
|
+
});
|
|
187
|
+
if (res.status === 404) return false;
|
|
188
|
+
return res.ok || res.status === 204;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
async exists(filePath: string): Promise<boolean> {
|
|
192
|
+
const token = await this.#getAccessToken();
|
|
193
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}`;
|
|
194
|
+
const res = await fetch(url, {
|
|
195
|
+
method: "GET",
|
|
196
|
+
headers: { authorization: `Bearer ${token}` },
|
|
197
|
+
});
|
|
198
|
+
if (res.status === 404) return false;
|
|
199
|
+
// Don't swallow 403/5xx as "not found" — would hide access and
|
|
200
|
+
// availability errors. Throw so the caller can distinguish.
|
|
201
|
+
if (!res.ok) {
|
|
202
|
+
throw new Error(`GCS EXISTS failed (${res.status})`);
|
|
203
|
+
}
|
|
204
|
+
return true;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
publicUrl(filePath: string): string {
|
|
208
|
+
if (this.#config.publicUrl) {
|
|
209
|
+
const publicRoot = this.#config.publicUrl.replace(/\/+$/, "");
|
|
210
|
+
return `${publicRoot}/${gcsEncodeKey(filePath)}`;
|
|
211
|
+
}
|
|
212
|
+
return `${GCS_API_ROOT}/${this.#config.bucket}/${gcsEncodeKey(filePath)}`;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
async url(filePath: string): Promise<string> {
|
|
216
|
+
const meta = await this.getMetadata(filePath);
|
|
217
|
+
if (meta.visibility === "public") return this.publicUrl(filePath);
|
|
218
|
+
return this.getSignedUrl(filePath);
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
async getMetadata(filePath: string): Promise<Metadata> {
|
|
222
|
+
const token = await this.#getAccessToken();
|
|
223
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}`;
|
|
224
|
+
const res = await fetch(url, {
|
|
225
|
+
method: "GET",
|
|
226
|
+
headers: { authorization: `Bearer ${token}` },
|
|
227
|
+
});
|
|
228
|
+
if (res.status === 404) {
|
|
229
|
+
throw new ArchiveError(
|
|
230
|
+
"ARCHIVE_NOT_FOUND",
|
|
231
|
+
`GCS object does not exist at path '${filePath}'`,
|
|
232
|
+
{ hint: "Confirm the bucket + key." },
|
|
233
|
+
);
|
|
234
|
+
}
|
|
235
|
+
if (!res.ok) {
|
|
236
|
+
throw new Error(`GCS HEAD failed (${res.status}): ${await res.text()}`);
|
|
237
|
+
}
|
|
238
|
+
const json = (await res.json()) as {
|
|
239
|
+
size?: string;
|
|
240
|
+
contentType?: string;
|
|
241
|
+
updated?: string;
|
|
242
|
+
etag?: string;
|
|
243
|
+
acl?: Array<{ entity?: string; role?: string }>;
|
|
244
|
+
};
|
|
245
|
+
const visibility: Visibility = Array.isArray(json.acl)
|
|
246
|
+
? json.acl.some(
|
|
247
|
+
(a) =>
|
|
248
|
+
a.entity === "allUsers" &&
|
|
249
|
+
(a.role === "READER" || a.role === "OWNER"),
|
|
250
|
+
)
|
|
251
|
+
? "public"
|
|
252
|
+
: "private"
|
|
253
|
+
: "private";
|
|
254
|
+
return {
|
|
255
|
+
size: Number.parseInt(json.size ?? "0", 10),
|
|
256
|
+
mimeType: json.contentType ?? "application/octet-stream",
|
|
257
|
+
lastModified: json.updated ? new Date(json.updated) : new Date(0),
|
|
258
|
+
etag: (json.etag ?? "").replace(/^(W\/)?"(.*)"$/, "$1$2"),
|
|
259
|
+
visibility,
|
|
260
|
+
};
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
|
|
264
|
+
const token = await this.#getAccessToken();
|
|
265
|
+
const base = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}/acl`;
|
|
266
|
+
if (visibility === "public") {
|
|
267
|
+
const res = await fetch(base, {
|
|
268
|
+
method: "POST",
|
|
269
|
+
headers: {
|
|
270
|
+
authorization: `Bearer ${token}`,
|
|
271
|
+
"content-type": "application/json",
|
|
272
|
+
},
|
|
273
|
+
body: JSON.stringify({ entity: "allUsers", role: "READER" }),
|
|
274
|
+
});
|
|
275
|
+
if (!res.ok) {
|
|
276
|
+
throw new Error(
|
|
277
|
+
`GCS setVisibility public failed (${res.status}): ${await res.text()}`,
|
|
278
|
+
);
|
|
279
|
+
}
|
|
280
|
+
} else {
|
|
281
|
+
const res = await fetch(`${base}/allUsers`, {
|
|
282
|
+
method: "DELETE",
|
|
283
|
+
headers: { authorization: `Bearer ${token}` },
|
|
284
|
+
});
|
|
285
|
+
// 404 = already private (no allUsers ACL) — idempotent success.
|
|
286
|
+
if (!res.ok && res.status !== 404) {
|
|
287
|
+
throw new Error(
|
|
288
|
+
`GCS setVisibility private failed (${res.status}): ${await res.text()}`,
|
|
289
|
+
);
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
async copy(from: string, to: string): Promise<void> {
|
|
295
|
+
const token = await this.#getAccessToken();
|
|
296
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(from)}/copyTo/b/${this.#config.bucket}/o/${gcsEncodeKey(to)}`;
|
|
297
|
+
const res = await fetch(url, {
|
|
298
|
+
method: "POST",
|
|
299
|
+
headers: { authorization: `Bearer ${token}` },
|
|
300
|
+
});
|
|
301
|
+
if (res.status === 404) {
|
|
302
|
+
throw new ArchiveError(
|
|
303
|
+
"ARCHIVE_NOT_FOUND",
|
|
304
|
+
`GCS copy source does not exist at path '${from}'`,
|
|
305
|
+
{ hint: "Confirm the source object was put() first." },
|
|
306
|
+
);
|
|
307
|
+
}
|
|
308
|
+
if (!res.ok) {
|
|
309
|
+
throw new Error(`GCS COPY failed (${res.status}): ${await res.text()}`);
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
async move(from: string, to: string): Promise<void> {
|
|
314
|
+
// Non-atomic: copy then delete. Same as S3.
|
|
315
|
+
await this.copy(from, to);
|
|
316
|
+
await this.delete(from);
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
async *list(prefix: string): AsyncIterable<StorageEntry> {
|
|
320
|
+
let pageToken: string | undefined;
|
|
321
|
+
do {
|
|
322
|
+
const params = new URLSearchParams({ prefix });
|
|
323
|
+
if (pageToken) params.set("pageToken", pageToken);
|
|
324
|
+
const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o?${params.toString()}`;
|
|
325
|
+
const token = await this.#getAccessToken();
|
|
326
|
+
const res = await fetch(url, {
|
|
327
|
+
method: "GET",
|
|
328
|
+
headers: { authorization: `Bearer ${token}` },
|
|
329
|
+
});
|
|
330
|
+
if (!res.ok) {
|
|
331
|
+
throw new Error(`GCS LIST failed (${res.status}): ${await res.text()}`);
|
|
332
|
+
}
|
|
333
|
+
const json = (await res.json()) as {
|
|
334
|
+
items?: Array<{ name?: string; size?: string; updated?: string }>;
|
|
335
|
+
nextPageToken?: string;
|
|
336
|
+
};
|
|
337
|
+
for (const item of json.items ?? []) {
|
|
338
|
+
yield {
|
|
339
|
+
path: item.name ?? "",
|
|
340
|
+
size: Number.parseInt(item.size ?? "0", 10),
|
|
341
|
+
lastModified: item.updated ? new Date(item.updated) : new Date(0),
|
|
342
|
+
};
|
|
343
|
+
}
|
|
344
|
+
pageToken = json.nextPageToken;
|
|
345
|
+
} while (pageToken);
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
getSignedUrl(filePath: string, options?: SignedUrlOptions): string {
|
|
349
|
+
const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
|
|
350
|
+
assertValidExpiry(expiresIn);
|
|
351
|
+
const dateStamp = amzDateNow();
|
|
352
|
+
const shortDate = dateStamp.slice(0, 8);
|
|
353
|
+
const scope = `${shortDate}/auto/storage/goog4_request`;
|
|
354
|
+
const credential = `${this.#config.serviceAccount.client_email}/${scope}`;
|
|
355
|
+
|
|
356
|
+
const queryParams: Array<[string, string]> = [
|
|
357
|
+
["X-Goog-Algorithm", "GOOG4-RSA-SHA256"],
|
|
358
|
+
["X-Goog-Credential", credential],
|
|
359
|
+
["X-Goog-Date", dateStamp],
|
|
360
|
+
["X-Goog-Expires", String(expiresIn)],
|
|
361
|
+
["X-Goog-SignedHeaders", "host"],
|
|
362
|
+
];
|
|
363
|
+
const canonicalQs = queryParams
|
|
364
|
+
.slice()
|
|
365
|
+
.sort((a, b) => (a[0] < b[0] ? -1 : 1))
|
|
366
|
+
.map(([k, v]) => `${k}=${gcsStrictEncode(v)}`)
|
|
367
|
+
.join("&");
|
|
368
|
+
|
|
369
|
+
const canonicalRequest = [
|
|
370
|
+
"GET",
|
|
371
|
+
`/${this.#config.bucket}/${gcsEncodeKey(filePath)}`,
|
|
372
|
+
canonicalQs,
|
|
373
|
+
"host:storage.googleapis.com\n",
|
|
374
|
+
"host",
|
|
375
|
+
"UNSIGNED-PAYLOAD",
|
|
376
|
+
].join("\n");
|
|
377
|
+
|
|
378
|
+
const stringToSign = [
|
|
379
|
+
"GOOG4-RSA-SHA256",
|
|
380
|
+
dateStamp,
|
|
381
|
+
scope,
|
|
382
|
+
createHash("sha256").update(canonicalRequest).digest("hex"),
|
|
383
|
+
].join("\n");
|
|
384
|
+
|
|
385
|
+
const signer = createSign("RSA-SHA256");
|
|
386
|
+
signer.update(stringToSign);
|
|
387
|
+
const signature = signer
|
|
388
|
+
.sign(this.#config.serviceAccount.private_key)
|
|
389
|
+
.toString("hex");
|
|
390
|
+
|
|
391
|
+
return `${GCS_API_ROOT}/${this.#config.bucket}/${gcsEncodeKey(filePath)}?${canonicalQs}&X-Goog-Signature=${signature}`;
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/** Fetch or refresh the OAuth access token. Lock-free: concurrent
|
|
395
|
+
* callers may trigger parallel refreshes; last-writer-wins is
|
|
396
|
+
* acceptable because token exchange is idempotent. */
|
|
397
|
+
async #getAccessToken(): Promise<string> {
|
|
398
|
+
const now = Date.now();
|
|
399
|
+
if (
|
|
400
|
+
this.#cachedToken &&
|
|
401
|
+
// Refresh when < 5 min remain before expiry.
|
|
402
|
+
this.#cachedToken.expiresAt - now > 5 * 60 * 1000
|
|
403
|
+
) {
|
|
404
|
+
return this.#cachedToken.value;
|
|
405
|
+
}
|
|
406
|
+
const iat = Math.floor(now / 1000);
|
|
407
|
+
const exp = iat + 3600;
|
|
408
|
+
const header = base64url(
|
|
409
|
+
Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })),
|
|
410
|
+
);
|
|
411
|
+
const claim = base64url(
|
|
412
|
+
Buffer.from(
|
|
413
|
+
JSON.stringify({
|
|
414
|
+
iss: this.#config.serviceAccount.client_email,
|
|
415
|
+
scope: GCS_SCOPE,
|
|
416
|
+
aud: GCS_OAUTH_URL,
|
|
417
|
+
exp,
|
|
418
|
+
iat,
|
|
419
|
+
}),
|
|
420
|
+
),
|
|
421
|
+
);
|
|
422
|
+
const unsigned = `${header}.${claim}`;
|
|
423
|
+
const signer = createSign("RSA-SHA256");
|
|
424
|
+
signer.update(unsigned);
|
|
425
|
+
const sig = base64url(signer.sign(this.#config.serviceAccount.private_key));
|
|
426
|
+
const jwt = `${unsigned}.${sig}`;
|
|
427
|
+
|
|
428
|
+
const body = new URLSearchParams({
|
|
429
|
+
grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
|
|
430
|
+
assertion: jwt,
|
|
431
|
+
}).toString();
|
|
432
|
+
const res = await fetch(GCS_OAUTH_URL, {
|
|
433
|
+
method: "POST",
|
|
434
|
+
headers: { "content-type": "application/x-www-form-urlencoded" },
|
|
435
|
+
body,
|
|
436
|
+
});
|
|
437
|
+
if (!res.ok) {
|
|
438
|
+
throw new Error(
|
|
439
|
+
`GCS token exchange failed (${res.status}): ${await res.text()}`,
|
|
440
|
+
);
|
|
441
|
+
}
|
|
442
|
+
const json = (await res.json()) as {
|
|
443
|
+
access_token?: string;
|
|
444
|
+
expires_in?: number;
|
|
445
|
+
};
|
|
446
|
+
if (!json.access_token) {
|
|
447
|
+
throw new Error("GCS token exchange: access_token missing from response");
|
|
448
|
+
}
|
|
449
|
+
this.#cachedToken = {
|
|
450
|
+
value: json.access_token,
|
|
451
|
+
expiresAt: now + (json.expires_in ?? 3600) * 1000,
|
|
452
|
+
};
|
|
453
|
+
return json.access_token;
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
/** Returns the current instant in basic-ISO8601 form: `YYYYMMDDTHHMMSSZ`. */
|
|
458
|
+
function amzDateNow(): string {
|
|
459
|
+
return `${new Date().toISOString().replace(/[-:]/g, "").split(".")[0]}Z`;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
/** Extract the lowercase file extension from a path (including the dot). */
|
|
463
|
+
function extFromPath(filePath: string): string {
|
|
464
|
+
const idx = filePath.lastIndexOf(".");
|
|
465
|
+
if (idx < 0) return "";
|
|
466
|
+
return filePath.slice(idx).toLowerCase();
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
/** Drain a readable into a Buffer, capped at `maxBytes`. Destroys the
|
|
470
|
+
* upstream on over-limit so FDs/sockets don't leak. Duplicated from
|
|
471
|
+
* `S3Driver.ts` per package-agnostic discipline. */
|
|
472
|
+
async function collectToBuffer(
|
|
473
|
+
readable: NodeJS.ReadableStream,
|
|
474
|
+
maxBytes: number,
|
|
475
|
+
): Promise<Buffer> {
|
|
476
|
+
const chunks: Buffer[] = [];
|
|
477
|
+
let total = 0;
|
|
478
|
+
for await (const chunk of readable) {
|
|
479
|
+
const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as string);
|
|
480
|
+
total += buf.length;
|
|
481
|
+
if (total > maxBytes) {
|
|
482
|
+
if (hasDestroy(readable)) readable.destroy();
|
|
483
|
+
throw new Error(
|
|
484
|
+
`putStream: readable exceeded declared contentLength (${total} > ${maxBytes})`,
|
|
485
|
+
);
|
|
486
|
+
}
|
|
487
|
+
chunks.push(buf);
|
|
488
|
+
}
|
|
489
|
+
return Buffer.concat(chunks, total);
|
|
490
|
+
}
|