Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

VcsProcess.ts

381 lines13.8 KB

1import * as Context from "effect/Context";
2import * as Duration from "effect/Duration";
3import * as Effect from "effect/Effect";
4import * as Layer from "effect/Layer";
5import * as Match from "effect/Match";
6import * as Schedule from "effect/Schedule";
7import * as Semaphore from "effect/Semaphore";
8import { ChildProcessSpawner } from "effect/process";
9​
10import {
11 type VcsError,
12 type VcsProcessErrorContext,
13 VcsProcessExitError,
14 type VcsProcessExitFailureKind,
15 VcsProcessMissingExitCodeError,
16 VcsProcessOutputLimitError,
17 VcsProcessOutputReadError,
18 VcsProcessSpawnError,
19 VcsProcessStdinWriteError,
20 VcsProcessTimeoutError,
21} from "@t3tools/contracts";
22import * as HostProcess from "@t3tools/shared/HostProcess";
23import type { SourceControlProcessInput } from "@t3tools/source-control-core/server/SourceControlHost";
24​
25import { gitCommandDuration, gitCommandsTotal, withMetrics } from "../observability/Metrics.ts";
26import * as ProcessRunner from "../processRunner.ts";
27​
28export interface VcsProcessInput {
29 readonly operation: string;
30 readonly command: string;
31 readonly args: ReadonlyArray<string>;
32 readonly cwd: string;
33 readonly spawnCwd?: string;
34 readonly stdin?: string;
35 readonly onStdoutChunk?: (chunk: Uint8Array) => void;
36 readonly env?: NodeJS.ProcessEnv;
37 readonly allowNonZeroExit?: boolean;
38 readonly timeoutMs?: number;
39 readonly maxOutputBytes?: number;
40 readonly outputMode?: ProcessRunner.ProcessRunInput["outputMode"];
41 readonly appendTruncationMarker?: boolean;
42 readonly classifyFailure?: SourceControlProcessInput["classifyFailure"];
43 readonly notFoundDetail?: string;
44 readonly concurrency?: SourceControlProcessInput["concurrency"];
46​
47export interface VcsProcessOutput {
48 readonly exitCode: ChildProcessSpawner.ExitCode;
49 readonly stdout: string;
50 readonly stderr: string;
51 readonly stdoutTruncated: boolean;
52 readonly stderrTruncated: boolean;
53 readonly stdoutInvalidUtf8?: boolean;
54 readonly stderrInvalidUtf8?: boolean;
56​
57export class VcsProcess extends Context.Service<
58 VcsProcess,
59 {
60 readonly run: (input: VcsProcessInput) => Effect.Effect<VcsProcessOutput, VcsError>;
61 }
62>()("t3/vcs/VcsProcess") {}
63​
64const DEFAULT_TIMEOUT_MS = 30_000;
65const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
66const OUTPUT_TRUNCATED_MARKER = "\n\n[truncated]";
67const VCS_PROCESS_CONCURRENCY = 8;
68// Forge CLIs can take seconds per call; cap them together so git, checkpoints included, keeps slots.
69const NON_GIT_PROCESS_CONCURRENCY = VCS_PROCESS_CONCURRENCY / 2;
70​
71/** Shown to users when a Git command fails because another process holds the index lock. */
72export const GIT_INDEX_LOCKED_DETAIL =
73 "Git's index is locked. Wait for other Git operations to finish, then try again.";
74​
75export const CHECKPOINT_CAPTURE_OPERATION = "GitVcsDriver.checkpoints.captureCheckpoint";
76​
77// Caller operations are diagnostic strings; only known labels may become metric attributes.
78const gitMetricOperations = new Set([
79 CHECKPOINT_CAPTURE_OPERATION,
80 "GitVcsDriver.checkpoints.deleteCheckpointRefs",
81 "GitVcsDriver.checkpoints.diffCheckpoints",
82 "GitVcsDriver.checkpoints.hasHeadCommit",
83 "GitVcsDriver.checkpoints.listAuthoredPaths",
84 "GitVcsDriver.checkpoints.resolveCheckpointCommit",
85 "GitVcsDriver.checkpoints.resolveGitCommonDir",
86 "GitVcsDriver.checkpoints.resolveHeadCommit",
87 "GitVcsDriver.checkpoints.restoreCheckpoint",
88 "GitVcsDriver.detectRepository",
89 "GitVcsDriver.filterIgnoredPaths",
90 "GitVcsDriver.initRepository",
91 "GitVcsDriver.isInsideWorkTree",
92 "GitVcsDriver.listRemotes",
93 "GitVcsDriver.listWorkspaceFiles",
94 "GitVcsDriver.resolveGitCommonDir",
95]);
96​
97/**
98 * Append after inherited entries without changing argv or the user's config.
99 * Windows env keys ignore case: read the last spelling of the count so command overrides win,
100 * then update every spelling because Node may keep any one.
101 * Leave invalid counts untouched so Git reports them.
102 */
103export const gitConfigEnv = (
104 env: NodeJS.ProcessEnv,
105 key: string,
106 value: string,
107 platform: NodeJS.Platform,
108): NodeJS.ProcessEnv => {
109 const countKeys = Object.keys(env).filter((name) =>
110 platform === "win32" ? name.toUpperCase() === "GIT_CONFIG_COUNT" : name === "GIT_CONFIG_COUNT",
111 );
112 const countKey = countKeys.at(-1) ?? "GIT_CONFIG_COUNT";
113 const inherited = env[countKey];
114 if (
115 inherited !== undefined &&
116 inherited !== "" &&
117 // Match Git's strtoul count syntax, including whitespace, signs and non-negative -0.
118 /^[ \t\r\n\v\f]*(?:\+?\d+|-0+)/.exec(inherited)?.[0] !== inherited
119 ) {
120 return {};
121 }
122 const count = inherited === undefined || inherited === "" ? 0 : Number.parseInt(inherited, 10);
123 return {
124 ...Object.fromEntries([...countKeys, countKey].map((name) => [name, String(count + 1)])),
125 [`GIT_CONFIG_KEY_${count}`]: key,
126 [`GIT_CONFIG_VALUE_${count}`]: value,
127 };
128};
129​
130/**
131 * A project can contain a fake bare repository whose config runs commands such as `core.fsmonitor`.
132 * Require `--git-dir` or `GIT_DIR` to open bare repositories; Git before 2.38 ignores this setting.
133 */
134export const explicitBareRepositoryEnv = (env: NodeJS.ProcessEnv, platform: NodeJS.Platform) =>
135 gitConfigEnv(env, "safe.bareRepository", "explicit", platform);
136​
137const classifyNonZeroExit = (
138 stderr: string,
139 classifyFailure: VcsProcessInput["classifyFailure"],
140): VcsProcessExitFailureKind => {
141 const normalized = stderr.toLowerCase();
142 const commandKind = classifyFailure?.(stderr) ?? null;
143​
144 if (
145 commandKind === "authentication" ||
146 normalized.includes("authentication failed") ||
147 normalized.includes("not logged in") ||
148 normalized.includes("no oauth token") ||
149 normalized.includes("unauthorized")
150 ) {
151 return "authentication";
152 }
153​
154 if (
155 commandKind === "rate-limited" ||
156 normalized.includes("api rate limit") ||
157 normalized.includes("rate limit exceeded") ||
158 normalized.includes("secondary rate limit") ||
159 normalized.includes("too many requests") ||
160 normalized.includes("http 429")
161 ) {
162 return "rate-limited";
163 }
164​
165 return commandKind ?? "command-failed";
166};
167​
168// Classify before discarding stderr; keep paths and process output out of errors.
169const isTransientGitExit = (stderr: string) =>
170 /unable to create [^\n]*\.lock['"]?: file exists/i.test(stderr) ||
171 /(?:unable to stat|lstat\(|error: open\()[^\n]+: no such file or directory/i.test(stderr);
172​
173// On macOS, Git's fsync uses F_FULLFSYNC; writeout-only still uses fsync(2).
174// Network mounts can reject F_FULLFSYNC. Ref writes omit errno, so retry their
175// bare write error too; explicit unrelated errors remain failures.
176// Linux writeout-only only starts writeback, so it must not use this fallback.
177const FULL_FSYNC_ARG = "core.fsyncMethod=fsync";
178const BATCH_FSYNC_ARG = "core.fsyncMethod=batch";
179const WRITEOUT_ONLY_FSYNC_ARG = "core.fsyncMethod=writeout-only";
180const canRetryFullFsync = (stderr: string) =>
181 /fsync error on [^\r\n]+: operation not supported\r?$/im.test(stderr) ||
182 /cannot update ref [^\r\n]+: couldn't write '[^\r\n]+\.lock'\r?$/im.test(stderr);
183​
184export const make = Effect.gen(function* () {
185 const processRunner = yield* ProcessRunner.ProcessRunner;
186 const hostPlatform = yield* HostProcess.Platform;
187 const vcsProcesses = yield* Semaphore.make(VCS_PROCESS_CONCURRENCY);
188 const nonGitProcesses = yield* Semaphore.make(NON_GIT_PROCESS_CONCURRENCY);
189 const keyedProcesses = new Map<string, Semaphore.Semaphore>();
190 const keyedPermit = (concurrency: NonNullable<VcsProcessInput["concurrency"]>) => {
191 let semaphore = keyedProcesses.get(concurrency.key);
192 if (semaphore === undefined) {
193 semaphore = Semaphore.makeUnsafe(concurrency.limit);
194 keyedProcesses.set(concurrency.key, semaphore);
195 }
196 return semaphore.withPermits(1);
197 };
198​
199 const spawn = Effect.fn("VcsProcess.spawn")(function* (
200 input: VcsProcessInput,
201 baseError: VcsProcessErrorContext,
202 ) {
203 let failedExit = false;
204 const execution = processRunner
205 .run({
206 command: input.command,
207 args: input.args,
208 cwd: input.cwd,
209 ...(input.spawnCwd !== undefined ? { spawnCwd: input.spawnCwd } : {}),
210 ...(input.stdin !== undefined ? { stdin: input.stdin } : {}),
211 ...(input.onStdoutChunk !== undefined ? { onStdoutChunk: input.onStdoutChunk } : {}),
212 env: {
213 // Failures are read by English patterns; without LANG, macOS Git follows the system language.
214 // LANGUAGE leaves LC_CTYPE, which hooks inherit, alone.
215 ...(input.command === "git" ? { LANGUAGE: "C" } : {}),
216 ...input.env,
217 ...explicitBareRepositoryEnv({ ...process.env, ...input.env }, hostPlatform),
218 },
219 timeout: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
220 maxOutputBytes: input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
221 outputMode: input.outputMode ?? "truncate",
222 truncatedMarker: input.appendTruncationMarker ? OUTPUT_TRUNCATED_MARKER : "",
223 timeoutBehavior: "error",
224 })
225 .pipe(
226 Effect.tap((result) => {
227 failedExit = result.code === null || (!input.allowNonZeroExit && result.code !== 0);
228 return Effect.void;
229 }),
230 Effect.mapError(
231 Match.valueTags({
232 ProcessSpawnError: (error) =>
233 VcsProcessSpawnError.fromProcessSpawnError(baseError, error),
234 ProcessOutputLimitError: (error) =>
235 new VcsProcessOutputLimitError({
236 ...baseError,
237 stream: error.stream,
238 maxBytes: error.maxBytes,
239 observedBytes: error.observedBytes,
240 }),
241 ProcessTimeoutError: (error) =>
242 VcsProcessTimeoutError.fromProcessTimeoutError(baseError, error),
243 ProcessStdinError: (error) =>
244 new VcsProcessStdinWriteError({
245 ...baseError,
246 stdinBytes: error.stdinBytes,
247 cause: error.cause,
248 }),
249 ProcessReadError: (error) =>
250 new VcsProcessOutputReadError({
251 ...baseError,
252 stream: error.stream,
253 cause: error.cause,
254 }),
255 }),
256 ),
257 );
258​
259 return yield* input.command === "git"
260 ? execution.pipe(
261 withMetrics({
262 counter: gitCommandsTotal,
263 timer: gitCommandDuration,
264 attributes: {
265 operation: gitMetricOperations.has(input.operation) ? input.operation : "other",
266 },
267 outcomeAttributes: (outcome) => ({
268 outcome: outcome === "success" && failedExit ? "failure" : outcome,
269 }),
270 }),
271 )
272 : execution;
273 });
274​
275 const runUnbounded = Effect.fn("VcsProcess.runUnbounded")(function* (input: VcsProcessInput) {
276 const baseError = {
277 operation: input.operation,
278 command: input.command,
279 cwd: input.cwd,
280 argumentCount: input.args.length,
281 };
282​
283 let result = yield* spawn(input, baseError);
284​
285 if (
286 hostPlatform === "darwin" &&
287 input.operation === CHECKPOINT_CAPTURE_OPERATION &&
288 !input.allowNonZeroExit &&
289 result.code !== null &&
290 result.code !== 0 &&
291 input.command === "git" &&
292 (input.args.includes(FULL_FSYNC_ARG) || input.args.includes(BATCH_FSYNC_ARG)) &&
293 canRetryFullFsync(result.stderr)
294 ) {
295 result = yield* spawn(
296 {
297 ...input,
298 args: input.args.map((arg) =>
299 arg === FULL_FSYNC_ARG || arg === BATCH_FSYNC_ARG ? WRITEOUT_ONLY_FSYNC_ARG : arg,
300 ),
301 },
302 baseError,
303 );
304 }
305​
306 if (result.code === null) {
307 return yield* new VcsProcessMissingExitCodeError(baseError);
308 }
309​
310 if (!input.allowNonZeroExit && result.code !== 0) {
311 const failureKind = classifyNonZeroExit(result.stderr, input.classifyFailure);
312 const error = VcsProcessExitError.fromProcessExit(
313 baseError,
314 {
315 exitCode: result.code,
316 stderr: result.stderr,
317 stderrTruncated: result.stderrTruncated,
318 },
319 failureKind,
320 {
321 retryable:
322 input.command === "git" &&
323 failureKind === "command-failed" &&
324 isTransientGitExit(result.stderr),
325 ...(input.notFoundDetail === undefined ? {} : { notFoundDetail: input.notFoundDetail }),
326 },
327 );
328 if (
329 input.command === "git" &&
330 /^fatal: unable to create ['"][^\r\n]*[/\\]index\.lock['"]: file exists\.?$/im.test(
331 result.stderr,
332 )
333 ) {
334 return yield* new VcsProcessExitError({
335 ...error,
336 detail: GIT_INDEX_LOCKED_DETAIL,
337 });
338 }
339 return yield* error;
340 }
341​
342 return {
343 exitCode: result.code,
344 stdout: result.stdout,
345 stderr: result.stderr,
346 stdoutTruncated: result.stdoutTruncated,
347 stderrTruncated: result.stderrTruncated,
348 stdoutInvalidUtf8: result.stdoutInvalidUtf8 ?? false,
349 stderrInvalidUtf8: result.stderrInvalidUtf8 ?? false,
350 } satisfies VcsProcessOutput;
351 });
352​
353 const run = Effect.fn("VcsProcess.run")(function* (input: VcsProcessInput) {
354 const bounded = vcsProcesses.withPermits(1)(runUnbounded(input));
355 if (
356 input.command === "git" &&
357 input.operation === CHECKPOINT_CAPTURE_OPERATION &&
358 input.onStdoutChunk === undefined
359 ) {
360 return yield* bounded.pipe(
361 Effect.tapError((error) =>
362 Effect.logDebug("checkpoint Git command failed", {
363 operation: input.operation,
364 errorTag: error._tag,
365 }),
366 ),
367 Effect.retry({
368 times: 2,
369 while: (error) => error._tag === "VcsProcessExitError" && error.retryable === true,
370 schedule: Schedule.spaced(Duration.millis(75)),
371 }),
372 );
373 }
374 const shared = input.command === "git" ? bounded : nonGitProcesses.withPermits(1)(bounded);
375 return yield* input.concurrency === undefined ? shared : keyedPermit(input.concurrency)(shared);
376 });
377​
378 return VcsProcess.of({ run });
379});
380​
381export const layer = Layer.effect(VcsProcess, make).pipe(Layer.provide(ProcessRunner.layer));