@git.zone/cli 8.8.0 → 8.8.2

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.
@@ -1,115 +1,356 @@
1
1
  import * as plugins from "./mod.plugins.js";
2
+ import { logger } from "../gitzone.logging.js";
2
3
  import { describeCommandFailure } from "./helpers.commandfailure.js";
3
4
 
4
5
  /** Bound of one `git ls-remote` attempt unless `release.targets.git.remoteTimeoutSeconds` sets it. */
5
6
  export const defaultReleaseGitRemoteTimeoutSeconds = 180;
6
7
  export const maximumReleaseGitRemoteTimeoutSeconds = 3600;
7
8
 
9
+ /** Bound of one `git fetch` or `git push` attempt, which transfers objects. */
10
+ export const releaseGitTransferTimeoutMs = 5 * 60_000;
11
+
8
12
  /**
9
13
  * How long one remote inspection may take and how often a transient failure
10
- * is retried. Remote inspection only reads refs, so repeating it is safe.
14
+ * is retried.
11
15
  */
12
16
  export interface IReleaseGitRemotePolicy {
13
- /** Bound of one attempt. */
17
+ /** Bound of one `ls-remote` attempt. */
14
18
  timeoutMs: number;
15
19
  /** Wait before each retry; its length is the number of retries. */
16
20
  retryDelaysMs: readonly number[];
17
21
  }
18
22
 
19
- /** Two retries, 5 s and 20 s apart: three attempts in all. */
20
- const defaultRetryDelaysMs: readonly number[] = [5_000, 20_000];
23
+ /**
24
+ * Eight attempts in all, waiting 2, 4, 8 and 16 s and then 30 s three times:
25
+ * two minutes of waiting at most. On 2026-10-05 code.foss.global dropped about
26
+ * two in three ssh connections, so five attempts would still have failed about
27
+ * one step in eight.
28
+ */
29
+ export const releaseGitRemoteRetryDelaysMs: readonly number[] = [
30
+ 2_000, 4_000, 8_000, 16_000, 30_000, 30_000, 30_000,
31
+ ];
32
+
33
+ /** The most waiting any policy may add between the attempts of one step. */
34
+ export const maximumReleaseGitRemoteRetryWaitMs = 180_000;
21
35
 
22
36
  export const createReleaseGitRemotePolicy = (
23
37
  timeoutSecondsArg: number = defaultReleaseGitRemoteTimeoutSeconds,
24
38
  ): IReleaseGitRemotePolicy => ({
25
39
  timeoutMs: timeoutSecondsArg * 1000,
26
- retryDelaysMs: defaultRetryDelaysMs,
40
+ retryDelaysMs: releaseGitRemoteRetryDelaysMs,
27
41
  });
28
42
 
29
- /** The final attempt of a remote inspection and what it took to get there. */
30
- export interface IReleaseGitRemoteResult extends plugins.smartshell.IExecResult {
31
- attempts: number;
32
- elapsedMs: number;
33
- /** The final failure is one a later attempt could have overcome. */
34
- transient: boolean;
43
+ interface IGitRemoteFailurePattern {
44
+ /** Why the failure is classified as it is; every retry line names it. */
45
+ reason: string;
46
+ pattern: RegExp;
35
47
  }
36
48
 
37
49
  /**
38
- * A dropped or refused connection, or a gateway that gave up on a busy
39
- * server, can succeed on the next attempt. Anything that names credentials,
40
- * permissions or a missing repository cannot, so it is never retried.
50
+ * Transport failures a later attempt can overcome: the connection was refused,
51
+ * dropped, reset or timed out, or an HTTP gateway gave up on a busy server.
52
+ * Git adds "Could not read from remote repository" to each of them; on its own
53
+ * that line proves nothing and is not listed. The ssh messages are OpenSSH's:
54
+ * `clientloop.c` prints "Connection to <host> closed by remote host.",
55
+ * `packet.c` "Connection closed by <address> port <n>", "Connection reset by
56
+ * <address> port <n>" and "Connection to <address> port <n> timed out",
57
+ * `kex.c` "kex_exchange_identification: Connection closed by remote host",
58
+ * "kex_exchange_identification: read: Connection reset by peer" and
59
+ * "Connection timed out during banner exchange", and `sshconnect.c`
60
+ * "ssh: connect to host <host> port <n>: Connection refused". Git's
61
+ * `sideband.c` prints "send-pack: unexpected disconnect while reading sideband
62
+ * packet".
41
63
  */
42
- const transientTransportPattern =
43
- /connection reset|reset by peer|ECONNRESET|early EOF|unexpected disconnect|remote end hung up unexpectedly|connection timed out|operation timed out|connection closed by|kex_exchange_identification|broken pipe|RPC failed|returned error: 50[234]\b/i;
44
- const permanentTransportPattern =
45
- /authentication failed|permission denied|could not read (?:username|password)|terminal prompts disabled|access denied|returned error: 40[134]\b|repository not found|does not appear to be a git repository|not found/i;
64
+ const transientGitRemoteFailures: readonly IGitRemoteFailurePattern[] = [
65
+ {
66
+ reason: "ssh connection closed by the remote host",
67
+ pattern: /connection to \S+ closed by remote host|connection closed by/i,
68
+ },
69
+ {
70
+ // A server that is restarting or shedding load refuses the connection
71
+ // before anything is sent; on 2026-10-05 code.foss.global did so between
72
+ // dropped pushes. A wrong port refuses too and fails once the bounded
73
+ // attempts run out.
74
+ reason: "ssh connection refused",
75
+ pattern: /ssh: connect to host \S+ port \d+: connection refused/i,
76
+ },
77
+ {
78
+ reason: "connection reset",
79
+ pattern: /connection reset|reset by peer|ECONNRESET/i,
80
+ },
81
+ {
82
+ reason: "connection timed out",
83
+ pattern:
84
+ /connection timed out|connection to \S+ port \d+ timed out|operation timed out|ETIMEDOUT/i,
85
+ },
86
+ { reason: "unexpected disconnect", pattern: /unexpected disconnect/i },
87
+ {
88
+ reason: "remote end hung up",
89
+ pattern: /remote end hung up unexpectedly/i,
90
+ },
91
+ { reason: "early EOF", pattern: /early EOF/i },
92
+ { reason: "broken pipe", pattern: /broken pipe/i },
93
+ {
94
+ reason: "ssh key exchange interrupted",
95
+ pattern: /kex_exchange_identification/i,
96
+ },
97
+ {
98
+ reason: "HTTP transport failure",
99
+ pattern:
100
+ /RPC failed; (?:curl (?:18|52|55|56|92)|HTTP 50[234])\b|returned error: 50[234]\b/i,
101
+ },
102
+ ];
103
+
104
+ /**
105
+ * Failures no retry overcomes. They win over any transport symptom in the
106
+ * same output, so `Authentication failed` followed by `remote end hung up`
107
+ * fails at once.
108
+ */
109
+ const permanentGitRemoteFailures: readonly IGitRemoteFailurePattern[] = [
110
+ {
111
+ reason: "authentication refused",
112
+ pattern:
113
+ /authentication failed|could not read (?:username|password)|terminal prompts disabled|returned error: 401\b/i,
114
+ },
115
+ {
116
+ reason: "permission denied",
117
+ pattern: /permission denied|access denied|returned error: 403\b/i,
118
+ },
119
+ {
120
+ reason: "repository not found",
121
+ pattern:
122
+ /repository not found|does not appear to be a git repository|not found|returned error: 404\b/i,
123
+ },
124
+ {
125
+ reason: "update rejected",
126
+ pattern: /non-fast-forward|\[(?:remote )?rejected\]|stale info|fetch first/i,
127
+ },
128
+ ];
129
+
130
+ export interface IGitRemoteFailureClass {
131
+ /** A later attempt could overcome the failure. */
132
+ transient: boolean;
133
+ reason: string;
134
+ }
135
+
136
+ const formatSeconds = (msArg: number): string =>
137
+ `${Number((msArg / 1000).toFixed(1))} s`;
46
138
 
47
- export const isTransientGitRemoteFailure = (
139
+ /**
140
+ * Classifies a failed remote command. A timeout is transient; a refused
141
+ * credential, a missing repository or a rejected update is not; otherwise only
142
+ * a known transport failure is. Anything unrecognised, including Git's own
143
+ * answers such as `ls-remote --exit-code` finding no ref, is final.
144
+ */
145
+ export const classifyGitRemoteFailure = (
48
146
  resultArg: plugins.smartshell.IExecResult,
49
- ): boolean => {
50
- if (resultArg.exitCode === 0) return false;
51
- if (resultArg.timedOut) return true;
52
- return (
53
- transientTransportPattern.test(resultArg.stderr) &&
54
- !permanentTransportPattern.test(resultArg.stderr)
147
+ timeoutMsArg: number,
148
+ ): IGitRemoteFailureClass => {
149
+ if (resultArg.timedOut) {
150
+ return {
151
+ transient: true,
152
+ reason: `timed out after ${formatSeconds(timeoutMsArg)}`,
153
+ };
154
+ }
155
+ const permanent = permanentGitRemoteFailures.find((failureArg) =>
156
+ failureArg.pattern.test(resultArg.stderr),
55
157
  );
158
+ if (permanent) return { transient: false, reason: permanent.reason };
159
+ const transient = transientGitRemoteFailures.find((failureArg) =>
160
+ failureArg.pattern.test(resultArg.stderr),
161
+ );
162
+ if (transient) return { transient: true, reason: transient.reason };
163
+ return {
164
+ transient: false,
165
+ reason: resultArg.signal
166
+ ? `terminated by ${resultArg.signal}`
167
+ : `exit code ${resultArg.exitCode}`,
168
+ };
56
169
  };
57
170
 
58
- export interface IRunGitRemoteInspectionOptions {
171
+ /** The final attempt of a remote command and what it took to get there. */
172
+ export interface IReleaseGitRemoteResult extends plugins.smartshell.IExecResult {
173
+ /** The release step the command belongs to. */
174
+ step: string;
175
+ /** `git ls-remote`, `git fetch` or `git push`, without arguments. */
176
+ command: string;
177
+ /** Bound of each attempt. */
178
+ timeoutMs: number;
179
+ attempts: number;
180
+ elapsedMs: number;
181
+ /** The final failure is one a later attempt could have overcome. */
182
+ transient: boolean;
183
+ }
184
+
185
+ /** A push whose final attempt failed may still have landed; see {@link runGitRemotePush}. */
186
+ export interface IReleaseGitRemotePushResult extends IReleaseGitRemoteResult {
187
+ /** A re-inspection found the pushed refs at the remote after a failed attempt. */
188
+ landed: boolean;
189
+ }
190
+
191
+ interface IGitRemoteCommandOptions {
59
192
  smartshell: plugins.smartshell.Smartshell;
60
193
  cwd: string;
61
- /** `ls-remote` arguments, starting with `ls-remote`. */
62
- args: string[];
63
194
  env: NodeJS.ProcessEnv;
64
195
  policy: IReleaseGitRemotePolicy;
196
+ /** The release step; every retry line and every failure names it. */
197
+ step: string;
198
+ }
199
+
200
+ /** The remote reads a release repeats freely: they change no remote state. */
201
+ export type TGitRemoteRead = "ls-remote" | "fetch";
202
+
203
+ export interface IRunGitRemoteReadOptions extends IGitRemoteCommandOptions {
204
+ args: [TGitRemoteRead, ...string[]];
65
205
  }
66
206
 
207
+ /** What re-reading the remote after a failed push attempt proved. */
208
+ export type TGitRemotePushState =
209
+ /** The remote holds the pushed refs: the push is done. */
210
+ | "landed"
211
+ /** The remote is as it was before the push: pushing again is safe. */
212
+ | "absent"
213
+ /** Neither is proven: the push is not repeated. */
214
+ | "unknown";
215
+
216
+ export interface IRunGitRemotePushOptions extends IGitRemoteCommandOptions {
217
+ args: ["push", ...string[]];
218
+ /** Runs before every attempt, the first included; a journaled push claims its attempt here. */
219
+ beforeAttempt?: () => Promise<void>;
220
+ /**
221
+ * Re-reads the remote after a transient failure, before any further
222
+ * attempt. Its reads go through {@link runGitRemoteRead}, so a dropped read
223
+ * is retried like any other; it answers `unknown` only when that read still
224
+ * failed or found refs that are neither the pushed nor the previous state.
225
+ */
226
+ reinspect: () => Promise<TGitRemotePushState>;
227
+ }
228
+
229
+ const assertRetryBudget = (policyArg: IReleaseGitRemotePolicy): void => {
230
+ const totalWaitMs = policyArg.retryDelaysMs.reduce(
231
+ (sumArg, delayArg) => sumArg + delayArg,
232
+ 0,
233
+ );
234
+ if (totalWaitMs > maximumReleaseGitRemoteRetryWaitMs) {
235
+ throw new Error(
236
+ `A Git remote retry policy may wait at most ${formatSeconds(maximumReleaseGitRemoteRetryWaitMs)} in total; this one waits ${formatSeconds(totalWaitMs)}.`,
237
+ );
238
+ }
239
+ };
240
+
67
241
  /**
68
- * Runs one read-only remote inspection under the policy's per-attempt bound,
69
- * repeating it after a transient failure. The caller decides what the final
70
- * answer means; this only makes a slow or flaky remote answer at all.
242
+ * The single retry loop of every remote command of a release. A transient
243
+ * failure is logged with the step and the classified reason, then retried
244
+ * after the policy's next delay; a push re-reads the remote first and is only
245
+ * repeated when the remote provably did not take it.
71
246
  */
72
- export const runGitRemoteInspection = async (
73
- optionsArg: IRunGitRemoteInspectionOptions,
74
- ): Promise<IReleaseGitRemoteResult> => {
247
+ const runGitRemoteCommand = async (
248
+ optionsArg: IGitRemoteCommandOptions & {
249
+ args: string[];
250
+ beforeAttempt?: () => Promise<void>;
251
+ reinspect?: () => Promise<TGitRemotePushState>;
252
+ },
253
+ ): Promise<{ result: IReleaseGitRemoteResult; landed: boolean }> => {
254
+ assertRetryBudget(optionsArg.policy);
255
+ const subcommand = optionsArg.args[0];
256
+ const command = `git ${subcommand}`;
257
+ const timeoutMs =
258
+ subcommand === "ls-remote"
259
+ ? optionsArg.policy.timeoutMs
260
+ : releaseGitTransferTimeoutMs;
261
+ const maximumAttempts = optionsArg.policy.retryDelaysMs.length + 1;
75
262
  const started = Date.now();
76
263
  for (let attempt = 1; ; attempt++) {
264
+ await optionsArg.beforeAttempt?.();
77
265
  const result = await optionsArg.smartshell.execSpawn(
78
266
  "git",
79
267
  optionsArg.args,
80
268
  {
81
269
  cwd: optionsArg.cwd,
82
270
  env: optionsArg.env,
83
- silent: true,
84
- timeout: optionsArg.policy.timeoutMs,
271
+ // A push shows its progress and the remote's messages; reads stay quiet.
272
+ silent: subcommand !== "push",
273
+ timeout: timeoutMs,
85
274
  timeoutKillGraceMs: 5_000,
86
275
  },
87
276
  );
88
- const transient = isTransientGitRemoteFailure(result);
89
- const retryDelayMs = optionsArg.policy.retryDelaysMs[attempt - 1];
90
- if (!transient || retryDelayMs === undefined) {
91
- return {
277
+ const finish = (
278
+ transientArg: boolean,
279
+ landedArg = false,
280
+ ): { result: IReleaseGitRemoteResult; landed: boolean } => ({
281
+ result: {
92
282
  ...result,
283
+ step: optionsArg.step,
284
+ command,
285
+ timeoutMs,
93
286
  attempts: attempt,
94
287
  elapsedMs: Date.now() - started,
95
- transient,
96
- };
288
+ transient: transientArg,
289
+ },
290
+ landed: landedArg,
291
+ });
292
+ if (result.exitCode === 0) return finish(false);
293
+ const failure = classifyGitRemoteFailure(result, timeoutMs);
294
+ const retryDelayMs = optionsArg.policy.retryDelaysMs[attempt - 1];
295
+ if (!failure.transient || retryDelayMs === undefined) {
296
+ return finish(failure.transient);
97
297
  }
298
+ const failed = `${optionsArg.step}: \`${command}\` failed (${failure.reason}) on attempt ${attempt} of ${maximumAttempts}`;
299
+ if (optionsArg.reinspect) {
300
+ const state = await optionsArg.reinspect();
301
+ if (state === "landed") {
302
+ await logger.log(
303
+ "warn",
304
+ `${failed}, but the remote already holds the pushed refs; the push is done.`,
305
+ );
306
+ return finish(true, true);
307
+ }
308
+ if (state === "unknown") {
309
+ await logger.log(
310
+ "warn",
311
+ `${failed}, and the remote state could not be proven; not pushing again.`,
312
+ );
313
+ return finish(true);
314
+ }
315
+ }
316
+ await logger.log(
317
+ "warn",
318
+ `${failed}${optionsArg.reinspect ? " and the remote does not hold the pushed refs" : ""}; retrying in ${formatSeconds(retryDelayMs)}.`,
319
+ );
98
320
  await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
99
321
  }
100
322
  };
101
323
 
102
- const formatSeconds = (msArg: number): string =>
103
- `${Number((msArg / 1000).toFixed(1))} s`;
324
+ /**
325
+ * Runs an idempotent remote read (`ls-remote`, or a `fetch` for inspection or
326
+ * verification), retrying transient failures. The caller decides what the
327
+ * final answer means; this only makes a flaky remote answer at all.
328
+ */
329
+ export const runGitRemoteRead = async (
330
+ optionsArg: IRunGitRemoteReadOptions,
331
+ ): Promise<IReleaseGitRemoteResult> =>
332
+ (await runGitRemoteCommand(optionsArg)).result;
333
+
334
+ /**
335
+ * Runs a `git push`, which is never repeated blindly: after a transient
336
+ * failure `reinspect` reads the remote. Refs already in place end the push as
337
+ * landed; an unchanged remote is pushed again; anything else stops. The caller
338
+ * still verifies the remote afterwards.
339
+ */
340
+ export const runGitRemotePush = async (
341
+ optionsArg: IRunGitRemotePushOptions,
342
+ ): Promise<IReleaseGitRemotePushResult> => {
343
+ const { result, landed } = await runGitRemoteCommand(optionsArg);
344
+ return { ...result, landed };
345
+ };
104
346
 
105
- /** How the final attempt failed, and how long the inspection kept trying. */
347
+ /** How the final attempt failed, and how long the step kept trying. */
106
348
  export const describeGitRemoteFailure = (
107
349
  resultArg: IReleaseGitRemoteResult,
108
- policyArg: IReleaseGitRemotePolicy,
109
350
  ): string => {
110
351
  const failure = describeCommandFailure(resultArg, {
111
- command: "git ls-remote",
112
- timeoutMs: policyArg.timeoutMs,
352
+ command: resultArg.command,
353
+ timeoutMs: resultArg.timeoutMs,
113
354
  });
114
355
  return resultArg.attempts > 1
115
356
  ? `${failure}; gave up after ${resultArg.attempts} attempts over ${formatSeconds(resultArg.elapsedMs)}`
@@ -117,7 +358,7 @@ export const describeGitRemoteFailure = (
117
358
  };
118
359
 
119
360
  /**
120
- * A remote inspection that failed. The message names the release step, the
361
+ * A remote command that failed. The message names the release step, the
121
362
  * per-attempt bound, the attempts and the time spent; it never carries the
122
363
  * destination URL, whose userinfo the command failure redacts.
123
364
  */
@@ -128,20 +369,15 @@ export class ReleaseGitRemoteError extends Error {
128
369
  public readonly timeoutMs: number;
129
370
  public readonly transient: boolean;
130
371
 
131
- constructor(
132
- messageArg: string,
133
- stepArg: string,
134
- resultArg: IReleaseGitRemoteResult,
135
- policyArg: IReleaseGitRemotePolicy,
136
- ) {
372
+ constructor(messageArg: string, resultArg: IReleaseGitRemoteResult) {
137
373
  super(
138
- `${messageArg} Step: ${stepArg}. ${describeGitRemoteFailure(resultArg, policyArg)}`,
374
+ `${messageArg} Step: ${resultArg.step}. ${describeGitRemoteFailure(resultArg)}`,
139
375
  );
140
376
  this.name = "ReleaseGitRemoteError";
141
- this.step = stepArg;
377
+ this.step = resultArg.step;
142
378
  this.attempts = resultArg.attempts;
143
379
  this.elapsedMs = resultArg.elapsedMs;
144
- this.timeoutMs = policyArg.timeoutMs;
380
+ this.timeoutMs = resultArg.timeoutMs;
145
381
  this.transient = resultArg.transient;
146
382
  }
147
383
  }