@leed-ai/git-gateway-backend-artifacts 0.0.0-stage → 0.1.0
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 +201 -0
- package/README.md +29 -2
- package/dist/artifacts-backend.d.ts +45 -0
- package/dist/artifacts-backend.js +198 -0
- package/dist/artifacts-backend.js.map +1 -0
- package/dist/artifacts-binding.d.ts +38 -0
- package/dist/artifacts-binding.js +9 -0
- package/dist/artifacts-binding.js.map +1 -0
- package/dist/artifacts-errors.d.ts +29 -0
- package/dist/artifacts-errors.js +65 -0
- package/dist/artifacts-errors.js.map +1 -0
- package/dist/artifacts-git-reads.d.ts +24 -0
- package/dist/artifacts-git-reads.js +67 -0
- package/dist/artifacts-git-reads.js.map +1 -0
- package/dist/artifacts-mapping.d.ts +15 -0
- package/dist/artifacts-mapping.js +67 -0
- package/dist/artifacts-mapping.js.map +1 -0
- package/dist/artifacts-rest.d.ts +35 -0
- package/dist/artifacts-rest.js +91 -0
- package/dist/artifacts-rest.js.map +1 -0
- package/dist/package-name.d.ts +3 -0
- package/dist/package-name.js +6 -0
- package/dist/package-name.js.map +1 -0
- package/dist/schemas/artifacts-binding-results.d.ts +80 -0
- package/dist/schemas/artifacts-binding-results.js +160 -0
- package/dist/schemas/artifacts-binding-results.js.map +1 -0
- package/dist/schemas/artifacts-rest-results.d.ts +38 -0
- package/dist/schemas/artifacts-rest-results.js +66 -0
- package/dist/schemas/artifacts-rest-results.js.map +1 -0
- package/package.json +111 -4
- package/src/artifacts-backend.ts +256 -0
- package/src/artifacts-binding.ts +36 -0
- package/src/artifacts-errors.ts +85 -0
- package/src/artifacts-git-reads.ts +76 -0
- package/src/artifacts-mapping.ts +57 -0
- package/src/artifacts-rest.ts +112 -0
- package/src/package-name.ts +4 -0
- package/src/schemas/artifacts-binding-results.ts +205 -0
- package/src/schemas/artifacts-rest-results.ts +100 -0
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { isGatewayError } from '@leed-ai/git-gateway-contract/gateway-error';
|
|
3
|
+
import type { Commit } from '@leed-ai/git-gateway-contract/schemas/commit';
|
|
4
|
+
import { FilePath, RepoName, Revision } from '@leed-ai/git-gateway-contract/schemas/names';
|
|
5
|
+
import { Sha } from '@leed-ai/git-gateway-contract/schemas/sha';
|
|
6
|
+
import { GitAccess, GitRemote } from '@leed-ai/git-gateway-contract/storage/git-remote';
|
|
7
|
+
import type { StorageBackend } from '@leed-ai/git-gateway-contract/storage/storage-backend';
|
|
8
|
+
import { parseStorageInput } from '@leed-ai/git-gateway-contract/storage/storage-input';
|
|
9
|
+
import { StorageLogOptions, StorageRef } from '@leed-ai/git-gateway-contract/storage/storage-read';
|
|
10
|
+
import {
|
|
11
|
+
CreateStorageRepoOptions,
|
|
12
|
+
StorageRepoInfo,
|
|
13
|
+
} from '@leed-ai/git-gateway-contract/storage/storage-repo-info';
|
|
14
|
+
import type { StorageTreeEntry } from '@leed-ai/git-gateway-contract/storage/storage-tree-entry';
|
|
15
|
+
import { z } from 'zod';
|
|
16
|
+
|
|
17
|
+
import {
|
|
18
|
+
releaseHandle,
|
|
19
|
+
type ArtifactsNamespaceBinding,
|
|
20
|
+
type ArtifactsRepoHandle,
|
|
21
|
+
} from './artifacts-binding.ts';
|
|
22
|
+
import { artifactsErrorCode, isRepoNotFound, toGatewayError } from './artifacts-errors.ts';
|
|
23
|
+
import { blobIdAt, isUnserializableBlob, readBlobOverGit } from './artifacts-git-reads.ts';
|
|
24
|
+
import { toContractCommit, toStorageTreeEntry } from './artifacts-mapping.ts';
|
|
25
|
+
import {
|
|
26
|
+
ArtifactsCommit,
|
|
27
|
+
ArtifactsCreateResult,
|
|
28
|
+
ArtifactsRepoInfo,
|
|
29
|
+
ArtifactsToken,
|
|
30
|
+
ArtifactsTreeEntry,
|
|
31
|
+
} from './schemas/artifacts-binding-results.ts';
|
|
32
|
+
|
|
33
|
+
/** Options of an {@link ArtifactsBackend}. */
|
|
34
|
+
export interface ArtifactsBackendOptions {
|
|
35
|
+
/** The Artifacts binding, `env.ARTIFACTS`. */
|
|
36
|
+
readonly binding: ArtifactsNamespaceBinding;
|
|
37
|
+
/** Lifetime of the tokens gitRemote() mints, in seconds: 60–31536000, default 300. */
|
|
38
|
+
readonly tokenTtlSeconds?: number;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const TokenTtl = z.int().min(60).max(31_536_000);
|
|
42
|
+
/**
|
|
43
|
+
* The name the binding resolves for a StorageRef. The live binding resolves short names ("main",
|
|
44
|
+
* "v1", a commit id) and answers nothing for fully qualified ones ("refs/heads/main" → no commits),
|
|
45
|
+
* so the "refs/heads/" or "refs/tags/" prefix is dropped. The binding then resolves the name as git
|
|
46
|
+
* does a short name, so a tag and a branch sharing one name cannot be told apart.
|
|
47
|
+
*/
|
|
48
|
+
export function bindingRef(ref: string): string {
|
|
49
|
+
return ref.replace(/^refs\/(?:heads|tags)\//, '');
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const bytesOf = async (blob: Blob | null): Promise<Uint8Array | null> =>
|
|
53
|
+
blob === null ? null : new Uint8Array(await blob.arrayBuffer());
|
|
54
|
+
|
|
55
|
+
/** Parses a host result; a mismatch means the host answered something the contract cannot use. */
|
|
56
|
+
function parseHost<S extends z.ZodType>(schema: S, value: unknown): z.output<S> {
|
|
57
|
+
return schema.parse(value);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* A {@link StorageBackend} over a Cloudflare Artifacts namespace, through the Workers binding:
|
|
62
|
+
* repository lifecycle (create, info, delete), reads (readCommit, readTree, readBlob, readFile,
|
|
63
|
+
* log) and per-call tokens for the repository's git remote. Artifacts has no write or ref API, so
|
|
64
|
+
* every write is a git-receive-pack push to {@link gitRemote}; refs are resolved through the
|
|
65
|
+
* binding's log. Every binding result is parsed with Zod; binding errors become GatewayErrors.
|
|
66
|
+
* Where the binding cannot carry a Blob back (wrangler's remote binding under `wrangler dev`),
|
|
67
|
+
* readBlob and readFile fall back to fetching the blob over the repository's git remote.
|
|
68
|
+
*/
|
|
69
|
+
export class ArtifactsBackend implements StorageBackend {
|
|
70
|
+
readonly #binding: ArtifactsNamespaceBinding;
|
|
71
|
+
readonly #ttl: number;
|
|
72
|
+
|
|
73
|
+
constructor(options: ArtifactsBackendOptions) {
|
|
74
|
+
this.#binding = options.binding;
|
|
75
|
+
this.#ttl = TokenTtl.parse(options.tokenTtlSeconds ?? 300);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
async createRepo(name: string, options: CreateStorageRepoOptions = {}): Promise<StorageRepoInfo> {
|
|
79
|
+
const repo = parseStorageInput(RepoName, name);
|
|
80
|
+
const { defaultBranch } = parseStorageInput(CreateStorageRepoOptions, options);
|
|
81
|
+
try {
|
|
82
|
+
const created = parseHost(
|
|
83
|
+
ArtifactsCreateResult,
|
|
84
|
+
await this.#binding.create(repo, { setDefaultBranch: defaultBranch }),
|
|
85
|
+
);
|
|
86
|
+
return await this.#withRepo(repo, 'createRepo', async (handle) => {
|
|
87
|
+
// The initial write token is never handed out; revoking it is hygiene, so a failure to
|
|
88
|
+
// revoke (the token then simply expires) does not fail the creation.
|
|
89
|
+
await handle.revokeToken(created.token).catch(() => false);
|
|
90
|
+
return this.#info(parseHost(ArtifactsRepoInfo, await handle.info()));
|
|
91
|
+
});
|
|
92
|
+
} catch (error) {
|
|
93
|
+
throw toGatewayError(repo, 'createRepo', error);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
async deleteRepo(name: string): Promise<void> {
|
|
98
|
+
const repo = parseStorageInput(RepoName, name);
|
|
99
|
+
try {
|
|
100
|
+
await this.#binding.delete(repo);
|
|
101
|
+
} catch (error) {
|
|
102
|
+
if (!isRepoNotFound(error, repo)) throw toGatewayError(repo, 'deleteRepo', error);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
async repoInfo(name: string): Promise<StorageRepoInfo | null> {
|
|
107
|
+
const repo = parseStorageInput(RepoName, name);
|
|
108
|
+
try {
|
|
109
|
+
return await this.#withRepo(repo, 'repoInfo', async (handle) =>
|
|
110
|
+
this.#info(parseHost(ArtifactsRepoInfo, await handle.info())),
|
|
111
|
+
);
|
|
112
|
+
} catch (error) {
|
|
113
|
+
if (isGatewayError(error, 'repo_not_found')) return null;
|
|
114
|
+
throw error;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
async resolveRef(name: string, ref: string): Promise<string | null> {
|
|
119
|
+
const repo = parseStorageInput(RepoName, name);
|
|
120
|
+
const parsed = parseStorageInput(StorageRef, ref);
|
|
121
|
+
return this.#withRepo(repo, 'resolveRef', async (handle) => {
|
|
122
|
+
const [head] = z.array(ArtifactsCommit).parse(await handle.log({ ref: bindingRef(parsed), limit: 1 }));
|
|
123
|
+
return head?.hash ?? null;
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
async readCommit(name: string, sha: string): Promise<Commit | null> {
|
|
128
|
+
const repo = parseStorageInput(RepoName, name);
|
|
129
|
+
const id = parseStorageInput(Sha, sha);
|
|
130
|
+
return this.#withRepo(repo, 'readCommit', async (handle) => {
|
|
131
|
+
const metadata = await this.#readTyped(
|
|
132
|
+
async () => handle.readCommit(id),
|
|
133
|
+
[async () => handle.readBlob(id), async () => handle.readTree(id)],
|
|
134
|
+
);
|
|
135
|
+
return metadata === null ? null : toContractCommit(parseHost(ArtifactsCommit, metadata));
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
async readTree(name: string, sha: string): Promise<StorageTreeEntry[] | null> {
|
|
140
|
+
const repo = parseStorageInput(RepoName, name);
|
|
141
|
+
const id = parseStorageInput(Sha, sha);
|
|
142
|
+
return this.#withRepo(repo, 'readTree', async (handle) => {
|
|
143
|
+
const entries = await this.#readTyped(
|
|
144
|
+
async () => handle.readTree(id),
|
|
145
|
+
[async () => handle.readBlob(id), async () => handle.readCommit(id)],
|
|
146
|
+
);
|
|
147
|
+
return entries === null ? null : z.array(ArtifactsTreeEntry).parse(entries).map(toStorageTreeEntry);
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
async readBlob(name: string, sha: string): Promise<Uint8Array | null> {
|
|
152
|
+
const repo = parseStorageInput(RepoName, name);
|
|
153
|
+
const id = parseStorageInput(Sha, sha);
|
|
154
|
+
return this.#withRepo(repo, 'readBlob', async (handle) => {
|
|
155
|
+
try {
|
|
156
|
+
return await bytesOf(await handle.readBlob(id));
|
|
157
|
+
} catch (error) {
|
|
158
|
+
if (!isUnserializableBlob(error)) throw error;
|
|
159
|
+
return readBlobOverGit(await this.gitRemote(repo, 'read'), id);
|
|
160
|
+
}
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
async readFile(name: string, ref: string, path: string): Promise<Uint8Array | null> {
|
|
165
|
+
const repo = parseStorageInput(RepoName, name);
|
|
166
|
+
const revision = parseStorageInput(Revision, ref);
|
|
167
|
+
const file = parseStorageInput(FilePath, path);
|
|
168
|
+
// A Revision is a commit id or a short branch name, which is what the binding resolves.
|
|
169
|
+
return this.#withRepo(repo, 'readFile', async (handle) => {
|
|
170
|
+
try {
|
|
171
|
+
return await bytesOf(await handle.readFile({ ref: revision, path: file }));
|
|
172
|
+
} catch (error) {
|
|
173
|
+
if (!isUnserializableBlob(error)) throw error;
|
|
174
|
+
const blob = await blobIdAt(handle, revision, file);
|
|
175
|
+
return blob === null ? null : readBlobOverGit(await this.gitRemote(repo, 'read'), blob);
|
|
176
|
+
}
|
|
177
|
+
});
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
async log(name: string, ref: string, options: StorageLogOptions): Promise<Commit[]> {
|
|
181
|
+
const repo = parseStorageInput(RepoName, name);
|
|
182
|
+
const revision = parseStorageInput(Revision, ref);
|
|
183
|
+
const { limit, offset } = parseStorageInput(StorageLogOptions, options);
|
|
184
|
+
return this.#withRepo(repo, 'log', async (handle) => {
|
|
185
|
+
const commits = z.array(ArtifactsCommit).parse(await handle.log({ ref: revision, limit, offset }));
|
|
186
|
+
return Promise.all(commits.map(toContractCommit));
|
|
187
|
+
});
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
async gitRemote(name: string, access: string): Promise<GitRemote> {
|
|
191
|
+
const repo = parseStorageInput(RepoName, name);
|
|
192
|
+
const scope = parseStorageInput(GitAccess, access);
|
|
193
|
+
return this.#withRepo(repo, 'gitRemote', async (handle) => {
|
|
194
|
+
const [info, token] = await Promise.all([handle.info(), handle.createToken(scope, this.#ttl)]);
|
|
195
|
+
const parsedToken = parseHost(ArtifactsToken, token);
|
|
196
|
+
return GitRemote.parse({
|
|
197
|
+
url: parseHost(ArtifactsRepoInfo, info).remote,
|
|
198
|
+
headers: { Authorization: `Bearer ${parsedToken.plaintext}` },
|
|
199
|
+
expiresAt: new Date(parsedToken.expiresAt).toISOString(),
|
|
200
|
+
});
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Runs `work` with a handle on the repository, releasing it after; failures become GatewayErrors. */
|
|
205
|
+
async #withRepo<T>(
|
|
206
|
+
repo: string,
|
|
207
|
+
what: string,
|
|
208
|
+
work: (handle: ArtifactsRepoHandle) => Promise<T>,
|
|
209
|
+
): Promise<T> {
|
|
210
|
+
let handle: ArtifactsRepoHandle;
|
|
211
|
+
try {
|
|
212
|
+
handle = await this.#binding.get(repo);
|
|
213
|
+
} catch (error) {
|
|
214
|
+
throw toGatewayError(repo, what, error);
|
|
215
|
+
}
|
|
216
|
+
try {
|
|
217
|
+
return await work(handle);
|
|
218
|
+
} catch (error) {
|
|
219
|
+
throw toGatewayError(repo, what, error);
|
|
220
|
+
} finally {
|
|
221
|
+
releaseHandle(handle);
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* Reads an object of one kind. The binding answers null for a missing id but throws
|
|
227
|
+
* INTERNAL_ERROR when the id names an object of another kind; that case is null too, told apart
|
|
228
|
+
* from a real failure by the object being readable as one of the other kinds (`probes`).
|
|
229
|
+
*/
|
|
230
|
+
async #readTyped(
|
|
231
|
+
read: () => Promise<unknown>,
|
|
232
|
+
probes: readonly (() => Promise<unknown>)[],
|
|
233
|
+
): Promise<unknown> {
|
|
234
|
+
try {
|
|
235
|
+
return await read();
|
|
236
|
+
} catch (error) {
|
|
237
|
+
if (artifactsErrorCode(error) !== 'INTERNAL_ERROR') throw error;
|
|
238
|
+
for (const probe of probes) {
|
|
239
|
+
// A Blob that could not be carried back (wrangler's remote binding) was still found.
|
|
240
|
+
const found = await probe().catch((probeError: unknown) =>
|
|
241
|
+
isUnserializableBlob(probeError) ? true : null,
|
|
242
|
+
);
|
|
243
|
+
if (found !== null) return null;
|
|
244
|
+
}
|
|
245
|
+
throw error;
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
#info(info: ArtifactsRepoInfo): StorageRepoInfo {
|
|
250
|
+
return StorageRepoInfo.parse({
|
|
251
|
+
name: info.name,
|
|
252
|
+
defaultBranch: info.defaultBranch,
|
|
253
|
+
createdAt: new Date(info.createdAt).toISOString(),
|
|
254
|
+
});
|
|
255
|
+
}
|
|
256
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The part of a repository handle (`ArtifactsRepo` in @cloudflare/workers-types) the backend
|
|
5
|
+
* uses. Declared structurally so the package's types do not depend on the Workers globals; the
|
|
6
|
+
* real binding's handles satisfy it. Every result is parsed with Zod before use.
|
|
7
|
+
*/
|
|
8
|
+
export interface ArtifactsRepoHandle {
|
|
9
|
+
info(): Promise<unknown>;
|
|
10
|
+
createToken(scope?: 'write' | 'read', ttl?: number): Promise<unknown>;
|
|
11
|
+
revokeToken(tokenOrId: string): Promise<boolean>;
|
|
12
|
+
readBlob(hash: string): Promise<Blob | null>;
|
|
13
|
+
readTree(hash: string): Promise<unknown>;
|
|
14
|
+
readCommit(hash: string): Promise<unknown>;
|
|
15
|
+
readFile(args: { ref: string; path: string }): Promise<Blob | null>;
|
|
16
|
+
log(opts?: { ref?: string; limit?: number; offset?: number }): Promise<unknown>;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The part of the Artifacts binding (`Artifacts` in @cloudflare/workers-types, `env.ARTIFACTS`)
|
|
21
|
+
* the backend uses: namespace-level create, get and delete.
|
|
22
|
+
*/
|
|
23
|
+
export interface ArtifactsNamespaceBinding {
|
|
24
|
+
create(
|
|
25
|
+
name: string,
|
|
26
|
+
opts?: { readOnly?: boolean; description?: string; setDefaultBranch?: string },
|
|
27
|
+
): Promise<unknown>;
|
|
28
|
+
get(name: string): Promise<ArtifactsRepoHandle>;
|
|
29
|
+
delete(name: string): Promise<boolean>;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Releases a repository handle (an RPC stub) when the runtime gives it a disposer. */
|
|
33
|
+
export function releaseHandle(handle: ArtifactsRepoHandle): void {
|
|
34
|
+
const dispose: unknown = Reflect.get(handle, Symbol.dispose);
|
|
35
|
+
if (typeof dispose === 'function') Reflect.apply(dispose, handle, []);
|
|
36
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { isGatewayError } from '@leed-ai/git-gateway-contract/gateway-error';
|
|
3
|
+
import {
|
|
4
|
+
repoExists,
|
|
5
|
+
repoNotFound,
|
|
6
|
+
storageUnavailable,
|
|
7
|
+
} from '@leed-ai/git-gateway-contract/storage/storage-errors';
|
|
8
|
+
|
|
9
|
+
import { ArtifactsBindingError } from './schemas/artifacts-binding-results.ts';
|
|
10
|
+
|
|
11
|
+
/** The Artifacts error code of something thrown, or null when it is not an Artifacts error. */
|
|
12
|
+
export function artifactsErrorCode(thrown: unknown): string | null {
|
|
13
|
+
if (typeof thrown !== 'object' || thrown === null) return null;
|
|
14
|
+
const parsed = ArtifactsBindingError.safeParse({
|
|
15
|
+
code: Reflect.get(thrown, 'code'),
|
|
16
|
+
message: Reflect.get(thrown, 'message'),
|
|
17
|
+
});
|
|
18
|
+
return parsed.success ? parsed.data.code : null;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** The REST API's numeric code for "already exists", which the binding's ArtifactsError carries. */
|
|
22
|
+
const ALREADY_EXISTS_NUMERIC = 10201;
|
|
23
|
+
|
|
24
|
+
const escapeRegExp = (text: string): string => text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Whether a failure of `create(repo)` says the repository already exists. The binding documents
|
|
28
|
+
* code ALREADY_EXISTS (numeric 10201), and the local simulator sends it; the live binding was seen
|
|
29
|
+
* to throw an error whose code did not survive, with only the message "repo already exists:
|
|
30
|
+
* <name>". So the code, then the numeric code, then exactly that message naming this repository
|
|
31
|
+
* (optionally after an "ArtifactsError: " prefix) are accepted.
|
|
32
|
+
*/
|
|
33
|
+
export function isAlreadyExists(thrown: unknown, repo: string): boolean {
|
|
34
|
+
if (artifactsErrorCode(thrown) === 'ALREADY_EXISTS') return true;
|
|
35
|
+
if (typeof thrown !== 'object' || thrown === null) return false;
|
|
36
|
+
if (Reflect.get(thrown, 'numericCode') === ALREADY_EXISTS_NUMERIC) return true;
|
|
37
|
+
const message: unknown = Reflect.get(thrown, 'message');
|
|
38
|
+
return (
|
|
39
|
+
typeof message === 'string' &&
|
|
40
|
+
new RegExp(String.raw`^(?:ArtifactsError: )?repo already exists: ${escapeRegExp(repo)}$`, 'i').test(
|
|
41
|
+
message.trim(),
|
|
42
|
+
)
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** The REST API's numeric code for "not found", which the binding's ArtifactsError carries. */
|
|
47
|
+
const NOT_FOUND_NUMERIC = 10200;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Whether a failure of a binding call on `repo` says the repository does not exist. The binding
|
|
51
|
+
* documents code NOT_FOUND (numeric 10200), and the local simulator sends it; the live binding was
|
|
52
|
+
* seen to throw an error whose code did not survive, with only the message "Repository not found:
|
|
53
|
+
* <name>." So the code, then the numeric code, then exactly that message naming this repository
|
|
54
|
+
* (optionally after an "ArtifactsError: " prefix, with or without the closing period) are
|
|
55
|
+
* accepted.
|
|
56
|
+
*/
|
|
57
|
+
export function isRepoNotFound(thrown: unknown, repo: string): boolean {
|
|
58
|
+
if (artifactsErrorCode(thrown) === 'NOT_FOUND') return true;
|
|
59
|
+
if (typeof thrown !== 'object' || thrown === null) return false;
|
|
60
|
+
if (Reflect.get(thrown, 'numericCode') === NOT_FOUND_NUMERIC) return true;
|
|
61
|
+
const message: unknown = Reflect.get(thrown, 'message');
|
|
62
|
+
return (
|
|
63
|
+
typeof message === 'string' &&
|
|
64
|
+
new RegExp(String.raw`^(?:ArtifactsError: )?repository not found: ${escapeRegExp(repo)}\.?$`, 'i').test(
|
|
65
|
+
message.trim(),
|
|
66
|
+
)
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Translates a failure of a binding call on repository `repo` into a GatewayError: NOT_FOUND is
|
|
72
|
+
* repo_not_found (also when only the numeric code or the message says so, see
|
|
73
|
+
* {@link isRepoNotFound}), ALREADY_EXISTS is repo_exists (for createRepo also when only the numeric code or
|
|
74
|
+
* the message says so, see {@link isAlreadyExists}), everything else (in-progress states,
|
|
75
|
+
* MEMORY_LIMIT, INTERNAL_ERROR, unparsable results) is storage_unavailable. GatewayErrors pass
|
|
76
|
+
* through unchanged.
|
|
77
|
+
*/
|
|
78
|
+
export function toGatewayError(repo: string, what: string, thrown: unknown): Error {
|
|
79
|
+
if (isGatewayError(thrown) && thrown instanceof Error) return thrown;
|
|
80
|
+
const code = artifactsErrorCode(thrown);
|
|
81
|
+
if (isRepoNotFound(thrown, repo)) return repoNotFound(repo);
|
|
82
|
+
if (code === 'ALREADY_EXISTS' || (what === 'createRepo' && isAlreadyExists(thrown, repo)))
|
|
83
|
+
return repoExists(repo);
|
|
84
|
+
return storageUnavailable(`Artifacts ${what}`, thrown);
|
|
85
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import type { GitRemote } from '@leed-ai/git-gateway-contract/storage/git-remote';
|
|
3
|
+
import { isCoreError } from '@leed-ai/git-gateway-core/core-error';
|
|
4
|
+
import { GitHttpClient } from '@leed-ai/git-gateway-core/smart-http/git-http-client';
|
|
5
|
+
import { z } from 'zod';
|
|
6
|
+
|
|
7
|
+
import type { ArtifactsRepoHandle } from './artifacts-binding.ts';
|
|
8
|
+
import { ArtifactsCommit, ArtifactsTreeEntry } from './schemas/artifacts-binding-results.ts';
|
|
9
|
+
|
|
10
|
+
const SHA = /^[0-9a-f]{40}$/;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Whether a binding call failed only because its result, a Blob, could not be carried back. That
|
|
14
|
+
* is what wrangler's remote Artifacts binding (`"remote": true` under `wrangler dev`) does for
|
|
15
|
+
* readBlob and readFile: its proxy cannot serialize a Blob ("Cannot serialize value: [object
|
|
16
|
+
* Blob]"). The native binding in production returns the Blob and never takes this path.
|
|
17
|
+
*/
|
|
18
|
+
export function isUnserializableBlob(thrown: unknown): boolean {
|
|
19
|
+
if (typeof thrown !== 'object' || thrown === null) return false;
|
|
20
|
+
const message: unknown = Reflect.get(thrown, 'message');
|
|
21
|
+
return typeof message === 'string' && message.includes('Cannot serialize value: [object Blob]');
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* A blob's bytes read over the repository's git remote instead of the binding: one upload-pack
|
|
26
|
+
* request wanting just that id (a blob reaches nothing, so the pack holds that object alone),
|
|
27
|
+
* read with the core pack reader. Null when the server does not have the id (refused
|
|
28
|
+
* in-protocol, "not our ref") or it is not a blob. HTTP failures propagate.
|
|
29
|
+
*/
|
|
30
|
+
export async function readBlobOverGit(remote: GitRemote, sha: string): Promise<Uint8Array | null> {
|
|
31
|
+
try {
|
|
32
|
+
const { objects } = await new GitHttpClient(remote).fetchPack({ wants: [sha] });
|
|
33
|
+
const object = objects.find((candidate) => candidate.sha === sha);
|
|
34
|
+
return object?.type === 'blob' ? object.data : null;
|
|
35
|
+
} catch (error) {
|
|
36
|
+
if (isCoreError(error, 'remote_error')) return null;
|
|
37
|
+
throw error;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The id of the blob at `path` in `revision` (a commit id or a short branch name), found through
|
|
43
|
+
* the binding's own commit and tree reads, which carry plain data even where Blobs cannot travel.
|
|
44
|
+
* Null when the revision, a directory on the way or the file does not exist, or the path names a
|
|
45
|
+
* directory or submodule.
|
|
46
|
+
*/
|
|
47
|
+
export async function blobIdAt(
|
|
48
|
+
handle: ArtifactsRepoHandle,
|
|
49
|
+
revision: string,
|
|
50
|
+
path: string,
|
|
51
|
+
): Promise<string | null> {
|
|
52
|
+
let commitId: string | null = revision;
|
|
53
|
+
if (!SHA.test(revision)) {
|
|
54
|
+
const [head] = z.array(ArtifactsCommit).parse(await handle.log({ ref: revision, limit: 1 }));
|
|
55
|
+
commitId = head?.hash ?? null;
|
|
56
|
+
}
|
|
57
|
+
if (commitId === null) return null;
|
|
58
|
+
const commit = await handle.readCommit(commitId);
|
|
59
|
+
if (commit === null) return null;
|
|
60
|
+
let tree = ArtifactsCommit.parse(commit).treeHash;
|
|
61
|
+
const segments = path.split('/');
|
|
62
|
+
for (const [index, segment] of segments.entries()) {
|
|
63
|
+
const listed = await handle.readTree(tree);
|
|
64
|
+
if (listed === null) return null;
|
|
65
|
+
const entry = z
|
|
66
|
+
.array(ArtifactsTreeEntry)
|
|
67
|
+
.parse(listed)
|
|
68
|
+
.find((candidate) => candidate.name === segment);
|
|
69
|
+
if (entry === undefined) return null;
|
|
70
|
+
const last = index === segments.length - 1;
|
|
71
|
+
if (last) return entry.type === 'tree' || entry.type === 'gitlink' ? null : entry.hash;
|
|
72
|
+
if (entry.type !== 'tree') return null;
|
|
73
|
+
tree = entry.hash;
|
|
74
|
+
}
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { readIdempotencyTrailer } from '@leed-ai/git-gateway-contract/reference/trailer';
|
|
3
|
+
import { Commit } from '@leed-ai/git-gateway-contract/schemas/commit';
|
|
4
|
+
import { StorageTreeEntry } from '@leed-ai/git-gateway-contract/storage/storage-tree-entry';
|
|
5
|
+
import { encodeCommit } from '@leed-ai/git-gateway-core/objects/commit-object';
|
|
6
|
+
import { hashObject } from '@leed-ai/git-gateway-core/objects/hash-object';
|
|
7
|
+
|
|
8
|
+
import type { ArtifactsCommit, ArtifactsTreeEntry } from './schemas/artifacts-binding-results.ts';
|
|
9
|
+
|
|
10
|
+
const isoOf = (seconds: number): string => new Date(seconds * 1000).toISOString();
|
|
11
|
+
|
|
12
|
+
/** The contract commit for some Artifacts commit metadata, with a given full message. */
|
|
13
|
+
function commitWith(metadata: ArtifactsCommit, message: string): Commit {
|
|
14
|
+
return Commit.parse({
|
|
15
|
+
sha: metadata.hash,
|
|
16
|
+
tree: metadata.treeHash,
|
|
17
|
+
parents: metadata.parents,
|
|
18
|
+
author: { ...metadata.author, date: isoOf(metadata.authoredAt) },
|
|
19
|
+
committer: { ...metadata.committer, date: isoOf(metadata.committedAt) },
|
|
20
|
+
message,
|
|
21
|
+
idempotencyKey: readIdempotencyTrailer(message),
|
|
22
|
+
});
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Converts Artifacts commit metadata into a contract {@link Commit}. Artifacts removes one
|
|
27
|
+
* trailing newline from the message and reports dates without their time zone, so the full
|
|
28
|
+
* message is recovered by re-encoding the commit both ways (at +0000, as the gateway writes
|
|
29
|
+
* every commit) and keeping the candidate whose id matches. When neither matches (a commit made
|
|
30
|
+
* in another time zone, or with extra headers such as a signature) the message is given back
|
|
31
|
+
* with the trailing newline git itself always writes.
|
|
32
|
+
*/
|
|
33
|
+
export async function toContractCommit(metadata: ArtifactsCommit): Promise<Commit> {
|
|
34
|
+
const candidates = [`${metadata.message}\n`, metadata.message].filter((message) => message.length > 0);
|
|
35
|
+
for (const message of candidates) {
|
|
36
|
+
const commit = commitWith(metadata, message);
|
|
37
|
+
const { tree, parents, author, committer } = commit;
|
|
38
|
+
const sha = await hashObject(
|
|
39
|
+
'commit',
|
|
40
|
+
encodeCommit({ tree, parents: [...parents], author, committer, message }),
|
|
41
|
+
);
|
|
42
|
+
if (sha === metadata.hash) return commit;
|
|
43
|
+
}
|
|
44
|
+
return commitWith(metadata, `${metadata.message}\n`);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const TYPES = { tree: 'tree', gitlink: 'commit', blob: 'blob', exec: 'blob', symlink: 'blob' } as const;
|
|
48
|
+
|
|
49
|
+
/** Converts an Artifacts tree entry into a contract {@link StorageTreeEntry} (mode "40000" becomes "040000"). */
|
|
50
|
+
export function toStorageTreeEntry(entry: ArtifactsTreeEntry): StorageTreeEntry {
|
|
51
|
+
return StorageTreeEntry.parse({
|
|
52
|
+
name: entry.name,
|
|
53
|
+
type: TYPES[entry.type],
|
|
54
|
+
mode: entry.mode === '40000' ? '040000' : entry.mode,
|
|
55
|
+
sha: entry.hash,
|
|
56
|
+
});
|
|
57
|
+
}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import type { Cloudflare } from 'cloudflare';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
ArtifactsRestNamespace,
|
|
7
|
+
ArtifactsRestRepo,
|
|
8
|
+
ArtifactsRestToken,
|
|
9
|
+
cloudflareEnvelope,
|
|
10
|
+
} from './schemas/artifacts-rest-results.ts';
|
|
11
|
+
|
|
12
|
+
/** Where the REST control plane points: an account and one Artifacts namespace in it. */
|
|
13
|
+
export interface ArtifactsRestOptions {
|
|
14
|
+
/** A configured official Cloudflare SDK client (API token with Artifacts permissions). */
|
|
15
|
+
readonly client: Cloudflare;
|
|
16
|
+
readonly accountId: string;
|
|
17
|
+
readonly namespace: string;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
const NotFound = z.object({ status: z.literal(404) });
|
|
21
|
+
|
|
22
|
+
/** True when the SDK threw for a 404. */
|
|
23
|
+
function isNotFound(error: unknown): boolean {
|
|
24
|
+
return NotFound.safeParse(error).success;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The Artifacts control plane over the Cloudflare REST API, for code that runs outside a Worker
|
|
29
|
+
* (provisioning scripts, CI, the live contract leg): namespaces, repositories and tokens. Every
|
|
30
|
+
* call goes through the official `cloudflare` SDK's generic request methods (it has no typed
|
|
31
|
+
* Artifacts resource yet) and every response is parsed with Zod. Inside a Worker, use the binding
|
|
32
|
+
* and {@link ArtifactsBackend} instead.
|
|
33
|
+
*/
|
|
34
|
+
export class ArtifactsRestControl {
|
|
35
|
+
readonly #client: Cloudflare;
|
|
36
|
+
readonly #account: string;
|
|
37
|
+
readonly #namespace: string;
|
|
38
|
+
|
|
39
|
+
constructor(options: ArtifactsRestOptions) {
|
|
40
|
+
this.#client = options.client;
|
|
41
|
+
this.#account = `/accounts/${encodeURIComponent(options.accountId)}/artifacts`;
|
|
42
|
+
this.#namespace = `${this.#account}/namespaces/${encodeURIComponent(options.namespace)}`;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The namespace, or null when it does not exist. */
|
|
46
|
+
async getNamespace(): Promise<ArtifactsRestNamespace | null> {
|
|
47
|
+
try {
|
|
48
|
+
return cloudflareEnvelope(ArtifactsRestNamespace).parse(await this.#client.get(this.#namespace)).result;
|
|
49
|
+
} catch (error) {
|
|
50
|
+
if (isNotFound(error)) return null;
|
|
51
|
+
throw error;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Creates the namespace (optionally pinned to a jurisdiction). */
|
|
56
|
+
async createNamespace(name: string, jurisdiction?: 'eu' | 'us'): Promise<ArtifactsRestNamespace> {
|
|
57
|
+
const body = jurisdiction === undefined ? { namespace: name } : { namespace: name, jurisdiction };
|
|
58
|
+
return cloudflareEnvelope(ArtifactsRestNamespace).parse(
|
|
59
|
+
await this.#client.post(`${this.#account}/namespaces`, { body }),
|
|
60
|
+
).result;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Creates a repository; the initial token in the result is not returned. */
|
|
64
|
+
async createRepo(name: string, defaultBranch: string): Promise<ArtifactsRestRepo> {
|
|
65
|
+
const response = await this.#client.post(`${this.#namespace}/repos`, {
|
|
66
|
+
body: { name, default_branch: defaultBranch },
|
|
67
|
+
});
|
|
68
|
+
return cloudflareEnvelope(ArtifactsRestRepo).parse(response).result;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** A repository, or null when it does not exist. */
|
|
72
|
+
async getRepo(name: string): Promise<ArtifactsRestRepo | null> {
|
|
73
|
+
try {
|
|
74
|
+
return cloudflareEnvelope(ArtifactsRestRepo).parse(
|
|
75
|
+
await this.#client.get(`${this.#namespace}/repos/${encodeURIComponent(name)}`),
|
|
76
|
+
).result;
|
|
77
|
+
} catch (error) {
|
|
78
|
+
if (isNotFound(error)) return null;
|
|
79
|
+
throw error;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** Deletes a repository; false when there was none. */
|
|
84
|
+
async deleteRepo(name: string): Promise<boolean> {
|
|
85
|
+
try {
|
|
86
|
+
await this.#client.delete(`${this.#namespace}/repos/${encodeURIComponent(name)}`);
|
|
87
|
+
return true;
|
|
88
|
+
} catch (error) {
|
|
89
|
+
if (isNotFound(error)) return false;
|
|
90
|
+
throw error;
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Mints a repository token for git; `ttlSeconds` 60–31536000. */
|
|
95
|
+
async createToken(repo: string, scope: 'read' | 'write', ttlSeconds: number): Promise<ArtifactsRestToken> {
|
|
96
|
+
const body = { repo, scope, ttl: z.int().min(60).max(31_536_000).parse(ttlSeconds) };
|
|
97
|
+
return cloudflareEnvelope(ArtifactsRestToken).parse(
|
|
98
|
+
await this.#client.post(`${this.#namespace}/tokens`, { body }),
|
|
99
|
+
).result;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Revokes a token by id; false when there was none. */
|
|
103
|
+
async revokeToken(id: string): Promise<boolean> {
|
|
104
|
+
try {
|
|
105
|
+
await this.#client.delete(`${this.#namespace}/tokens/${encodeURIComponent(id)}`);
|
|
106
|
+
return true;
|
|
107
|
+
} catch (error) {
|
|
108
|
+
if (isNotFound(error)) return false;
|
|
109
|
+
throw error;
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|