@leed-ai/git-gateway-worker 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.
Files changed (269) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +49 -2
  3. package/dist/audit/audit-recorder.d.ts +2 -0
  4. package/dist/audit/audit-recorder.js +53 -0
  5. package/dist/audit/audit-recorder.js.map +1 -0
  6. package/dist/audit/push-report.d.ts +13 -0
  7. package/dist/audit/push-report.js +66 -0
  8. package/dist/audit/push-report.js.map +1 -0
  9. package/dist/audit-recorder-K1Ns3tfC.d.ts +31 -0
  10. package/dist/auth/authenticate.d.ts +14 -0
  11. package/dist/auth/authenticate.js +59 -0
  12. package/dist/auth/authenticate.js.map +1 -0
  13. package/dist/auth/authorize.d.ts +12 -0
  14. package/dist/auth/authorize.js +57 -0
  15. package/dist/auth/authorize.js.map +1 -0
  16. package/dist/auth/read-token-auth.d.ts +60 -0
  17. package/dist/auth/read-token-auth.js +83 -0
  18. package/dist/auth/read-token-auth.js.map +1 -0
  19. package/dist/cache/decision-cache.d.ts +2 -0
  20. package/dist/cache/decision-cache.js +45 -0
  21. package/dist/cache/decision-cache.js.map +1 -0
  22. package/dist/commit-workflow-schemas-BWlg7bZR.d.ts +95 -0
  23. package/dist/decision-cache-87U32iSj.d.ts +24 -0
  24. package/dist/gateway-app.d.ts +69 -0
  25. package/dist/gateway-app.js +80 -0
  26. package/dist/gateway-app.js.map +1 -0
  27. package/dist/gateway-context-Boh9I0mk.d.ts +54 -0
  28. package/dist/gateway-env-DnsBU4Pq.d.ts +40 -0
  29. package/dist/gateway-worker.d.ts +13 -0
  30. package/dist/gateway-worker.js +22 -0
  31. package/dist/gateway-worker.js.map +1 -0
  32. package/dist/git-route-Spxi09Rm.d.ts +22 -0
  33. package/dist/health.d.ts +6 -0
  34. package/dist/health.js +16 -0
  35. package/dist/health.js.map +1 -0
  36. package/dist/logger-BZ1zyKLb.d.ts +27 -0
  37. package/dist/logging/logger.d.ts +2 -0
  38. package/dist/logging/logger.js +15 -0
  39. package/dist/logging/logger.js.map +1 -0
  40. package/dist/on-push-DTREOB__.d.ts +62 -0
  41. package/dist/policy/branch-policy.d.ts +24 -0
  42. package/dist/policy/branch-policy.js +125 -0
  43. package/dist/policy/branch-policy.js.map +1 -0
  44. package/dist/policy/enforce-branch-policy.d.ts +30 -0
  45. package/dist/policy/enforce-branch-policy.js +214 -0
  46. package/dist/policy/enforce-branch-policy.js.map +1 -0
  47. package/dist/policy/fast-forward.d.ts +32 -0
  48. package/dist/policy/fast-forward.js +95 -0
  49. package/dist/policy/fast-forward.js.map +1 -0
  50. package/dist/policy/ref-pattern.d.ts +7 -0
  51. package/dist/policy/ref-pattern.js +25 -0
  52. package/dist/policy/ref-pattern.js.map +1 -0
  53. package/dist/policy/rule-branch-policy.d.ts +17 -0
  54. package/dist/policy/rule-branch-policy.js +69 -0
  55. package/dist/policy/rule-branch-policy.js.map +1 -0
  56. package/dist/proxy/defer.d.ts +8 -0
  57. package/dist/proxy/defer.js +15 -0
  58. package/dist/proxy/defer.js.map +1 -0
  59. package/dist/proxy/forward-read.d.ts +11 -0
  60. package/dist/proxy/forward-read.js +53 -0
  61. package/dist/proxy/forward-read.js.map +1 -0
  62. package/dist/proxy/gateway-deps.d.ts +39 -0
  63. package/dist/proxy/gateway-deps.js +0 -0
  64. package/dist/proxy/gateway-env.d.ts +2 -0
  65. package/dist/proxy/gateway-env.js +0 -0
  66. package/dist/proxy/git-responses.d.ts +25 -0
  67. package/dist/proxy/git-responses.js +83 -0
  68. package/dist/proxy/git-responses.js.map +1 -0
  69. package/dist/proxy/git-route.d.ts +2 -0
  70. package/dist/proxy/git-route.js +34 -0
  71. package/dist/proxy/git-route.js.map +1 -0
  72. package/dist/proxy/push-events.d.ts +28 -0
  73. package/dist/proxy/push-events.js +65 -0
  74. package/dist/proxy/push-events.js.map +1 -0
  75. package/dist/proxy/push-guard.d.ts +43 -0
  76. package/dist/proxy/push-guard.js +81 -0
  77. package/dist/proxy/push-guard.js.map +1 -0
  78. package/dist/proxy/push-options.d.ts +16 -0
  79. package/dist/proxy/push-options.js +33 -0
  80. package/dist/proxy/push-options.js.map +1 -0
  81. package/dist/proxy/receive-pack.d.ts +17 -0
  82. package/dist/proxy/receive-pack.js +244 -0
  83. package/dist/proxy/receive-pack.js.map +1 -0
  84. package/dist/proxy/request-log.d.ts +13 -0
  85. package/dist/proxy/request-log.js +41 -0
  86. package/dist/proxy/request-log.js.map +1 -0
  87. package/dist/proxy/resolve-route.d.ts +9 -0
  88. package/dist/proxy/resolve-route.js +22 -0
  89. package/dist/proxy/resolve-route.js.map +1 -0
  90. package/dist/proxy/upstream-call.d.ts +23 -0
  91. package/dist/proxy/upstream-call.js +63 -0
  92. package/dist/proxy/upstream-call.js.map +1 -0
  93. package/dist/proxy/upstream.d.ts +2 -0
  94. package/dist/proxy/upstream.js +68 -0
  95. package/dist/proxy/upstream.js.map +1 -0
  96. package/dist/push-event-f-5TsFUY.d.ts +15 -0
  97. package/dist/push-policy/changed-paths.d.ts +26 -0
  98. package/dist/push-policy/changed-paths.js +117 -0
  99. package/dist/push-policy/changed-paths.js.map +1 -0
  100. package/dist/push-policy/pushed-objects.d.ts +30 -0
  101. package/dist/push-policy/pushed-objects.js +76 -0
  102. package/dist/push-policy/pushed-objects.js.map +1 -0
  103. package/dist/push-policy/run-push-policy.d.ts +35 -0
  104. package/dist/push-policy/run-push-policy.js +77 -0
  105. package/dist/push-policy/run-push-policy.js.map +1 -0
  106. package/dist/push-policy/tree-diff.d.ts +21 -0
  107. package/dist/push-policy/tree-diff.js +78 -0
  108. package/dist/push-policy/tree-diff.js.map +1 -0
  109. package/dist/push-policy/uncheckable.d.ts +14 -0
  110. package/dist/push-policy/uncheckable.js +25 -0
  111. package/dist/push-policy/uncheckable.js.map +1 -0
  112. package/dist/rpc/branch-methods.d.ts +16 -0
  113. package/dist/rpc/branch-methods.js +43 -0
  114. package/dist/rpc/branch-methods.js.map +1 -0
  115. package/dist/rpc/commit-attempt.d.ts +27 -0
  116. package/dist/rpc/commit-attempt.js +85 -0
  117. package/dist/rpc/commit-attempt.js.map +1 -0
  118. package/dist/rpc/commit-graph.d.ts +20 -0
  119. package/dist/rpc/commit-graph.js +38 -0
  120. package/dist/rpc/commit-graph.js.map +1 -0
  121. package/dist/rpc/commit-method.d.ts +13 -0
  122. package/dist/rpc/commit-method.js +30 -0
  123. package/dist/rpc/commit-method.js.map +1 -0
  124. package/dist/rpc/commit-source.d.ts +12 -0
  125. package/dist/rpc/commit-source.js +9 -0
  126. package/dist/rpc/commit-source.js.map +1 -0
  127. package/dist/rpc/gateway-context.d.ts +2 -0
  128. package/dist/rpc/gateway-context.js +30 -0
  129. package/dist/rpc/gateway-context.js.map +1 -0
  130. package/dist/rpc/gateway-rpc.d.ts +10 -0
  131. package/dist/rpc/gateway-rpc.js +48 -0
  132. package/dist/rpc/gateway-rpc.js.map +1 -0
  133. package/dist/rpc/gateway-service.d.ts +24 -0
  134. package/dist/rpc/gateway-service.js +63 -0
  135. package/dist/rpc/gateway-service.js.map +1 -0
  136. package/dist/rpc/history-page.d.ts +35 -0
  137. package/dist/rpc/history-page.js +122 -0
  138. package/dist/rpc/history-page.js.map +1 -0
  139. package/dist/rpc/lifecycle-methods.d.ts +12 -0
  140. package/dist/rpc/lifecycle-methods.js +39 -0
  141. package/dist/rpc/lifecycle-methods.js.map +1 -0
  142. package/dist/rpc/paint-down.d.ts +17 -0
  143. package/dist/rpc/paint-down.js +96 -0
  144. package/dist/rpc/paint-down.js.map +1 -0
  145. package/dist/rpc/promote-attempt.d.ts +21 -0
  146. package/dist/rpc/promote-attempt.js +55 -0
  147. package/dist/rpc/promote-attempt.js.map +1 -0
  148. package/dist/rpc/push-ref.d.ts +21 -0
  149. package/dist/rpc/push-ref.js +47 -0
  150. package/dist/rpc/push-ref.js.map +1 -0
  151. package/dist/rpc/read-methods.d.ts +17 -0
  152. package/dist/rpc/read-methods.js +94 -0
  153. package/dist/rpc/read-methods.js.map +1 -0
  154. package/dist/rpc/read-token.d.ts +39 -0
  155. package/dist/rpc/read-token.js +107 -0
  156. package/dist/rpc/read-token.js.map +1 -0
  157. package/dist/rpc/repo-access.d.ts +36 -0
  158. package/dist/rpc/repo-access.js +75 -0
  159. package/dist/rpc/repo-access.js.map +1 -0
  160. package/dist/rpc/sync-attempt.d.ts +23 -0
  161. package/dist/rpc/sync-attempt.js +105 -0
  162. package/dist/rpc/sync-attempt.js.map +1 -0
  163. package/dist/sync-workflow-schemas-DCNmNE5-.d.ts +57 -0
  164. package/dist/upstream-DvqMCj5N.d.ts +15 -0
  165. package/dist/workflow-starter-BqhwX6oA.d.ts +45 -0
  166. package/dist/workflows/commit-workflow-schemas.d.ts +2 -0
  167. package/dist/workflows/commit-workflow-schemas.js +84 -0
  168. package/dist/workflows/commit-workflow-schemas.js.map +1 -0
  169. package/dist/workflows/commit-workflow.d.ts +16 -0
  170. package/dist/workflows/commit-workflow.js +22 -0
  171. package/dist/workflows/commit-workflow.js.map +1 -0
  172. package/dist/workflows/on-push.d.ts +2 -0
  173. package/dist/workflows/on-push.js +90 -0
  174. package/dist/workflows/on-push.js.map +1 -0
  175. package/dist/workflows/push-event.d.ts +2 -0
  176. package/dist/workflows/push-event.js +28 -0
  177. package/dist/workflows/push-event.js.map +1 -0
  178. package/dist/workflows/run-commit-workflow.d.ts +15 -0
  179. package/dist/workflows/run-commit-workflow.js +49 -0
  180. package/dist/workflows/run-commit-workflow.js.map +1 -0
  181. package/dist/workflows/run-sync-workflow.d.ts +14 -0
  182. package/dist/workflows/run-sync-workflow.js +67 -0
  183. package/dist/workflows/run-sync-workflow.js.map +1 -0
  184. package/dist/workflows/step-errors.d.ts +15 -0
  185. package/dist/workflows/step-errors.js +24 -0
  186. package/dist/workflows/step-errors.js.map +1 -0
  187. package/dist/workflows/step-runner.d.ts +31 -0
  188. package/dist/workflows/step-runner.js +6 -0
  189. package/dist/workflows/step-runner.js.map +1 -0
  190. package/dist/workflows/sync-branch-workflow.d.ts +15 -0
  191. package/dist/workflows/sync-branch-workflow.js +21 -0
  192. package/dist/workflows/sync-branch-workflow.js.map +1 -0
  193. package/dist/workflows/sync-workflow-schemas.d.ts +2 -0
  194. package/dist/workflows/sync-workflow-schemas.js +104 -0
  195. package/dist/workflows/sync-workflow-schemas.js.map +1 -0
  196. package/dist/workflows/workflow-instance-id.d.ts +12 -0
  197. package/dist/workflows/workflow-instance-id.js +33 -0
  198. package/dist/workflows/workflow-instance-id.js.map +1 -0
  199. package/dist/workflows/workflow-runtime.d.ts +7 -0
  200. package/dist/workflows/workflow-runtime.js +11 -0
  201. package/dist/workflows/workflow-runtime.js.map +1 -0
  202. package/dist/workflows/workflow-starter.d.ts +2 -0
  203. package/dist/workflows/workflow-starter.js +40 -0
  204. package/dist/workflows/workflow-starter.js.map +1 -0
  205. package/package.json +381 -4
  206. package/src/audit/audit-recorder.ts +74 -0
  207. package/src/audit/push-report.ts +60 -0
  208. package/src/auth/authenticate.ts +68 -0
  209. package/src/auth/authorize.ts +57 -0
  210. package/src/auth/read-token-auth.ts +119 -0
  211. package/src/cache/decision-cache.ts +57 -0
  212. package/src/gateway-app.ts +147 -0
  213. package/src/gateway-worker.ts +32 -0
  214. package/src/health.ts +12 -0
  215. package/src/logging/logger.ts +40 -0
  216. package/src/policy/branch-policy.ts +119 -0
  217. package/src/policy/enforce-branch-policy.ts +213 -0
  218. package/src/policy/fast-forward.ts +136 -0
  219. package/src/policy/ref-pattern.ts +24 -0
  220. package/src/policy/rule-branch-policy.ts +76 -0
  221. package/src/proxy/defer.ts +18 -0
  222. package/src/proxy/forward-read.ts +52 -0
  223. package/src/proxy/gateway-deps.ts +43 -0
  224. package/src/proxy/gateway-env.ts +43 -0
  225. package/src/proxy/git-responses.ts +89 -0
  226. package/src/proxy/git-route.ts +49 -0
  227. package/src/proxy/push-events.ts +91 -0
  228. package/src/proxy/push-guard.ts +109 -0
  229. package/src/proxy/push-options.ts +38 -0
  230. package/src/proxy/receive-pack.ts +257 -0
  231. package/src/proxy/request-log.ts +44 -0
  232. package/src/proxy/resolve-route.ts +24 -0
  233. package/src/proxy/upstream-call.ts +71 -0
  234. package/src/proxy/upstream.ts +76 -0
  235. package/src/push-policy/changed-paths.ts +143 -0
  236. package/src/push-policy/pushed-objects.ts +88 -0
  237. package/src/push-policy/run-push-policy.ts +99 -0
  238. package/src/push-policy/tree-diff.ts +107 -0
  239. package/src/push-policy/uncheckable.ts +27 -0
  240. package/src/rpc/branch-methods.ts +57 -0
  241. package/src/rpc/commit-attempt.ts +87 -0
  242. package/src/rpc/commit-graph.ts +44 -0
  243. package/src/rpc/commit-method.ts +36 -0
  244. package/src/rpc/commit-source.ts +15 -0
  245. package/src/rpc/gateway-context.ts +77 -0
  246. package/src/rpc/gateway-rpc.ts +65 -0
  247. package/src/rpc/gateway-service.ts +85 -0
  248. package/src/rpc/history-page.ts +163 -0
  249. package/src/rpc/lifecycle-methods.ts +50 -0
  250. package/src/rpc/paint-down.ts +120 -0
  251. package/src/rpc/promote-attempt.ts +52 -0
  252. package/src/rpc/push-ref.ts +54 -0
  253. package/src/rpc/read-methods.ts +111 -0
  254. package/src/rpc/read-token.ts +135 -0
  255. package/src/rpc/repo-access.ts +112 -0
  256. package/src/rpc/sync-attempt.ts +84 -0
  257. package/src/workflows/commit-workflow-schemas.ts +95 -0
  258. package/src/workflows/commit-workflow.ts +39 -0
  259. package/src/workflows/on-push.ts +128 -0
  260. package/src/workflows/push-event.ts +41 -0
  261. package/src/workflows/run-commit-workflow.ts +45 -0
  262. package/src/workflows/run-sync-workflow.ts +52 -0
  263. package/src/workflows/step-errors.ts +26 -0
  264. package/src/workflows/step-runner.ts +36 -0
  265. package/src/workflows/sync-branch-workflow.ts +40 -0
  266. package/src/workflows/sync-workflow-schemas.ts +122 -0
  267. package/src/workflows/workflow-instance-id.ts +26 -0
  268. package/src/workflows/workflow-runtime.ts +13 -0
  269. package/src/workflows/workflow-starter.ts +69 -0
@@ -0,0 +1,89 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { concatBytes } from '@leed-ai/git-gateway-core/bytes';
3
+ import { encodePktLine, FLUSH_PKT } from '@leed-ai/git-gateway-core/pkt-line/encode';
4
+ import {
5
+ encodeErrPacket,
6
+ encodeReportStatus,
7
+ reportStatusFraming,
8
+ } from '@leed-ai/git-gateway-core/receive-pack/report-status';
9
+ import {
10
+ BAND_PROGRESS,
11
+ encodeSideBand,
12
+ SIDE_BAND_64K_MAX_PAYLOAD,
13
+ SIDE_BAND_MAX_PAYLOAD,
14
+ } from '@leed-ai/git-gateway-core/receive-pack/side-band';
15
+
16
+ import type { GitServiceName } from './git-route.ts';
17
+
18
+ /** Headers git smart-HTTP responses carry so no proxy or browser caches them. */
19
+ export const NO_CACHE: Readonly<Record<string, string>> = {
20
+ 'Cache-Control': 'no-cache, max-age=0, must-revalidate',
21
+ Expires: 'Fri, 01 Jan 1980 00:00:00 GMT',
22
+ Pragma: 'no-cache',
23
+ };
24
+
25
+ /** A plain-text response (for errors outside the git protocol). */
26
+ export function textResponse(status: number, body: string, headers: Record<string, string> = {}): Response {
27
+ return new Response(body.endsWith('\n') ? body : `${body}\n`, {
28
+ status,
29
+ headers: { 'Content-Type': 'text/plain; charset=utf-8', ...NO_CACHE, ...headers },
30
+ });
31
+ }
32
+
33
+ /** 401 with a Basic challenge, so git asks its credential helper and retries. */
34
+ export function unauthorized(realm: string): Response {
35
+ return textResponse(401, 'Authentication required', { 'WWW-Authenticate': `Basic realm="${realm}"` });
36
+ }
37
+
38
+ /**
39
+ * A refusal git prints as "fatal: remote error: <message>": an "ERR" packet, after the
40
+ * "# service=…" preamble for an info/refs request.
41
+ */
42
+ export function errResponse(
43
+ service: GitServiceName,
44
+ endpoint: 'info-refs' | 'rpc',
45
+ message: string,
46
+ ): Response {
47
+ const err = encodeErrPacket(message);
48
+ const body =
49
+ endpoint === 'info-refs' ? concatBytes([encodePktLine(`# service=${service}\n`), FLUSH_PKT, err]) : err;
50
+ const kind = endpoint === 'info-refs' ? 'advertisement' : 'result';
51
+ return new Response(body, {
52
+ status: 200,
53
+ headers: { 'Content-Type': `application/x-${service}-${kind}`, ...NO_CACHE },
54
+ });
55
+ }
56
+
57
+ /** One update a refused push names, and why it was refused. */
58
+ export interface RefRefusal {
59
+ readonly ref: string;
60
+ readonly reason: string;
61
+ }
62
+
63
+ /**
64
+ * The receive-pack response refusing a whole push in-protocol: "ng <ref> <reason>" for every
65
+ * update (git prints "! [remote rejected] <ref> (<reason>)"), with each reason also sent as
66
+ * progress text when a side-band was negotiated (git prints "remote: …"). A client that did not
67
+ * ask for report-status gets an ERR packet instead.
68
+ */
69
+ export function refusePush(capabilities: readonly string[], refusals: readonly RefRefusal[]): Response {
70
+ const headers = { 'Content-Type': 'application/x-git-receive-pack-result', ...NO_CACHE };
71
+ const wantsReport = capabilities.includes('report-status') || capabilities.includes('report-status-v2');
72
+ if (!wantsReport) {
73
+ return new Response(encodeErrPacket(refusals[0]?.reason ?? 'push refused'), { status: 200, headers });
74
+ }
75
+ const framing = reportStatusFraming(capabilities);
76
+ const report = encodeReportStatus(
77
+ { unpack: 'ok', refs: refusals.map(({ ref, reason }) => ({ ref, status: 'ng', reason })) },
78
+ framing,
79
+ );
80
+ if (framing.sideBand === 'none') return new Response(report, { status: 200, headers });
81
+ const progress = new TextEncoder().encode(
82
+ refusals.map(({ ref, reason }) => `git-gateway: ${ref}: ${reason}\n`).join(''),
83
+ );
84
+ const maxPayload = framing.sideBand === 'side-band' ? SIDE_BAND_MAX_PAYLOAD : SIDE_BAND_64K_MAX_PAYLOAD;
85
+ return new Response(concatBytes([encodeSideBand(BAND_PROGRESS, progress, maxPayload), report]), {
86
+ status: 200,
87
+ headers,
88
+ });
89
+ }
@@ -0,0 +1,49 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import type { GitOperation, SmartHttpEndpoint } from '@leed-ai/git-gateway-contract/proxy/git-operation';
3
+ import { RepoName } from '@leed-ai/git-gateway-contract/schemas/names';
4
+
5
+ /** A git service as named on the wire. */
6
+ export type GitServiceName = 'git-upload-pack' | 'git-receive-pack';
7
+
8
+ /** What a smart-HTTP request addresses. */
9
+ export interface GitRequest {
10
+ readonly repo: RepoName;
11
+ readonly endpoint: SmartHttpEndpoint;
12
+ readonly service: GitServiceName;
13
+ readonly operation: GitOperation;
14
+ }
15
+
16
+ /** Why a path is not a smart-HTTP request the gateway serves. */
17
+ export type GitRouteFailure = 'not-found' | 'dumb-http';
18
+
19
+ const PATH = /^\/([^/]+)\.git\/(info\/refs|git-upload-pack|git-receive-pack)$/;
20
+
21
+ /**
22
+ * Resolves `/<repo>.git/info/refs?service=…`, `/<repo>.git/git-upload-pack` and
23
+ * `/<repo>.git/git-receive-pack`. An info/refs request without a smart service is "dumb-http"
24
+ * (unsupported); anything else, including a repository name the contract does not allow, is
25
+ * "not-found".
26
+ */
27
+ export function resolveGitRequest(url: URL): GitRequest | GitRouteFailure {
28
+ const match = PATH.exec(url.pathname);
29
+ if (match === null) return 'not-found';
30
+ let name: string;
31
+ try {
32
+ name = decodeURIComponent(match[1] ?? '');
33
+ } catch {
34
+ return 'not-found';
35
+ }
36
+ const repo = RepoName.safeParse(name);
37
+ if (!repo.success) return 'not-found';
38
+ const rest = match[2];
39
+ const service = rest === 'info/refs' ? url.searchParams.get('service') : rest;
40
+ if (service !== 'git-upload-pack' && service !== 'git-receive-pack') return 'dumb-http';
41
+ const endpoint: SmartHttpEndpoint =
42
+ rest === 'info/refs' ? 'info-refs' : service === 'git-upload-pack' ? 'upload-pack' : 'receive-pack';
43
+ return {
44
+ repo: repo.data,
45
+ endpoint,
46
+ service,
47
+ operation: service === 'git-receive-pack' ? 'write' : 'read',
48
+ };
49
+ }
@@ -0,0 +1,91 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import type { AuditRefOutcome } from '@leed-ai/git-gateway-contract/proxy/audit-event';
3
+ import { FullRefName } from '@leed-ai/git-gateway-contract/schemas/names';
4
+ import type { RefUpdate } from '@leed-ai/git-gateway-contract/schemas/ref-update';
5
+
6
+ import type { Logger } from '../logging/logger.ts';
7
+ import type { OnPushHook } from '../workflows/on-push.ts';
8
+ import type { PushEvent } from '../workflows/push-event.ts';
9
+
10
+ /** Most updates one push event carries (the PushEvent schema's cap); a larger push is split. */
11
+ export const MAX_EVENT_UPDATES = 1000;
12
+
13
+ /**
14
+ * The push events for a smart-HTTP push, from the per-ref outcomes read from the storage host's
15
+ * report-status: one event per {@link MAX_EVENT_UPDATES} updates the host reported "ok", in the
16
+ * order the push named them. Refused and unknown updates are left out; no accepted update, no
17
+ * event.
18
+ */
19
+ export function pushEventsFrom(
20
+ repo: string,
21
+ outcomes: readonly AuditRefOutcome[],
22
+ pushedAt: string,
23
+ ): PushEvent[] {
24
+ const updates: RefUpdate[] = outcomes
25
+ .filter((outcome) => outcome.status === 'ok' && FullRefName.safeParse(outcome.ref).success)
26
+ .map(({ ref, oldSha, newSha }) => ({ ref, oldSha, newSha }));
27
+ const events: PushEvent[] = [];
28
+ for (let start = 0; start < updates.length; start += MAX_EVENT_UPDATES) {
29
+ events.push({ repo, updates: updates.slice(start, start + MAX_EVENT_UPDATES), pushedAt });
30
+ }
31
+ return events;
32
+ }
33
+
34
+ /** What {@link deliverPushEvents} needs from the gateway. */
35
+ export interface PushEventSink {
36
+ readonly onPush: OnPushHook;
37
+ readonly onPushError: (error: unknown) => void;
38
+ readonly logger: Logger;
39
+ readonly now: () => Date;
40
+ }
41
+
42
+ /**
43
+ * Hands the accepted updates of a smart-HTTP push to the deployment's onPush hook, once the
44
+ * storage host's report has been read. The push has already happened, so nothing here changes the
45
+ * response: a hook failure is logged and passed to `onPushError`. When the report could not be
46
+ * read (too large, malformed) no event is sent and a warning is logged. Never rejects.
47
+ */
48
+ export async function deliverPushEvents(
49
+ sink: PushEventSink,
50
+ repo: string,
51
+ outcomes: Promise<readonly AuditRefOutcome[]>,
52
+ requestId: string,
53
+ ): Promise<void> {
54
+ let refs: readonly AuditRefOutcome[];
55
+ try {
56
+ refs = await outcomes;
57
+ } catch (error) {
58
+ report(sink, requestId, repo, error);
59
+ return;
60
+ }
61
+ if (refs.some((ref) => ref.status === 'unknown')) {
62
+ sink.logger.log({
63
+ level: 'warn',
64
+ message: 'push event incomplete: the storage host report could not be read for every ref',
65
+ requestId,
66
+ repo,
67
+ });
68
+ }
69
+ for (const event of pushEventsFrom(repo, refs, sink.now().toISOString())) {
70
+ try {
71
+ await sink.onPush(event);
72
+ } catch (error) {
73
+ report(sink, requestId, repo, error);
74
+ }
75
+ }
76
+ }
77
+
78
+ function report(sink: PushEventSink, requestId: string, repo: string, error: unknown): void {
79
+ sink.logger.log({
80
+ level: 'error',
81
+ message: 'onPush hook failed',
82
+ requestId,
83
+ repo,
84
+ error: error instanceof Error ? error.message : String(error),
85
+ });
86
+ try {
87
+ sink.onPushError(error);
88
+ } catch {
89
+ // The error handler failed too; the failure is already logged.
90
+ }
91
+ }
@@ -0,0 +1,109 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { concatBytes } from '@leed-ai/git-gateway-core/bytes';
3
+ import { PackScanner, type PackScan } from '@leed-ai/git-gateway-core/pack/pack-scanner';
4
+
5
+ import type { RefRefusal } from './git-responses.ts';
6
+
7
+ /** A pack ends with a 20-byte SHA-1 checksum; holding it back keeps the host from completing the push. */
8
+ const HELD_BYTES = 20;
9
+
10
+ /** The error a guarded stream fails with when the push is refused; the host never sees a complete pack. */
11
+ export class PushRefused extends Error {
12
+ override readonly name = 'PushRefused';
13
+ readonly refusals: readonly RefRefusal[];
14
+
15
+ constructor(refusals: readonly RefRefusal[]) {
16
+ super(`push refused: ${refusals.map((refusal) => refusal.ref).join(', ')}`);
17
+ this.refusals = refusals;
18
+ }
19
+ }
20
+
21
+ /** Options of {@link guardPush}. */
22
+ export interface PushGuardOptions {
23
+ /** Bytes before the pack (the update commands), forwarded without scanning. */
24
+ readonly headLength: number;
25
+ /** Most bytes of commits the scan keeps. */
26
+ readonly maxCommitBytes: number;
27
+ /**
28
+ * Keep the whole pack (checksum included), at most this many bytes, and hand it to `decide`; a
29
+ * longer pack is refused with `tooLarge`. Absent: nothing is kept.
30
+ */
31
+ readonly keepPack?: { readonly maxBytes: number; readonly tooLarge: string };
32
+ /**
33
+ * Decides the push once the whole pack has been scanned, given the pack when `keepPack` asked
34
+ * for it (null otherwise); returns the refused updates (none to allow it).
35
+ */
36
+ readonly decide: (scan: PackScan, pack: Uint8Array | null) => Promise<readonly RefRefusal[]>;
37
+ /** Called with every refused update, scan failures included, before the stream fails. */
38
+ readonly onRefused: (refusals: readonly RefRefusal[]) => void;
39
+ /** The refs to refuse when the pack cannot be scanned, with the reason to give for each. */
40
+ readonly refuseAll: (reason: string) => readonly RefRefusal[];
41
+ }
42
+
43
+ /**
44
+ * A pass-through for a push body that scans the pack as it streams to the storage host, so the
45
+ * gateway can prove fast-forwards from commits the host does not have yet — without buffering the
46
+ * pack. Everything is forwarded as it arrives except the last 20 bytes, the pack checksum; once
47
+ * the body has ended and the scan is complete, `decide` runs, and only if it refuses nothing are
48
+ * those bytes released. With `keepPack`, the pack is also kept (bounded) for `decide` to read
49
+ * whole, as the push policy needs to compute changed paths. On a refusal (or a pack that cannot be read) the stream fails instead, so
50
+ * the host sees a truncated pack and updates no ref.
51
+ */
52
+ export function guardPush(options: PushGuardOptions): TransformStream<Uint8Array, Uint8Array> {
53
+ const scanner = new PackScanner({ maxCommitBytes: options.maxCommitBytes });
54
+ let position = 0;
55
+ let held = new Uint8Array(0);
56
+ const kept: Uint8Array[] = [];
57
+ let keptBytes = 0;
58
+
59
+ const refuse = (refusals: readonly RefRefusal[]): PushRefused => {
60
+ options.onRefused(refusals);
61
+ return new PushRefused(refusals);
62
+ };
63
+ const unreadable = (error: unknown): PushRefused => {
64
+ const detail = error instanceof Error ? error.message : String(error);
65
+ return refuse(options.refuseAll(`the pushed pack could not be checked: ${detail}`));
66
+ };
67
+
68
+ return new TransformStream<Uint8Array, Uint8Array>({
69
+ async transform(chunk, controller) {
70
+ const start = position;
71
+ position += chunk.length;
72
+ if (position > options.headLength) {
73
+ const packBytes = chunk.subarray(Math.max(0, options.headLength - start));
74
+ if (options.keepPack !== undefined) {
75
+ keptBytes += packBytes.length;
76
+ if (keptBytes > options.keepPack.maxBytes)
77
+ throw refuse(options.refuseAll(options.keepPack.tooLarge));
78
+ kept.push(packBytes.slice());
79
+ }
80
+ try {
81
+ await scanner.push(packBytes);
82
+ } catch (error) {
83
+ throw unreadable(error);
84
+ }
85
+ }
86
+ if (chunk.length >= HELD_BYTES) {
87
+ if (held.length > 0) controller.enqueue(held);
88
+ controller.enqueue(chunk.subarray(0, chunk.length - HELD_BYTES));
89
+ held = chunk.slice(chunk.length - HELD_BYTES);
90
+ return;
91
+ }
92
+ const joined = concatBytes([held, chunk]);
93
+ const release = Math.max(0, joined.length - HELD_BYTES);
94
+ if (release > 0) controller.enqueue(joined.slice(0, release));
95
+ held = joined.slice(release);
96
+ },
97
+ async flush(controller) {
98
+ let scan: PackScan;
99
+ try {
100
+ scan = scanner.finish();
101
+ } catch (error) {
102
+ throw unreadable(error);
103
+ }
104
+ const refusals = await options.decide(scan, options.keepPack === undefined ? null : concatBytes(kept));
105
+ if (refusals.length > 0) throw refuse(refusals);
106
+ if (held.length > 0) controller.enqueue(held);
107
+ },
108
+ });
109
+ }
@@ -0,0 +1,38 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import type { ReceivePackRequest } from '@leed-ai/git-gateway-core/schemas/receive-pack';
3
+
4
+ /** The name of a push option: the part of `<name>[=<value>]` before the first "=". */
5
+ export function pushOptionName(option: string): string {
6
+ const equals = option.indexOf('=');
7
+ return equals === -1 ? option : option.slice(0, equals);
8
+ }
9
+
10
+ /**
11
+ * The names of a push's options that are not on the allowlist, deduplicated, in the order sent.
12
+ * A storage host acts on push options with the gateway's own credential — GitLab opens and
13
+ * auto-merges merge requests (`merge_request.*`) and sets CI variables (`ci.variable`) — so an
14
+ * option outside the allowlist would let a push reach refs the branch policy never saw.
15
+ */
16
+ export function disallowedPushOptions(
17
+ request: Pick<ReceivePackRequest, 'pushOptions'>,
18
+ allowed: readonly string[],
19
+ ): string[] {
20
+ const permitted = new Set(allowed);
21
+ const refused = new Set<string>();
22
+ for (const option of request.pushOptions) {
23
+ const name = pushOptionName(option);
24
+ if (!permitted.has(name)) refused.add(name);
25
+ }
26
+ return [...refused];
27
+ }
28
+
29
+ /**
30
+ * The reason a push refused for its options is given: the option names only (a value may be a
31
+ * secret, such as a CI variable), each cut to 100 characters, at most five of them.
32
+ */
33
+ export function pushOptionsReason(names: readonly string[]): string {
34
+ const shown = names.slice(0, 5).map((name) => JSON.stringify(name.slice(0, 100)));
35
+ const more = names.length > 5 ? ` and ${names.length - 5} more` : '';
36
+ const noun = names.length === 1 ? 'push option' : 'push options';
37
+ return `${noun} ${shown.join(', ')}${more} not allowed by this gateway`;
38
+ }
@@ -0,0 +1,257 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import type { Handler } from 'hono';
3
+
4
+ import { readPushOutcomes, rejectedOutcomes, unknownOutcomes } from '../audit/push-report.ts';
5
+ import { provePending } from '../policy/branch-policy.ts';
6
+ import { COLLATERAL_REASON, refuseAll } from '../policy/enforce-branch-policy.ts';
7
+ import { deferWith } from './defer.ts';
8
+ import type { GatewayDeps } from './gateway-deps.ts';
9
+ import type { GatewayEnv } from './gateway-env.ts';
10
+ import { refusePush, textResponse, type RefRefusal } from './git-responses.ts';
11
+ import { deliverPushEvents } from './push-events.ts';
12
+ import { judgeChangedPaths } from '../push-policy/run-push-policy.ts';
13
+ import { guardPush } from './push-guard.ts';
14
+ import { callUpstream, streamToClient, type UpstreamResult } from './upstream-call.ts';
15
+
16
+ /** Bytes of a host report read for push events when the audit report is switched off (1 MiB). */
17
+ const DEFAULT_REPORT_BYTES = 1024 * 1024;
18
+
19
+ /** The reason given for every update when proving the push failed unexpectedly. */
20
+ const UNCHECKED_REASON = 'the push could not be checked; try again later';
21
+
22
+ /** Waits for `promise`, but at most `ms` milliseconds. */
23
+ async function within(promise: Promise<void>, ms: number): Promise<void> {
24
+ let timer: ReturnType<typeof setTimeout> | undefined;
25
+ const timeout = new Promise<void>((resolve) => {
26
+ timer = setTimeout(resolve, ms);
27
+ });
28
+ await Promise.race([promise, timeout]);
29
+ clearTimeout(timer);
30
+ }
31
+
32
+ /**
33
+ * Holds a 2xx storage host answer back until the push guard has decided, so a host that answers
34
+ * before reading the whole body cannot carry a push past a refusal made later. Returns once the
35
+ * guard's verdict is in, or once the host's answer has ended without one (the host stopped
36
+ * reading, so it never got the pack checksum and updated nothing); the answer is buffered by the
37
+ * tee meanwhile and handed back whole. On a refusal the watching branch is cancelled as well.
38
+ */
39
+ async function awaitVerdict(
40
+ upstream: Response,
41
+ verdict: Promise<void>,
42
+ isRefused: () => boolean,
43
+ ): Promise<UpstreamResult> {
44
+ const [watched, kept] = (upstream.body ?? new Blob([]).stream()).tee();
45
+ const reader = watched.getReader();
46
+ const ended = (async () => {
47
+ try {
48
+ for (let next = await reader.read(); !next.done; next = await reader.read());
49
+ } catch {
50
+ // The host's answer failed: it is over either way.
51
+ }
52
+ })();
53
+ await Promise.race([verdict, ended]);
54
+ if (isRefused()) await reader.cancel().catch(() => undefined);
55
+ const init = { status: upstream.status, statusText: upstream.statusText, headers: upstream.headers };
56
+ return { ok: true, response: new Response(kept, init) };
57
+ }
58
+
59
+ /**
60
+ * Forwards a push the branch policy let through. When fast-forwards remain to be proven from the
61
+ * pack, or the push policy is to be given changed paths computed from it, the body streams through a guard that scans it and holds back the pack checksum until
62
+ * they are; a refusal then fails the upstream request (the host gets a truncated pack and updates
63
+ * nothing) and the client is told in-protocol which refs were refused and why. The host's answer
64
+ * is held until that verdict is known — and when the host's request fails first, the verdict is
65
+ * still awaited (at most `maxVerdictWaitMs`), so a refusal is never mistaken for a storage
66
+ * failure — and the push is audited only after it; otherwise it
67
+ * streams back untouched. When an audit hook or an onPush hook is set, a copy of the answer is
68
+ * read for per-ref outcomes: the audit event gets them, and the refs the host accepted go to the
69
+ * onPush hook as push events, both after the response through `waitUntil`.
70
+ */
71
+ export function receivePack(deps: GatewayDeps): Handler<GatewayEnv> {
72
+ return async (context) => {
73
+ const requestId = context.get('requestId');
74
+ const principal = context.get('principal');
75
+ const git = context.get('git');
76
+ const push = context.get('push');
77
+ const defer = deferWith(context);
78
+ const commands = push.request.commands;
79
+ let refused: readonly RefRefusal[] | null = null;
80
+ /** Settles once the guard has allowed or refused the push, or will never decide it. */
81
+ const { promise: verdict, resolve: settleVerdict } = Promise.withResolvers<void>();
82
+ let deciding = false;
83
+ const { policyUpdates } = push;
84
+ const guarded = push.pending.length > 0 || policyUpdates !== null;
85
+ if (push.pending.length > 0) {
86
+ deps.logger.log({
87
+ level: 'debug',
88
+ message: 'proving fast-forwards from the pushed pack',
89
+ requestId,
90
+ repo: git.repo,
91
+ refs: push.pending.map(({ update }) => update.ref),
92
+ });
93
+ }
94
+ let body = push.body;
95
+ if (guarded) {
96
+ const { pushPolicy } = deps;
97
+ const maxPackBytes = deps.config.maxPushPolicyPackBytes;
98
+ const guard = guardPush({
99
+ headLength: push.headLength,
100
+ maxCommitBytes: deps.config.maxScannedCommitBytes,
101
+ ...(policyUpdates === null
102
+ ? {}
103
+ : {
104
+ keepPack: {
105
+ maxBytes: maxPackBytes,
106
+ tooLarge: `the push policy could not check this push: the pack is larger than ${maxPackBytes} bytes`,
107
+ },
108
+ }),
109
+ decide: async (scan, pack) => {
110
+ deciding = true;
111
+ let refusals: readonly RefRefusal[];
112
+ try {
113
+ refusals = await provePending(deps, git, push.pending, scan.commits);
114
+ if (
115
+ refusals.length === 0 &&
116
+ policyUpdates !== null &&
117
+ pushPolicy !== undefined &&
118
+ pack !== null
119
+ ) {
120
+ refusals = await judgeChangedPaths(
121
+ { pushPolicy, backend: deps.backend, config: deps.config },
122
+ { principal, repo: git.repo, updates: policyUpdates },
123
+ pack,
124
+ );
125
+ }
126
+ } catch (error) {
127
+ deps.logger.log({
128
+ level: 'error',
129
+ message: 'proving the push failed',
130
+ requestId,
131
+ repo: git.repo,
132
+ error: error instanceof Error ? error.message : String(error),
133
+ });
134
+ refusals = commands.map((command) => ({ ref: command.ref, reason: UNCHECKED_REASON }));
135
+ }
136
+ if (refusals.length === 0) settleVerdict();
137
+ return refusals;
138
+ },
139
+ onRefused: (refusals) => {
140
+ refused = refuseAll(push.request, refusals);
141
+ settleVerdict();
142
+ },
143
+ refuseAll: (reason) => commands.map((command) => ({ ref: command.ref, reason })),
144
+ });
145
+ // The pipe fails when the host stops reading (or the client stops sending); if that happens
146
+ // before the pack has been scanned, no verdict will ever come.
147
+ push.body.pipeTo(guard.writable).catch(() => {
148
+ if (!deciding) settleVerdict();
149
+ });
150
+ body = guard.readable;
151
+ }
152
+ const refusal = (all: readonly RefRefusal[]): Response => {
153
+ const reasons = new Map(all.map((entry) => [entry.ref, entry.reason]));
154
+ const reason = all.find((entry) => entry.reason !== COLLATERAL_REASON)?.reason ?? COLLATERAL_REASON;
155
+ deps.audit.record(
156
+ {
157
+ requestId,
158
+ principal,
159
+ git,
160
+ outcome: 'denied',
161
+ reason,
162
+ refs: rejectedOutcomes(push.request, reasons, reason),
163
+ },
164
+ defer,
165
+ requestId,
166
+ );
167
+ deps.logger.log({
168
+ level: 'info',
169
+ message: 'push refused after scanning its pack',
170
+ requestId,
171
+ repo: git.repo,
172
+ reason,
173
+ });
174
+ const response = refusePush(push.request.capabilities, all);
175
+ response.headers.set('X-Request-Id', requestId);
176
+ return response;
177
+ };
178
+ let result: UpstreamResult | null = null;
179
+ let failure: unknown = null;
180
+ try {
181
+ result = await callUpstream(deps, context, body);
182
+ } catch (error) {
183
+ failure = error;
184
+ }
185
+ if (guarded) {
186
+ if (result?.ok === true) result = await awaitVerdict(result.response, verdict, () => refused !== null);
187
+ // A refusal fails the host's request by design (the pack is cut short), and the host may
188
+ // notice before the guard has recorded its verdict: wait for it, so a refused push is
189
+ // answered in-protocol rather than as a storage failure.
190
+ else if (refused === null) await within(verdict, deps.config.maxVerdictWaitMs);
191
+ }
192
+ if (refused !== null) {
193
+ await result?.response.body?.cancel().catch(() => undefined);
194
+ return refusal(refused);
195
+ }
196
+ if (result === null) {
197
+ deps.logger.log({
198
+ level: 'error',
199
+ message: 'storage host unreachable',
200
+ requestId,
201
+ repo: git.repo,
202
+ error: failure instanceof Error ? failure.message : String(failure),
203
+ });
204
+ const reason = 'The storage backend is unreachable; try again later';
205
+ deps.audit.record(
206
+ { requestId, principal, git, outcome: 'failed', reason, refs: unknownOutcomes(push.request) },
207
+ defer,
208
+ requestId,
209
+ );
210
+ return textResponse(502, reason, { 'X-Request-Id': requestId });
211
+ }
212
+ if (!result.ok) {
213
+ deps.audit.record(
214
+ {
215
+ requestId,
216
+ principal,
217
+ git,
218
+ outcome: 'failed',
219
+ reason: result.reason,
220
+ refs: unknownOutcomes(push.request),
221
+ },
222
+ defer,
223
+ requestId,
224
+ );
225
+ return result.response;
226
+ }
227
+ const upstream = result.response;
228
+ const auditReport = deps.audit.enabled && deps.config.maxAuditReportBytes > 0;
229
+ const onPush = deps.onPush;
230
+ const unknown = { requestId, principal, git, outcome: 'allowed' as const, reason: null };
231
+ if (upstream.body === null || (!auditReport && onPush === undefined)) {
232
+ deps.audit.record({ ...unknown, refs: unknownOutcomes(push.request) }, defer, requestId);
233
+ return streamToClient(upstream, upstream.body, requestId);
234
+ }
235
+ const [toClient, toReport] = upstream.body.tee();
236
+ const limit = auditReport ? deps.config.maxAuditReportBytes : DEFAULT_REPORT_BYTES;
237
+ const outcomes = readPushOutcomes(toReport, push.request, limit);
238
+ deps.audit.record(
239
+ auditReport
240
+ ? outcomes.then((refs) => ({ ...unknown, refs }))
241
+ : { ...unknown, refs: unknownOutcomes(push.request) },
242
+ defer,
243
+ requestId,
244
+ );
245
+ if (onPush !== undefined) {
246
+ defer(
247
+ deliverPushEvents(
248
+ { onPush, onPushError: deps.onPushError, logger: deps.logger, now: deps.now },
249
+ git.repo,
250
+ outcomes,
251
+ requestId,
252
+ ),
253
+ );
254
+ }
255
+ return streamToClient(upstream, toClient, requestId);
256
+ };
257
+ }
@@ -0,0 +1,44 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { RequestId } from '@leed-ai/git-gateway-contract/proxy/audit-event';
3
+ import type { MiddlewareHandler } from 'hono';
4
+
5
+ import type { Logger } from '../logging/logger.ts';
6
+ import type { GatewayEnv } from './gateway-env.ts';
7
+
8
+ /** The id of a request: its Cloudflare Ray id when it has a valid one, otherwise a random UUID. */
9
+ export function requestIdOf(request: Request): string {
10
+ const ray = RequestId.safeParse(request.headers.get('CF-Ray'));
11
+ return ray.success ? ray.data : crypto.randomUUID();
12
+ }
13
+
14
+ /**
15
+ * The first middleware: gives the request an id (returned as X-Request-Id) and writes one
16
+ * structured log entry when it is answered — method, path, status, duration, repository,
17
+ * endpoint and principal subject. Never the query string beyond `service`, never a header value,
18
+ * never a credential.
19
+ */
20
+ export function requestLog(logger: Logger, now: () => Date): MiddlewareHandler<GatewayEnv> {
21
+ return async (context, next) => {
22
+ const requestId = requestIdOf(context.req.raw);
23
+ context.set('requestId', requestId);
24
+ const started = now().getTime();
25
+ await next();
26
+ context.res.headers.set('X-Request-Id', requestId);
27
+ const url = new URL(context.req.url);
28
+ const git = context.get('git') as GatewayEnv['Variables']['git'] | undefined;
29
+ const principal = context.get('principal') as GatewayEnv['Variables']['principal'] | undefined;
30
+ logger.log({
31
+ level: context.res.status >= 500 ? 'error' : 'info',
32
+ message: 'request',
33
+ requestId,
34
+ method: context.req.method,
35
+ path: url.pathname,
36
+ service: url.searchParams.get('service'),
37
+ status: context.res.status,
38
+ durationMs: now().getTime() - started,
39
+ repo: git?.repo ?? null,
40
+ endpoint: git?.endpoint ?? null,
41
+ principal: principal?.subject ?? null,
42
+ });
43
+ };
44
+ }