@git.zone/cli 7.2.6 → 7.3.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/assets/templates/npm/.package.json +1 -1
- package/assets/templates/service/.package.json +1 -1
- package/assets/templates/wcc/.package.json +1 -1
- package/assets/templates/website/.package.json +1 -1
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/helpers.climode.js +2 -1
- package/dist_ts/helpers.workflow.d.ts +19 -1
- package/dist_ts/helpers.workflow.js +31 -2
- package/dist_ts/mod_config/index.js +18 -2
- package/dist_ts/mod_release/classes.detachedrelease.d.ts +85 -0
- package/dist_ts/mod_release/classes.detachedrelease.js +506 -0
- package/dist_ts/mod_release/classes.releasejournal.d.ts +34 -0
- package/dist_ts/mod_release/classes.releasejournal.js +134 -2
- package/dist_ts/mod_release/helpers.giteaassets.d.ts +19 -0
- package/dist_ts/mod_release/helpers.giteaassets.js +53 -4
- package/dist_ts/mod_release/helpers.gitremote.d.ts +52 -0
- package/dist_ts/mod_release/helpers.gitremote.js +87 -0
- package/dist_ts/mod_release/helpers.releasebranch.d.ts +5 -0
- package/dist_ts/mod_release/helpers.releasebranch.js +39 -15
- package/dist_ts/mod_release/helpers.releasepreparation.js +18 -8
- package/dist_ts/mod_release/helpers.releasepublication.d.ts +3 -0
- package/dist_ts/mod_release/helpers.releasepublication.js +19 -15
- package/dist_ts/mod_release/index.js +303 -66
- package/dist_ts/mod_services/classes.interprocesslock.d.ts +12 -0
- package/dist_ts/mod_services/classes.interprocesslock.js +35 -12
- package/dist_ts/paths.d.ts +6 -0
- package/dist_ts/paths.js +7 -1
- package/package.json +4 -4
- package/readme.md +158 -21
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/helpers.climode.ts +1 -0
- package/ts/helpers.workflow.ts +50 -0
- package/ts/mod_config/index.ts +19 -0
- package/ts/mod_release/classes.detachedrelease.ts +655 -0
- package/ts/mod_release/classes.releasejournal.ts +181 -1
- package/ts/mod_release/helpers.giteaassets.ts +67 -5
- package/ts/mod_release/helpers.gitremote.ts +147 -0
- package/ts/mod_release/helpers.releasebranch.ts +75 -30
- package/ts/mod_release/helpers.releasepreparation.ts +25 -7
- package/ts/mod_release/helpers.releasepublication.ts +27 -36
- package/ts/mod_release/index.ts +443 -87
- package/ts/mod_services/classes.interprocesslock.ts +44 -15
- package/ts/paths.ts +10 -0
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import * as plugins from "./mod.plugins.js";
|
|
2
2
|
import { formatCommandFailure } from "./helpers.commandfailure.js";
|
|
3
3
|
import { InterProcessLock } from "../mod_services/classes.interprocesslock.js";
|
|
4
|
-
import {
|
|
4
|
+
import {
|
|
5
|
+
resolveGiteaAssetsConfiguration,
|
|
6
|
+
type TReleaseRecordedPlan,
|
|
7
|
+
type TReleaseTarget,
|
|
8
|
+
} from "../helpers.workflow.js";
|
|
5
9
|
import {
|
|
6
10
|
assertGiteaFrozenAssets,
|
|
7
11
|
validateGiteaAssets,
|
|
@@ -33,6 +37,7 @@ export const legacyReleaseJournalSchemaVersion = 1 as const;
|
|
|
33
37
|
export const releaseJournalSchemaVersion = 2 as const;
|
|
34
38
|
export const releaseArtifactFileName = "package.tgz" as const;
|
|
35
39
|
export const releaseJournalFileName = "journal.json" as const;
|
|
40
|
+
export const releaseIntentKind = "gitzone-release-intent" as const;
|
|
36
41
|
|
|
37
42
|
/**
|
|
38
43
|
* `accepted` records a destination that took the upload without rejecting it
|
|
@@ -1724,6 +1729,106 @@ const assertSchema4AppendOnlyTransition = (
|
|
|
1724
1729
|
}
|
|
1725
1730
|
};
|
|
1726
1731
|
|
|
1732
|
+
/** The Git destination state a recorded release leases when it publishes. */
|
|
1733
|
+
export interface IReleaseIntentGit {
|
|
1734
|
+
remote: string;
|
|
1735
|
+
destinationHash: string;
|
|
1736
|
+
expectedRemoteMainOid: string;
|
|
1737
|
+
}
|
|
1738
|
+
|
|
1739
|
+
/**
|
|
1740
|
+
* What a release settled before it prepared its journal: its local commit and
|
|
1741
|
+
* tag, the Git destination state it leases, and the command-line choices that
|
|
1742
|
+
* shaped it. It is recorded as soon as the tag exists, so a failure before the
|
|
1743
|
+
* journal is installed resumes from the release commit instead of stranding
|
|
1744
|
+
* it. The installed journal supersedes it.
|
|
1745
|
+
*/
|
|
1746
|
+
export interface IReleaseIntent {
|
|
1747
|
+
kind: typeof releaseIntentKind;
|
|
1748
|
+
release: IReleaseIdentity;
|
|
1749
|
+
plan: TReleaseRecordedPlan;
|
|
1750
|
+
git: IReleaseIntentGit | null;
|
|
1751
|
+
createdAt: string;
|
|
1752
|
+
}
|
|
1753
|
+
|
|
1754
|
+
const releaseTargets: readonly TReleaseTarget[] = [
|
|
1755
|
+
"git",
|
|
1756
|
+
"giteaAssets",
|
|
1757
|
+
"npm",
|
|
1758
|
+
"docker",
|
|
1759
|
+
];
|
|
1760
|
+
|
|
1761
|
+
const assertReleaseIntentPlan = (valueArg: unknown): TReleaseRecordedPlan => {
|
|
1762
|
+
if (!isPlainObject(valueArg)) {
|
|
1763
|
+
throw new Error("Release intent plan must be an object.");
|
|
1764
|
+
}
|
|
1765
|
+
assertExactKeys(valueArg, ["targets", "runBuild"], "Release intent plan");
|
|
1766
|
+
const targets = valueArg.targets;
|
|
1767
|
+
if (
|
|
1768
|
+
!Array.isArray(targets) ||
|
|
1769
|
+
typeof valueArg.runBuild !== "boolean" ||
|
|
1770
|
+
targets.some(
|
|
1771
|
+
(targetArg, indexArg) =>
|
|
1772
|
+
!releaseTargets.includes(targetArg) ||
|
|
1773
|
+
(indexArg > 0 &&
|
|
1774
|
+
releaseTargets.indexOf(targets[indexArg - 1]) >=
|
|
1775
|
+
releaseTargets.indexOf(targetArg)),
|
|
1776
|
+
)
|
|
1777
|
+
) {
|
|
1778
|
+
throw new Error(
|
|
1779
|
+
"Release intent plan must name unique release targets in canonical order.",
|
|
1780
|
+
);
|
|
1781
|
+
}
|
|
1782
|
+
return valueArg as unknown as TReleaseRecordedPlan;
|
|
1783
|
+
};
|
|
1784
|
+
|
|
1785
|
+
const assertReleaseIntentGit = (valueArg: unknown): IReleaseIntentGit | null => {
|
|
1786
|
+
if (valueArg === null) return null;
|
|
1787
|
+
if (!isPlainObject(valueArg)) {
|
|
1788
|
+
throw new Error("Release intent Git destination must be an object or null.");
|
|
1789
|
+
}
|
|
1790
|
+
assertExactKeys(
|
|
1791
|
+
valueArg,
|
|
1792
|
+
["remote", "destinationHash", "expectedRemoteMainOid"],
|
|
1793
|
+
"Release intent Git destination",
|
|
1794
|
+
);
|
|
1795
|
+
if (
|
|
1796
|
+
typeof valueArg.remote !== "string" ||
|
|
1797
|
+
normalizeReleaseGitRemoteName(valueArg.remote) !== valueArg.remote ||
|
|
1798
|
+
typeof valueArg.destinationHash !== "string" ||
|
|
1799
|
+
!sha256Regex.test(valueArg.destinationHash) ||
|
|
1800
|
+
typeof valueArg.expectedRemoteMainOid !== "string" ||
|
|
1801
|
+
!gitOidRegex.test(valueArg.expectedRemoteMainOid)
|
|
1802
|
+
) {
|
|
1803
|
+
throw new Error("Release intent Git destination data is invalid.");
|
|
1804
|
+
}
|
|
1805
|
+
return valueArg as unknown as IReleaseIntentGit;
|
|
1806
|
+
};
|
|
1807
|
+
|
|
1808
|
+
export const assertReleaseIntent = (valueArg: unknown): IReleaseIntent => {
|
|
1809
|
+
if (!isPlainObject(valueArg)) {
|
|
1810
|
+
throw new Error("Release intent root must be a JSON object.");
|
|
1811
|
+
}
|
|
1812
|
+
assertExactKeys(
|
|
1813
|
+
valueArg,
|
|
1814
|
+
["kind", "release", "plan", "git", "createdAt"],
|
|
1815
|
+
"Release intent",
|
|
1816
|
+
);
|
|
1817
|
+
if (valueArg.kind !== releaseIntentKind) {
|
|
1818
|
+
throw new Error("Release intent kind is invalid.");
|
|
1819
|
+
}
|
|
1820
|
+
assertReleaseIdentity(valueArg.release);
|
|
1821
|
+
const plan = assertReleaseIntentPlan(valueArg.plan);
|
|
1822
|
+
const git = assertReleaseIntentGit(valueArg.git);
|
|
1823
|
+
if (plan.targets.includes("git") !== (git !== null)) {
|
|
1824
|
+
throw new Error(
|
|
1825
|
+
"A release intent records a Git destination exactly when Git is a target.",
|
|
1826
|
+
);
|
|
1827
|
+
}
|
|
1828
|
+
assertIsoTimestamp(valueArg.createdAt, "Release intent createdAt");
|
|
1829
|
+
return valueArg as unknown as IReleaseIntent;
|
|
1830
|
+
};
|
|
1831
|
+
|
|
1727
1832
|
export const createReleaseAttempt = (): IReleaseAttempt => ({
|
|
1728
1833
|
id: plugins.crypto.randomBytes(16).toString("hex"),
|
|
1729
1834
|
pid: process.pid,
|
|
@@ -1815,6 +1920,77 @@ export class ReleaseJournalStore {
|
|
|
1815
1920
|
);
|
|
1816
1921
|
}
|
|
1817
1922
|
|
|
1923
|
+
/** Beside the release directory, so installing the journal never meets it. */
|
|
1924
|
+
public getIntentPath(versionArg: string): string {
|
|
1925
|
+
return `${this.getReleaseDirectory(versionArg)}.intent.json`;
|
|
1926
|
+
}
|
|
1927
|
+
|
|
1928
|
+
public async hasJournal(versionArg: string): Promise<boolean> {
|
|
1929
|
+
try {
|
|
1930
|
+
await plugins.fs.lstat(this.getReleaseDirectory(versionArg));
|
|
1931
|
+
return true;
|
|
1932
|
+
} catch (error) {
|
|
1933
|
+
if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
|
|
1934
|
+
throw error;
|
|
1935
|
+
}
|
|
1936
|
+
}
|
|
1937
|
+
|
|
1938
|
+
/**
|
|
1939
|
+
* Records the intent atomically. A fresh release just created its tag, so
|
|
1940
|
+
* an intent left behind by an earlier, unwound attempt at this version no
|
|
1941
|
+
* longer names an existing tag and is replaced.
|
|
1942
|
+
*/
|
|
1943
|
+
public async recordIntent(intentArg: IReleaseIntent): Promise<void> {
|
|
1944
|
+
const intent = assertReleaseIntent(intentArg);
|
|
1945
|
+
await plugins.fs.mkdir(this.rootPath, { recursive: true, mode: 0o700 });
|
|
1946
|
+
const intentPath = this.getIntentPath(intent.release.version);
|
|
1947
|
+
const temporaryPath = `${intentPath}.tmp-${process.pid}-${plugins.crypto.randomBytes(12).toString("hex")}`;
|
|
1948
|
+
try {
|
|
1949
|
+
const handle = await plugins.fs.open(temporaryPath, "wx", 0o600);
|
|
1950
|
+
try {
|
|
1951
|
+
await handle.writeFile(`${JSON.stringify(intent, null, 2)}\n`, "utf8");
|
|
1952
|
+
await handle.sync();
|
|
1953
|
+
} finally {
|
|
1954
|
+
await handle.close();
|
|
1955
|
+
}
|
|
1956
|
+
await plugins.fs.rename(temporaryPath, intentPath);
|
|
1957
|
+
await syncDirectory(this.rootPath);
|
|
1958
|
+
} catch (error) {
|
|
1959
|
+
await plugins.fs.rm(temporaryPath, { force: true });
|
|
1960
|
+
throw new Error(
|
|
1961
|
+
`Release intent v${intent.release.version} could not be recorded.`,
|
|
1962
|
+
{ cause: error },
|
|
1963
|
+
);
|
|
1964
|
+
}
|
|
1965
|
+
}
|
|
1966
|
+
|
|
1967
|
+
/** The recorded intent of a release without an installed journal, if any. */
|
|
1968
|
+
public async readIntent(versionArg: string): Promise<IReleaseIntent | null> {
|
|
1969
|
+
const version = normalizeReleaseVersion(versionArg);
|
|
1970
|
+
let content: string;
|
|
1971
|
+
try {
|
|
1972
|
+
content = await plugins.fs.readFile(this.getIntentPath(version), "utf8");
|
|
1973
|
+
} catch (error) {
|
|
1974
|
+
if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
|
|
1975
|
+
throw new Error(`Release intent v${version} could not be read.`, {
|
|
1976
|
+
cause: error,
|
|
1977
|
+
});
|
|
1978
|
+
}
|
|
1979
|
+
let parsed: unknown;
|
|
1980
|
+
try {
|
|
1981
|
+
parsed = JSON.parse(content);
|
|
1982
|
+
} catch (error) {
|
|
1983
|
+
throw new Error(`Release intent v${version} is not valid JSON.`, {
|
|
1984
|
+
cause: error,
|
|
1985
|
+
});
|
|
1986
|
+
}
|
|
1987
|
+
const intent = assertReleaseIntent(parsed);
|
|
1988
|
+
if (intent.release.version !== version) {
|
|
1989
|
+
throw new Error("Release intent path and version do not match.");
|
|
1990
|
+
}
|
|
1991
|
+
return intent;
|
|
1992
|
+
}
|
|
1993
|
+
|
|
1818
1994
|
public async read(versionArg: string): Promise<TReleaseJournal> {
|
|
1819
1995
|
const version = normalizeReleaseVersion(versionArg);
|
|
1820
1996
|
const filePath = plugins.path.join(
|
|
@@ -2014,6 +2190,10 @@ export class ReleaseJournalStore {
|
|
|
2014
2190
|
}
|
|
2015
2191
|
await syncDirectory(temporaryDirectory);
|
|
2016
2192
|
await plugins.fs.rename(temporaryDirectory, releaseDirectory);
|
|
2193
|
+
// The journal now owns the release; its intent is superseded.
|
|
2194
|
+
await plugins.fs.rm(this.getIntentPath(journal.release.version), {
|
|
2195
|
+
force: true,
|
|
2196
|
+
});
|
|
2017
2197
|
await syncDirectory(this.rootPath);
|
|
2018
2198
|
return journal;
|
|
2019
2199
|
});
|
|
@@ -34,6 +34,50 @@ class GiteaAssetHttpError extends Error {
|
|
|
34
34
|
}
|
|
35
35
|
}
|
|
36
36
|
|
|
37
|
+
/**
|
|
38
|
+
* A request ended for a reason that proves neither success nor conflict. The
|
|
39
|
+
* message carries a sanitized cause and never a URL, header, body or token.
|
|
40
|
+
*/
|
|
41
|
+
export class GiteaAssetInconclusiveError extends Error {
|
|
42
|
+
constructor(message: string) {
|
|
43
|
+
super(message);
|
|
44
|
+
this.name = "GiteaAssetInconclusiveError";
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const safeErrorName = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
|
|
49
|
+
const safeErrorCode = /^[A-Z][A-Z0-9_]{1,63}$/;
|
|
50
|
+
/** Plain words only: no digit, colon, slash or dot inside can carry a URL or token. */
|
|
51
|
+
const safeErrorMessage = /^[A-Za-z][A-Za-z ]{0,79}\.?$/;
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Names why a request ended: the HTTP status it reached, each error of the
|
|
55
|
+
* cause chain by name and code, its message only when it is plain words
|
|
56
|
+
* ("terminated", "fetch failed", "other side closed"), and how far the
|
|
57
|
+
* transfer got.
|
|
58
|
+
*/
|
|
59
|
+
export const describeGiteaRequestFailure = (
|
|
60
|
+
error: unknown,
|
|
61
|
+
evidence: { status?: number; progress: string },
|
|
62
|
+
): string => {
|
|
63
|
+
const parts: string[] = [];
|
|
64
|
+
if (evidence.status !== undefined) parts.push(`HTTP ${evidence.status}`);
|
|
65
|
+
let current = error;
|
|
66
|
+
for (let depth = 0; depth < 4 && current instanceof Error; depth++) {
|
|
67
|
+
const name = safeErrorName.test(current.name) ? current.name : "Error";
|
|
68
|
+
const code = (current as NodeJS.ErrnoException).code;
|
|
69
|
+
const codeText =
|
|
70
|
+
typeof code === "string" && safeErrorCode.test(code) ? ` [${code}]` : "";
|
|
71
|
+
const messageText = safeErrorMessage.test(current.message)
|
|
72
|
+
? `: ${current.message}`
|
|
73
|
+
: "";
|
|
74
|
+
parts.push(`${name}${codeText}${messageText}`);
|
|
75
|
+
current = current.cause;
|
|
76
|
+
}
|
|
77
|
+
parts.push(evidence.progress);
|
|
78
|
+
return `(${parts.join("; ")})`;
|
|
79
|
+
};
|
|
80
|
+
|
|
37
81
|
export const defaultGiteaAssetTransferLimits: Readonly<IGiteaAssetTransferLimits> =
|
|
38
82
|
Object.freeze({
|
|
39
83
|
responseTimeoutMs: 2 * 60_000,
|
|
@@ -193,6 +237,11 @@ export class GiteaTransferWatchdog {
|
|
|
193
237
|
return this.#failure;
|
|
194
238
|
}
|
|
195
239
|
|
|
240
|
+
/** Bytes sent and received so far. */
|
|
241
|
+
get bytes(): number {
|
|
242
|
+
return this.#bytes;
|
|
243
|
+
}
|
|
244
|
+
|
|
196
245
|
/** Wait for response headers; every redirect hop starts a new wait. */
|
|
197
246
|
awaitResponse(): void {
|
|
198
247
|
this.#arm("response");
|
|
@@ -765,8 +814,14 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
|
|
|
765
814
|
// Never include response text, fetch errors, URLs or causes that can expose the token.
|
|
766
815
|
if (watchdog.failure) throw watchdog.failure;
|
|
767
816
|
if (error instanceof GiteaAssetHttpError) throw error;
|
|
768
|
-
throw new
|
|
769
|
-
`Gitea asset ${method} result is inconclusive
|
|
817
|
+
throw new GiteaAssetInconclusiveError(
|
|
818
|
+
`Gitea asset ${method} result is inconclusive ${describeGiteaRequestFailure(
|
|
819
|
+
error,
|
|
820
|
+
{
|
|
821
|
+
status: response?.status,
|
|
822
|
+
progress: `${watchdog.bytes} bytes transferred`,
|
|
823
|
+
},
|
|
824
|
+
)}; inspect the retained release before another mutation.`,
|
|
770
825
|
);
|
|
771
826
|
} finally {
|
|
772
827
|
watchdog.close();
|
|
@@ -993,6 +1048,9 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
|
|
|
993
1048
|
asset.size,
|
|
994
1049
|
);
|
|
995
1050
|
let response: Response | undefined;
|
|
1051
|
+
/** Status of the response the failure followed; a redirect hop resets it. */
|
|
1052
|
+
let status: number | undefined;
|
|
1053
|
+
let size = 0;
|
|
996
1054
|
try {
|
|
997
1055
|
let url = new URL(asset.publicUrl);
|
|
998
1056
|
for (let redirects = 0; ; redirects++) {
|
|
@@ -1004,11 +1062,13 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
|
|
|
1004
1062
|
)
|
|
1005
1063
|
throw new GiteaAssetConflictError("Unsafe anonymous asset redirect.");
|
|
1006
1064
|
watchdog.awaitResponse();
|
|
1065
|
+
status = undefined;
|
|
1007
1066
|
response = await this.fetchImplementation(url.href, {
|
|
1008
1067
|
redirect: "manual",
|
|
1009
1068
|
signal: watchdog.signal,
|
|
1010
1069
|
headers: { "Accept-Encoding": "identity" },
|
|
1011
1070
|
});
|
|
1071
|
+
status = response.status;
|
|
1012
1072
|
watchdog.progress("received", 0);
|
|
1013
1073
|
if (![301, 302, 303, 307, 308].includes(response.status)) break;
|
|
1014
1074
|
if (redirects >= 5 || !response.headers.get("location"))
|
|
@@ -1032,7 +1092,6 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
|
|
|
1032
1092
|
)
|
|
1033
1093
|
throw new GiteaAssetConflictError("Anonymous asset size mismatch.");
|
|
1034
1094
|
const hash = plugins.crypto.createHash("sha256");
|
|
1035
|
-
let size = 0;
|
|
1036
1095
|
const reader = response.body.getReader();
|
|
1037
1096
|
try {
|
|
1038
1097
|
while (true) {
|
|
@@ -1055,8 +1114,11 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
|
|
|
1055
1114
|
} catch (error) {
|
|
1056
1115
|
if (watchdog.failure) throw watchdog.failure;
|
|
1057
1116
|
if (error instanceof GiteaAssetConflictError) throw error;
|
|
1058
|
-
throw new
|
|
1059
|
-
|
|
1117
|
+
throw new GiteaAssetInconclusiveError(
|
|
1118
|
+
`Gitea public asset verification is inconclusive ${describeGiteaRequestFailure(
|
|
1119
|
+
error,
|
|
1120
|
+
{ status, progress: `${size} of ${asset.size} bytes received` },
|
|
1121
|
+
)}; inspect availability before publication.`,
|
|
1060
1122
|
);
|
|
1061
1123
|
} finally {
|
|
1062
1124
|
watchdog.close();
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
import * as plugins from "./mod.plugins.js";
|
|
2
|
+
import { describeCommandFailure } from "./helpers.commandfailure.js";
|
|
3
|
+
|
|
4
|
+
/** Bound of one `git ls-remote` attempt unless `release.targets.git.remoteTimeoutSeconds` sets it. */
|
|
5
|
+
export const defaultReleaseGitRemoteTimeoutSeconds = 180;
|
|
6
|
+
export const maximumReleaseGitRemoteTimeoutSeconds = 3600;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* 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.
|
|
11
|
+
*/
|
|
12
|
+
export interface IReleaseGitRemotePolicy {
|
|
13
|
+
/** Bound of one attempt. */
|
|
14
|
+
timeoutMs: number;
|
|
15
|
+
/** Wait before each retry; its length is the number of retries. */
|
|
16
|
+
retryDelaysMs: readonly number[];
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Two retries, 5 s and 20 s apart: three attempts in all. */
|
|
20
|
+
const defaultRetryDelaysMs: readonly number[] = [5_000, 20_000];
|
|
21
|
+
|
|
22
|
+
export const createReleaseGitRemotePolicy = (
|
|
23
|
+
timeoutSecondsArg: number = defaultReleaseGitRemoteTimeoutSeconds,
|
|
24
|
+
): IReleaseGitRemotePolicy => ({
|
|
25
|
+
timeoutMs: timeoutSecondsArg * 1000,
|
|
26
|
+
retryDelaysMs: defaultRetryDelaysMs,
|
|
27
|
+
});
|
|
28
|
+
|
|
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;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
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.
|
|
41
|
+
*/
|
|
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;
|
|
46
|
+
|
|
47
|
+
export const isTransientGitRemoteFailure = (
|
|
48
|
+
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)
|
|
55
|
+
);
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
export interface IRunGitRemoteInspectionOptions {
|
|
59
|
+
smartshell: plugins.smartshell.Smartshell;
|
|
60
|
+
cwd: string;
|
|
61
|
+
/** `ls-remote` arguments, starting with `ls-remote`. */
|
|
62
|
+
args: string[];
|
|
63
|
+
env: NodeJS.ProcessEnv;
|
|
64
|
+
policy: IReleaseGitRemotePolicy;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
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.
|
|
71
|
+
*/
|
|
72
|
+
export const runGitRemoteInspection = async (
|
|
73
|
+
optionsArg: IRunGitRemoteInspectionOptions,
|
|
74
|
+
): Promise<IReleaseGitRemoteResult> => {
|
|
75
|
+
const started = Date.now();
|
|
76
|
+
for (let attempt = 1; ; attempt++) {
|
|
77
|
+
const result = await optionsArg.smartshell.execSpawn(
|
|
78
|
+
"git",
|
|
79
|
+
optionsArg.args,
|
|
80
|
+
{
|
|
81
|
+
cwd: optionsArg.cwd,
|
|
82
|
+
env: optionsArg.env,
|
|
83
|
+
silent: true,
|
|
84
|
+
timeout: optionsArg.policy.timeoutMs,
|
|
85
|
+
timeoutKillGraceMs: 5_000,
|
|
86
|
+
},
|
|
87
|
+
);
|
|
88
|
+
const transient = isTransientGitRemoteFailure(result);
|
|
89
|
+
const retryDelayMs = optionsArg.policy.retryDelaysMs[attempt - 1];
|
|
90
|
+
if (!transient || retryDelayMs === undefined) {
|
|
91
|
+
return {
|
|
92
|
+
...result,
|
|
93
|
+
attempts: attempt,
|
|
94
|
+
elapsedMs: Date.now() - started,
|
|
95
|
+
transient,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
|
|
99
|
+
}
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
const formatSeconds = (msArg: number): string =>
|
|
103
|
+
`${Number((msArg / 1000).toFixed(1))} s`;
|
|
104
|
+
|
|
105
|
+
/** How the final attempt failed, and how long the inspection kept trying. */
|
|
106
|
+
export const describeGitRemoteFailure = (
|
|
107
|
+
resultArg: IReleaseGitRemoteResult,
|
|
108
|
+
policyArg: IReleaseGitRemotePolicy,
|
|
109
|
+
): string => {
|
|
110
|
+
const failure = describeCommandFailure(resultArg, {
|
|
111
|
+
command: "git ls-remote",
|
|
112
|
+
timeoutMs: policyArg.timeoutMs,
|
|
113
|
+
});
|
|
114
|
+
return resultArg.attempts > 1
|
|
115
|
+
? `${failure}; gave up after ${resultArg.attempts} attempts over ${formatSeconds(resultArg.elapsedMs)}`
|
|
116
|
+
: failure;
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* A remote inspection that failed. The message names the release step, the
|
|
121
|
+
* per-attempt bound, the attempts and the time spent; it never carries the
|
|
122
|
+
* destination URL, whose userinfo the command failure redacts.
|
|
123
|
+
*/
|
|
124
|
+
export class ReleaseGitRemoteError extends Error {
|
|
125
|
+
public readonly step: string;
|
|
126
|
+
public readonly attempts: number;
|
|
127
|
+
public readonly elapsedMs: number;
|
|
128
|
+
public readonly timeoutMs: number;
|
|
129
|
+
public readonly transient: boolean;
|
|
130
|
+
|
|
131
|
+
constructor(
|
|
132
|
+
messageArg: string,
|
|
133
|
+
stepArg: string,
|
|
134
|
+
resultArg: IReleaseGitRemoteResult,
|
|
135
|
+
policyArg: IReleaseGitRemotePolicy,
|
|
136
|
+
) {
|
|
137
|
+
super(
|
|
138
|
+
`${messageArg} Step: ${stepArg}. ${describeGitRemoteFailure(resultArg, policyArg)}`,
|
|
139
|
+
);
|
|
140
|
+
this.name = "ReleaseGitRemoteError";
|
|
141
|
+
this.step = stepArg;
|
|
142
|
+
this.attempts = resultArg.attempts;
|
|
143
|
+
this.elapsedMs = resultArg.elapsedMs;
|
|
144
|
+
this.timeoutMs = policyArg.timeoutMs;
|
|
145
|
+
this.transient = resultArg.transient;
|
|
146
|
+
}
|
|
147
|
+
}
|