@leed-ai/git-gateway-contract 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 +50 -2
- package/dist/behaviour/assertions.d.ts +23 -0
- package/dist/behaviour/assertions.js +56 -0
- package/dist/behaviour/assertions.js.map +1 -0
- package/dist/behaviour/behaviour-case.d.ts +19 -0
- package/dist/behaviour/behaviour-case.js +12 -0
- package/dist/behaviour/behaviour-case.js.map +1 -0
- package/dist/behaviour/behaviour-suite.d.ts +30 -0
- package/dist/behaviour/behaviour-suite.js +50 -0
- package/dist/behaviour/behaviour-suite.js.map +1 -0
- package/dist/behaviour/commit-action-cases.d.ts +4 -0
- package/dist/behaviour/commit-action-cases.js +342 -0
- package/dist/behaviour/commit-action-cases.js.map +1 -0
- package/dist/behaviour/commit-write-cases.d.ts +4 -0
- package/dist/behaviour/commit-write-cases.js +234 -0
- package/dist/behaviour/commit-write-cases.js.map +1 -0
- package/dist/behaviour/fixtures.d.ts +29 -0
- package/dist/behaviour/fixtures.js +83 -0
- package/dist/behaviour/fixtures.js.map +1 -0
- package/dist/behaviour/lifecycle-cases.d.ts +4 -0
- package/dist/behaviour/lifecycle-cases.js +158 -0
- package/dist/behaviour/lifecycle-cases.js.map +1 -0
- package/dist/behaviour/promote-cases.d.ts +4 -0
- package/dist/behaviour/promote-cases.js +122 -0
- package/dist/behaviour/promote-cases.js.map +1 -0
- package/dist/behaviour/read-cases.d.ts +4 -0
- package/dist/behaviour/read-cases.js +248 -0
- package/dist/behaviour/read-cases.js.map +1 -0
- package/dist/behaviour/sync-cases.d.ts +4 -0
- package/dist/behaviour/sync-cases.js +205 -0
- package/dist/behaviour/sync-cases.js.map +1 -0
- package/dist/clock-B3MlpmVY.d.ts +10 -0
- package/dist/commit-BEZmeAOl.d.ts +23 -0
- package/dist/file-map-CxUveLWz.d.ts +18 -0
- package/dist/gateway-config-oVsdTEeK.d.ts +39 -0
- package/dist/gateway-error-body-BWzZFAQI.d.ts +214 -0
- package/dist/gateway-error.d.ts +30 -0
- package/dist/gateway-error.js +63 -0
- package/dist/gateway-error.js.map +1 -0
- package/dist/git-gateway-VA9Tc5tn.d.ts +358 -0
- package/dist/git-gateway.d.ts +2 -0
- package/dist/git-gateway.js +65 -0
- package/dist/git-gateway.js.map +1 -0
- package/dist/health.d.ts +9 -0
- package/dist/health.js +18 -0
- package/dist/health.js.map +1 -0
- package/dist/history-CqvHaUE-.d.ts +20 -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/proxy/audit-event.d.ts +61 -0
- package/dist/proxy/audit-event.js +97 -0
- package/dist/proxy/audit-event.js.map +1 -0
- package/dist/proxy/branch-rule.d.ts +72 -0
- package/dist/proxy/branch-rule.js +106 -0
- package/dist/proxy/branch-rule.js.map +1 -0
- package/dist/proxy/gateway-hooks.d.ts +58 -0
- package/dist/proxy/gateway-hooks.js +0 -0
- package/dist/proxy/git-operation.d.ts +17 -0
- package/dist/proxy/git-operation.js +32 -0
- package/dist/proxy/git-operation.js.map +1 -0
- package/dist/proxy/policy-result.d.ts +51 -0
- package/dist/proxy/policy-result.js +90 -0
- package/dist/proxy/policy-result.js.map +1 -0
- package/dist/proxy/principal.d.ts +18 -0
- package/dist/proxy/principal.js +32 -0
- package/dist/proxy/principal.js.map +1 -0
- package/dist/proxy/push-policy-result.d.ts +34 -0
- package/dist/proxy/push-policy-result.js +48 -0
- package/dist/proxy/push-policy-result.js.map +1 -0
- package/dist/proxy/push-policy.d.ts +146 -0
- package/dist/proxy/push-policy.js +112 -0
- package/dist/proxy/push-policy.js.map +1 -0
- package/dist/proxy/request-credential.d.ts +22 -0
- package/dist/proxy/request-credential.js +46 -0
- package/dist/proxy/request-credential.js.map +1 -0
- package/dist/proxy/smart-http-config.d.ts +22 -0
- package/dist/proxy/smart-http-config.js +40 -0
- package/dist/proxy/smart-http-config.js.map +1 -0
- package/dist/reference/apply-actions.d.ts +9 -0
- package/dist/reference/apply-actions.js +84 -0
- package/dist/reference/apply-actions.js.map +1 -0
- package/dist/reference/branch-methods.d.ts +7 -0
- package/dist/reference/branch-methods.js +105 -0
- package/dist/reference/branch-methods.js.map +1 -0
- package/dist/reference/bytes.d.ts +22 -0
- package/dist/reference/bytes.js +62 -0
- package/dist/reference/bytes.js.map +1 -0
- package/dist/reference/clock.d.ts +2 -0
- package/dist/reference/clock.js +18 -0
- package/dist/reference/clock.js.map +1 -0
- package/dist/reference/commit-method.d.ts +5 -0
- package/dist/reference/commit-method.js +83 -0
- package/dist/reference/commit-method.js.map +1 -0
- package/dist/reference/file-map.d.ts +2 -0
- package/dist/reference/file-map.js +24 -0
- package/dist/reference/file-map.js.map +1 -0
- package/dist/reference/hash.d.ts +10 -0
- package/dist/reference/hash.js +25 -0
- package/dist/reference/hash.js.map +1 -0
- package/dist/reference/history.d.ts +2 -0
- package/dist/reference/history.js +65 -0
- package/dist/reference/history.js.map +1 -0
- package/dist/reference/lifecycle-methods.d.ts +9 -0
- package/dist/reference/lifecycle-methods.js +48 -0
- package/dist/reference/lifecycle-methods.js.map +1 -0
- package/dist/reference/read-methods.d.ts +13 -0
- package/dist/reference/read-methods.js +68 -0
- package/dist/reference/read-methods.js.map +1 -0
- package/dist/reference/reference-gateway.d.ts +18 -0
- package/dist/reference/reference-gateway.js +35 -0
- package/dist/reference/reference-gateway.js.map +1 -0
- package/dist/reference/repo-state.d.ts +43 -0
- package/dist/reference/repo-state.js +45 -0
- package/dist/reference/repo-state.js.map +1 -0
- package/dist/reference/run-method.d.ts +13 -0
- package/dist/reference/run-method.js +15 -0
- package/dist/reference/run-method.js.map +1 -0
- package/dist/reference/three-way-merge.d.ts +16 -0
- package/dist/reference/three-way-merge.js +45 -0
- package/dist/reference/three-way-merge.js.map +1 -0
- package/dist/reference/trailer.d.ts +7 -0
- package/dist/reference/trailer.js +16 -0
- package/dist/reference/trailer.js.map +1 -0
- package/dist/reference/tree-index.d.ts +2 -0
- package/dist/reference/tree-index.js +66 -0
- package/dist/reference/tree-index.js.map +1 -0
- package/dist/reference/write-commit.d.ts +15 -0
- package/dist/reference/write-commit.js +44 -0
- package/dist/reference/write-commit.js.map +1 -0
- package/dist/rpc/commit-exists.d.ts +16 -0
- package/dist/rpc/commit-exists.js +30 -0
- package/dist/rpc/commit-exists.js.map +1 -0
- package/dist/rpc/commit.d.ts +172 -0
- package/dist/rpc/commit.js +115 -0
- package/dist/rpc/commit.js.map +1 -0
- package/dist/rpc/list-tree.d.ts +59 -0
- package/dist/rpc/list-tree.js +54 -0
- package/dist/rpc/list-tree.js.map +1 -0
- package/dist/rpc/log.d.ts +35 -0
- package/dist/rpc/log.js +41 -0
- package/dist/rpc/log.js.map +1 -0
- package/dist/rpc/mint-read-token.d.ts +17 -0
- package/dist/rpc/mint-read-token.js +36 -0
- package/dist/rpc/mint-read-token.js.map +1 -0
- package/dist/rpc/promote.d.ts +39 -0
- package/dist/rpc/promote.js +69 -0
- package/dist/rpc/promote.js.map +1 -0
- package/dist/rpc/read-file.d.ts +44 -0
- package/dist/rpc/read-file.js +56 -0
- package/dist/rpc/read-file.js.map +1 -0
- package/dist/rpc/repo-lifecycle.d.ts +39 -0
- package/dist/rpc/repo-lifecycle.js +64 -0
- package/dist/rpc/repo-lifecycle.js.map +1 -0
- package/dist/rpc/resolve-ref.d.ts +15 -0
- package/dist/rpc/resolve-ref.js +28 -0
- package/dist/rpc/resolve-ref.js.map +1 -0
- package/dist/rpc/sync-branch.d.ts +107 -0
- package/dist/rpc/sync-branch.js +114 -0
- package/dist/rpc/sync-branch.js.map +1 -0
- package/dist/schemas/commit-action.d.ts +100 -0
- package/dist/schemas/commit-action.js +138 -0
- package/dist/schemas/commit-action.js.map +1 -0
- package/dist/schemas/commit.d.ts +2 -0
- package/dist/schemas/commit.js +24 -0
- package/dist/schemas/commit.js.map +1 -0
- package/dist/schemas/content-encoding.d.ts +24 -0
- package/dist/schemas/content-encoding.js +41 -0
- package/dist/schemas/content-encoding.js.map +1 -0
- package/dist/schemas/examples.d.ts +38 -0
- package/dist/schemas/examples.js +32 -0
- package/dist/schemas/examples.js.map +1 -0
- package/dist/schemas/gateway-config.d.ts +2 -0
- package/dist/schemas/gateway-config.js +72 -0
- package/dist/schemas/gateway-config.js.map +1 -0
- package/dist/schemas/gateway-error-body.d.ts +2 -0
- package/dist/schemas/gateway-error-body.js +188 -0
- package/dist/schemas/gateway-error-body.js.map +1 -0
- package/dist/schemas/identity.d.ts +21 -0
- package/dist/schemas/identity.js +40 -0
- package/dist/schemas/identity.js.map +1 -0
- package/dist/schemas/names.d.ts +26 -0
- package/dist/schemas/names.js +58 -0
- package/dist/schemas/names.js.map +1 -0
- package/dist/schemas/ref-update.d.ts +10 -0
- package/dist/schemas/ref-update.js +25 -0
- package/dist/schemas/ref-update.js.map +1 -0
- package/dist/schemas/sha.d.ts +8 -0
- package/dist/schemas/sha.js +14 -0
- package/dist/schemas/sha.js.map +1 -0
- package/dist/schemas/tree-entry.d.ts +2 -0
- package/dist/schemas/tree-entry.js +62 -0
- package/dist/schemas/tree-entry.js.map +1 -0
- package/dist/storage/git-remote.d.ts +17 -0
- package/dist/storage/git-remote.js +31 -0
- package/dist/storage/git-remote.js.map +1 -0
- package/dist/storage/storage-backend.d.ts +61 -0
- package/dist/storage/storage-backend.js +0 -0
- package/dist/storage/storage-errors.d.ts +12 -0
- package/dist/storage/storage-errors.js +22 -0
- package/dist/storage/storage-errors.js.map +1 -0
- package/dist/storage/storage-input.d.ts +7 -0
- package/dist/storage/storage-input.js +14 -0
- package/dist/storage/storage-input.js.map +1 -0
- package/dist/storage/storage-read.d.ts +13 -0
- package/dist/storage/storage-read.js +30 -0
- package/dist/storage/storage-read.js.map +1 -0
- package/dist/storage/storage-repo-info.d.ts +16 -0
- package/dist/storage/storage-repo-info.js +30 -0
- package/dist/storage/storage-repo-info.js.map +1 -0
- package/dist/storage/storage-tree-entry.d.ts +21 -0
- package/dist/storage/storage-tree-entry.js +17 -0
- package/dist/storage/storage-tree-entry.js.map +1 -0
- package/dist/tree-entry-BM_1gou1.d.ts +41 -0
- package/dist/tree-index-Bk721Phv.d.ts +14 -0
- package/package.json +401 -4
- package/src/behaviour/assertions.ts +75 -0
- package/src/behaviour/behaviour-case.ts +28 -0
- package/src/behaviour/behaviour-suite.ts +76 -0
- package/src/behaviour/commit-action-cases.ts +253 -0
- package/src/behaviour/commit-write-cases.ts +205 -0
- package/src/behaviour/fixtures.ts +103 -0
- package/src/behaviour/lifecycle-cases.ts +104 -0
- package/src/behaviour/promote-cases.ts +78 -0
- package/src/behaviour/read-cases.ts +176 -0
- package/src/behaviour/sync-cases.ts +156 -0
- package/src/gateway-error.ts +72 -0
- package/src/git-gateway.ts +76 -0
- package/src/health.ts +26 -0
- package/src/package-name.ts +4 -0
- package/src/proxy/audit-event.ts +135 -0
- package/src/proxy/branch-rule.ts +190 -0
- package/src/proxy/gateway-hooks.ts +67 -0
- package/src/proxy/git-operation.ts +36 -0
- package/src/proxy/policy-result.ts +127 -0
- package/src/proxy/principal.ts +81 -0
- package/src/proxy/push-policy-result.ts +86 -0
- package/src/proxy/push-policy.ts +158 -0
- package/src/proxy/request-credential.ts +47 -0
- package/src/proxy/smart-http-config.ts +158 -0
- package/src/reference/apply-actions.ts +96 -0
- package/src/reference/branch-methods.ts +105 -0
- package/src/reference/bytes.ts +66 -0
- package/src/reference/clock.ts +19 -0
- package/src/reference/commit-method.ts +97 -0
- package/src/reference/file-map.ts +35 -0
- package/src/reference/hash.ts +25 -0
- package/src/reference/history.ts +78 -0
- package/src/reference/lifecycle-methods.ts +52 -0
- package/src/reference/read-methods.ts +87 -0
- package/src/reference/reference-gateway.ts +50 -0
- package/src/reference/repo-state.ts +83 -0
- package/src/reference/run-method.ts +25 -0
- package/src/reference/three-way-merge.ts +42 -0
- package/src/reference/trailer.ts +18 -0
- package/src/reference/tree-index.ts +65 -0
- package/src/reference/write-commit.ts +44 -0
- package/src/rpc/commit-exists.ts +46 -0
- package/src/rpc/commit.ts +156 -0
- package/src/rpc/list-tree.ts +78 -0
- package/src/rpc/log.ts +51 -0
- package/src/rpc/mint-read-token.ts +59 -0
- package/src/rpc/promote.ts +72 -0
- package/src/rpc/read-file.ts +75 -0
- package/src/rpc/repo-lifecycle.ts +103 -0
- package/src/rpc/resolve-ref.ts +41 -0
- package/src/rpc/sync-branch.ts +149 -0
- package/src/schemas/commit-action.ts +157 -0
- package/src/schemas/commit.ts +43 -0
- package/src/schemas/content-encoding.ts +58 -0
- package/src/schemas/examples.ts +24 -0
- package/src/schemas/gateway-config.ts +116 -0
- package/src/schemas/gateway-error-body.ts +230 -0
- package/src/schemas/identity.ts +57 -0
- package/src/schemas/names.ts +126 -0
- package/src/schemas/ref-update.ts +38 -0
- package/src/schemas/sha.ts +20 -0
- package/src/schemas/tree-entry.ts +72 -0
- package/src/storage/git-remote.ts +58 -0
- package/src/storage/storage-backend.ts +65 -0
- package/src/storage/storage-errors.ts +24 -0
- package/src/storage/storage-input.ts +14 -0
- package/src/storage/storage-read.ts +45 -0
- package/src/storage/storage-repo-info.ts +46 -0
- package/src/storage/storage-tree-entry.ts +20 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
/** What a git remote is minted for. */
|
|
5
|
+
export const GitAccess = z.enum(['read', 'write']).meta({
|
|
6
|
+
id: 'GitAccess',
|
|
7
|
+
title: 'Git access',
|
|
8
|
+
description: 'What a git remote from StorageBackend.gitRemote() is allowed to do on the storage host.',
|
|
9
|
+
enumDescriptions: {
|
|
10
|
+
read: 'Fetch and clone only (git-upload-pack).',
|
|
11
|
+
write: 'Fetch, clone and push (git-upload-pack and git-receive-pack).',
|
|
12
|
+
},
|
|
13
|
+
examples: ['read', 'write'],
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
/** A git access level, inferred from {@link GitAccess}. */
|
|
17
|
+
export type GitAccess = z.infer<typeof GitAccess>;
|
|
18
|
+
|
|
19
|
+
/** Where and how to reach a repository over git smart HTTP on the storage host. */
|
|
20
|
+
export const GitRemote = z
|
|
21
|
+
.object({
|
|
22
|
+
url: z
|
|
23
|
+
.url({ protocol: /^https?$/ })
|
|
24
|
+
.describe(
|
|
25
|
+
'The repository\'s smart-HTTP base URL on the storage host, ending in ".git"; append "/info/refs?service=…", "/git-upload-pack" or "/git-receive-pack". Never holds a credential.',
|
|
26
|
+
),
|
|
27
|
+
headers: z
|
|
28
|
+
.record(
|
|
29
|
+
z.string().min(1).describe('HTTP header name, e.g. "Authorization".'),
|
|
30
|
+
z.string().describe('HTTP header value. Secret when it carries a credential.'),
|
|
31
|
+
)
|
|
32
|
+
.describe(
|
|
33
|
+
'HTTP headers every request to the remote must carry, typically the short-lived credential as "Authorization". Secret: never log it or hand it to a git client.',
|
|
34
|
+
),
|
|
35
|
+
expiresAt: z.iso
|
|
36
|
+
.datetime()
|
|
37
|
+
.nullable()
|
|
38
|
+
.describe(
|
|
39
|
+
'When the credential in `headers` stops working, as an ISO 8601 UTC timestamp; null when the host does not say (for example a long-lived access token).',
|
|
40
|
+
),
|
|
41
|
+
})
|
|
42
|
+
.strict()
|
|
43
|
+
.meta({
|
|
44
|
+
id: 'GitRemote',
|
|
45
|
+
title: 'Git remote',
|
|
46
|
+
description:
|
|
47
|
+
'A storage-host git remote minted for one use: the smart-HTTP URL plus the headers that authorize it. The gateway proxies to it; the credential never reaches a git client.',
|
|
48
|
+
examples: [
|
|
49
|
+
{
|
|
50
|
+
url: 'https://artifacts.example.com/git/default/acme-raw-content.git',
|
|
51
|
+
headers: { Authorization: 'Bearer art_v2_example' },
|
|
52
|
+
expiresAt: '2026-11-20T09:35:00.000Z',
|
|
53
|
+
},
|
|
54
|
+
],
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
/** A storage-host git remote, inferred from {@link GitRemote}. */
|
|
58
|
+
export type GitRemote = z.infer<typeof GitRemote>;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import type { Commit } from '../schemas/commit.ts';
|
|
3
|
+
import type { FilePath, RepoName, Revision } from '../schemas/names.ts';
|
|
4
|
+
import type { Sha } from '../schemas/sha.ts';
|
|
5
|
+
import type { GitAccess, GitRemote } from './git-remote.ts';
|
|
6
|
+
import type { StorageLogOptions, StorageRef } from './storage-read.ts';
|
|
7
|
+
import type { CreateStorageRepoOptions, StorageRepoInfo } from './storage-repo-info.ts';
|
|
8
|
+
import type { StorageTreeEntry } from './storage-tree-entry.ts';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Where repositories are stored: Cloudflare Artifacts, GitLab, an in-memory test double. A
|
|
12
|
+
* backend provides only what every git host provides — repository lifecycle, reads by id and by
|
|
13
|
+
* ref, and a git smart-HTTP remote. Every write is a git-receive-pack push to that remote; a
|
|
14
|
+
* backend never needs a commits or refs API.
|
|
15
|
+
*
|
|
16
|
+
* Conventions every implementation follows (the backend contract suite in
|
|
17
|
+
* `@leed-ai/git-gateway-testkit` pins them):
|
|
18
|
+
*
|
|
19
|
+
* - Inputs are validated with the contract schemas; a bad value throws an `invalid_input`
|
|
20
|
+
* GatewayError before the host is called.
|
|
21
|
+
* - Every call on a repository that does not exist throws `repo_not_found`, except
|
|
22
|
+
* {@link repoInfo} (null) and {@link deleteRepo} (no-op).
|
|
23
|
+
* - A missing object, ref or path is `null` (an empty array for {@link log}), never an error.
|
|
24
|
+
* - A host failure throws `storage_unavailable`. Everything the host returns is parsed with Zod
|
|
25
|
+
* before it is handed back.
|
|
26
|
+
*/
|
|
27
|
+
export interface StorageBackend {
|
|
28
|
+
/** Creates an empty repository. Throws `repo_exists` when the name is taken. */
|
|
29
|
+
createRepo(name: RepoName, options?: CreateStorageRepoOptions): Promise<StorageRepoInfo>;
|
|
30
|
+
/** Deletes a repository with all its refs and objects; deleting a missing one does nothing. */
|
|
31
|
+
deleteRepo(name: RepoName): Promise<void>;
|
|
32
|
+
/** The repository's description, or null when it does not exist. */
|
|
33
|
+
repoInfo(name: RepoName): Promise<StorageRepoInfo | null>;
|
|
34
|
+
|
|
35
|
+
/** The commit a ref names, or null when the ref does not exist (always null in an empty repository). */
|
|
36
|
+
resolveRef(repo: RepoName, ref: StorageRef): Promise<Sha | null>;
|
|
37
|
+
/** A commit by id, or null when no commit has that id. */
|
|
38
|
+
readCommit(repo: RepoName, sha: Sha): Promise<Commit | null>;
|
|
39
|
+
/** One level of a tree by id, in stored order, or null when no tree has that id. */
|
|
40
|
+
readTree(repo: RepoName, sha: Sha): Promise<StorageTreeEntry[] | null>;
|
|
41
|
+
/** A blob's bytes by id, or null when no blob has that id. */
|
|
42
|
+
readBlob(repo: RepoName, sha: Sha): Promise<Uint8Array | null>;
|
|
43
|
+
/** A file's bytes at a revision, or null when the revision or the file does not exist. */
|
|
44
|
+
readFile(repo: RepoName, ref: Revision, path: FilePath): Promise<Uint8Array | null>;
|
|
45
|
+
/** The first-parent chain from a revision, newest first; empty when the revision does not exist. */
|
|
46
|
+
log(repo: RepoName, ref: Revision, options: StorageLogOptions): Promise<Commit[]>;
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Optional capability: whether `ancestor` is `descendant` itself or one of its ancestors, as
|
|
50
|
+
* `git merge-base --is-ancestor` answers it, or null when either commit is not in the
|
|
51
|
+
* repository. A backend implements it only when its host can answer in one or a few calls (a
|
|
52
|
+
* merge-base API, say); the gateway then proves fast-forwards with it instead of walking
|
|
53
|
+
* history one {@link readCommit} at a time, and falls back to that walk when it is absent.
|
|
54
|
+
* Follows the same conventions as the reads: invalid ids are `invalid_input`, a missing
|
|
55
|
+
* repository `repo_not_found`, a host failure `storage_unavailable`.
|
|
56
|
+
*/
|
|
57
|
+
isAncestor?(repo: RepoName, ancestor: Sha, descendant: Sha): Promise<boolean | null>;
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* A freshly minted smart-HTTP remote for the repository: URL plus the headers that authorize
|
|
61
|
+
* `access`. The credential is short-lived where the host allows it and must never reach a
|
|
62
|
+
* git client.
|
|
63
|
+
*/
|
|
64
|
+
gitRemote(repo: RepoName, access: GitAccess): Promise<GitRemote>;
|
|
65
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { gatewayError, type GatewayError } from '../gateway-error.ts';
|
|
3
|
+
|
|
4
|
+
/** The repo_not_found error a backend throws for a call on a missing repository. */
|
|
5
|
+
export function repoNotFound(repo: string): GatewayError {
|
|
6
|
+
return gatewayError('repo_not_found', `Repository not found: ${repo}`, { repo });
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/** The repo_exists error a backend throws when createRepo names a taken repository. */
|
|
10
|
+
export function repoExists(repo: string): GatewayError {
|
|
11
|
+
return gatewayError('repo_exists', `Repository already exists: ${repo}`, { repo });
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* The storage_unavailable error a backend throws when its host fails or answers with something
|
|
16
|
+
* the contract cannot represent. `cause` is summarised in the message; callers pass host errors,
|
|
17
|
+
* never credentials.
|
|
18
|
+
*/
|
|
19
|
+
export function storageUnavailable(what: string, cause: unknown): GatewayError {
|
|
20
|
+
const reason = cause instanceof Error ? cause.message : String(cause);
|
|
21
|
+
return gatewayError('storage_unavailable', `Storage backend failed: ${what}: ${reason}`, {
|
|
22
|
+
retryable: true,
|
|
23
|
+
});
|
|
24
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import type { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { invalidInput } from '../gateway-error.ts';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Parses one argument of a {@link StorageBackend} call with its contract schema, throwing an
|
|
8
|
+
* invalid_input GatewayError (never a ZodError) when it does not match.
|
|
9
|
+
*/
|
|
10
|
+
export function parseStorageInput<S extends z.ZodType>(schema: S, value: unknown): z.output<S> {
|
|
11
|
+
const parsed = schema.safeParse(value);
|
|
12
|
+
if (!parsed.success) throw invalidInput(parsed.error);
|
|
13
|
+
return parsed.data;
|
|
14
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { BranchName, FullRefName } from '../schemas/names.ts';
|
|
5
|
+
|
|
6
|
+
/** A ref a storage backend resolves. */
|
|
7
|
+
export const StorageRef = z
|
|
8
|
+
.union([
|
|
9
|
+
FullRefName.describe(
|
|
10
|
+
'A fully qualified ref, "refs/heads/<branch>" or "refs/tags/<tag>", resolved exactly.',
|
|
11
|
+
),
|
|
12
|
+
BranchName.describe('A short branch name, resolved as "refs/heads/<name>".'),
|
|
13
|
+
])
|
|
14
|
+
.meta({
|
|
15
|
+
id: 'StorageRef',
|
|
16
|
+
title: 'Storage ref',
|
|
17
|
+
description:
|
|
18
|
+
'A ref StorageBackend.resolveRef() resolves: a fully qualified "refs/heads/…" or "refs/tags/…" ref, or a short branch name meaning "refs/heads/<name>".',
|
|
19
|
+
examples: ['main', 'refs/heads/staging', 'refs/tags/v1.0.0'],
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
/** A ref a backend resolves, inferred from {@link StorageRef}. */
|
|
23
|
+
export type StorageRef = z.infer<typeof StorageRef>;
|
|
24
|
+
|
|
25
|
+
/** Paging of `StorageBackend.log`. */
|
|
26
|
+
export const StorageLogOptions = z
|
|
27
|
+
.object({
|
|
28
|
+
limit: z
|
|
29
|
+
.int()
|
|
30
|
+
.min(1)
|
|
31
|
+
.max(1000)
|
|
32
|
+
.describe('Most commits returned: 1–1000. Fewer come back when the history is shorter.'),
|
|
33
|
+
offset: z.int().min(0).default(0).describe('Commits skipped from the newest before listing. Default 0.'),
|
|
34
|
+
})
|
|
35
|
+
.strict()
|
|
36
|
+
.meta({
|
|
37
|
+
id: 'StorageLogOptions',
|
|
38
|
+
title: 'Storage log options',
|
|
39
|
+
description:
|
|
40
|
+
'Paging of StorageBackend.log(), which lists the first-parent chain from a revision, newest first: skip `offset` commits, then return up to `limit`.',
|
|
41
|
+
examples: [{ limit: 50, offset: 0 }],
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
/** Paging of `log` as accepted (defaults optional). */
|
|
45
|
+
export type StorageLogOptions = z.input<typeof StorageLogOptions>;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { EXAMPLE_TIMESTAMP } from '../schemas/examples.ts';
|
|
5
|
+
import { Timestamp } from '../schemas/identity.ts';
|
|
6
|
+
import { BranchName, RepoName } from '../schemas/names.ts';
|
|
7
|
+
|
|
8
|
+
/** Options of `StorageBackend.createRepo`. */
|
|
9
|
+
export const CreateStorageRepoOptions = z
|
|
10
|
+
.object({
|
|
11
|
+
defaultBranch: BranchName.default('main').describe(
|
|
12
|
+
'Branch the new repository\'s HEAD names. It holds no commits until the first push to it. Default "main".',
|
|
13
|
+
),
|
|
14
|
+
})
|
|
15
|
+
.strict()
|
|
16
|
+
.meta({
|
|
17
|
+
id: 'CreateStorageRepoOptions',
|
|
18
|
+
title: 'Storage createRepo options',
|
|
19
|
+
description:
|
|
20
|
+
'Options of StorageBackend.createRepo(): how the empty repository is set up on the storage host.',
|
|
21
|
+
examples: [{ defaultBranch: 'main' }],
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
/** Options of `StorageBackend.createRepo` as accepted (defaults optional). */
|
|
25
|
+
export type CreateStorageRepoOptions = z.input<typeof CreateStorageRepoOptions>;
|
|
26
|
+
|
|
27
|
+
/** A repository as the storage host describes it. */
|
|
28
|
+
export const StorageRepoInfo = z
|
|
29
|
+
.object({
|
|
30
|
+
name: RepoName.describe('The repository name, the same name the gateway serves it under.'),
|
|
31
|
+
defaultBranch: BranchName.describe("The branch the repository's HEAD names on the storage host."),
|
|
32
|
+
createdAt: Timestamp.nullable().describe(
|
|
33
|
+
'When the storage host created the repository, as an ISO 8601 UTC timestamp; null when the host does not report it.',
|
|
34
|
+
),
|
|
35
|
+
})
|
|
36
|
+
.strict()
|
|
37
|
+
.meta({
|
|
38
|
+
id: 'StorageRepoInfo',
|
|
39
|
+
title: 'Storage repository',
|
|
40
|
+
description:
|
|
41
|
+
'A repository as a StorageBackend reports it: name, default branch and creation time. Carries no host URL or credential; those come only from gitRemote().',
|
|
42
|
+
examples: [{ name: 'acme-raw-content', defaultBranch: 'main', createdAt: EXAMPLE_TIMESTAMP }],
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
/** A repository on the storage host, inferred from {@link StorageRepoInfo}. */
|
|
46
|
+
export type StorageRepoInfo = z.infer<typeof StorageRepoInfo>;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import type { z } from 'zod';
|
|
3
|
+
|
|
4
|
+
import { TreeEntry } from '../schemas/tree-entry.ts';
|
|
5
|
+
|
|
6
|
+
/** One entry of a tree object read by id. */
|
|
7
|
+
export const StorageTreeEntry = TreeEntry.omit({ path: true })
|
|
8
|
+
.strict()
|
|
9
|
+
.meta({
|
|
10
|
+
id: 'StorageTreeEntry',
|
|
11
|
+
title: 'Storage tree entry',
|
|
12
|
+
description:
|
|
13
|
+
'One entry of a git tree object read by its id through StorageBackend.readTree(): the name within that tree, the kind of object, its mode and its id. A contract TreeEntry without the path, which a tree read by id cannot know. Entries come back in the order git stores them.',
|
|
14
|
+
examples: [
|
|
15
|
+
{ name: 'about.md', type: 'blob', mode: '100644', sha: 'e69de29bb2d1d6434b8b29ae775ad8c2e48c5391' },
|
|
16
|
+
],
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
/** A tree entry read by tree id, inferred from {@link StorageTreeEntry}. */
|
|
20
|
+
export type StorageTreeEntry = z.infer<typeof StorageTreeEntry>;
|