@git.zone/cli 8.5.0 → 8.5.1

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.
@@ -89,10 +89,11 @@ export interface IReleaseGiteaAssetsTargetConfig {
89
89
  /** Rate floor that bounds a whole transfer by its size; default 256. */
90
90
  minimumKiBPerSecond?: number;
91
91
  /**
92
- * Attachments published at the same time, largest first; default 2, at most
93
- * 6. The order is safe because the release stays a draft, invisible to the
94
- * public, until the complete set verified. Uploads into a release an older
95
- * gitzone already published run one at a time in manifest order instead.
92
+ * Attachments of a draft in progress at the same time, largest first;
93
+ * default 1, at most 2. Uploads never overlap and neither do verification
94
+ * downloads: with 2 the next attachment uploads while the previous one is
95
+ * verified. Uploads into an already published release run one at a time in
96
+ * manifest order.
96
97
  */
97
98
  concurrency?: number;
98
99
  }
@@ -199,7 +200,7 @@ export const resolveGiteaAssetTransferLimits = (
199
200
  });
200
201
 
201
202
  /**
202
- * How many attachments a release publishes at the same time. Like the
203
+ * How many attachments of a draft are in progress at the same time. Like the
203
204
  * transfer bounds this is tuning, not identity: it may change between resumes.
204
205
  */
205
206
  export const resolveGiteaAssetConcurrency = (
@@ -335,7 +336,7 @@ export interface IResolvedReleaseWorkflow {
335
336
  npmVerificationWindowMinutes: number;
336
337
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
337
338
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
338
- /** Attachments published at the same time. */
339
+ /** Attachments of a draft in progress at the same time. */
339
340
  giteaAssetConcurrency?: number;
340
341
  dockerEnabled: boolean;
341
342
  dockerEngine: "tsdocker";
@@ -1970,7 +1970,7 @@ async function validateReleaseConfig(
1970
1970
  const concurrency = resolveGiteaAssetConcurrency(targets.giteaAssets);
1971
1971
  findings.push({
1972
1972
  level: "ok",
1973
- message: `Gitea asset transfers wait ${transfer.responseTimeoutMs / 1000} s for a response, fail after ${transfer.stallTimeoutMs / 1000} s without progress, and must average at least ${transfer.minimumBytesPerSecond / 1024} KiB/s each; ${concurrency} run at the same time, so the link must carry ${(concurrency * transfer.minimumBytesPerSecond) / 1024} KiB/s`,
1973
+ message: `Gitea asset transfers wait ${transfer.responseTimeoutMs / 1000} s for a response, fail after ${transfer.stallTimeoutMs / 1000} s without progress, and must average at least ${transfer.minimumBytesPerSecond / 1024} KiB/s each; ${concurrency === 1 ? "one attachment at a time" : "an upload overlaps the previous attachment's verification download"}, never two uploads or two downloads, so each direction of the link must carry ${transfer.minimumBytesPerSecond / 1024} KiB/s`,
1974
1974
  });
1975
1975
  if (targets.git?.enabled === false || targets.docker?.enabled === true)
1976
1976
  throw new Error(
@@ -45,6 +45,31 @@ export class GiteaAssetInconclusiveError extends Error {
45
45
  }
46
46
  }
47
47
 
48
+ /**
49
+ * The release left the draft state the attachments were being uploaded for,
50
+ * for example because something other than this release published it. No
51
+ * further attachment starts; `gitzone release resume` reads the release again
52
+ * and continues a published release one attachment at a time in manifest order.
53
+ */
54
+ export class GiteaReleaseStateChangedError extends Error {
55
+ constructor(message: string) {
56
+ super(message);
57
+ this.name = "GiteaReleaseStateChangedError";
58
+ }
59
+ }
60
+
61
+ /**
62
+ * Gitea did not process the pushed release tag within the bound, so the draft
63
+ * was not created: Gitea would publish a draft it found for the tag once it
64
+ * processes the push. Nothing was created; resume waits again.
65
+ */
66
+ export class GiteaTagProcessingTimeoutError extends Error {
67
+ constructor(message: string) {
68
+ super(message);
69
+ this.name = "GiteaTagProcessingTimeoutError";
70
+ }
71
+ }
72
+
48
73
  const safeErrorName = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
49
74
  const safeErrorCode = /^[A-Z][A-Z0-9_]{1,63}$/;
50
75
  /** Plain words only: no digit, colon, slash or dot inside can carry a URL or token. */
@@ -85,15 +110,30 @@ export const defaultGiteaAssetTransferLimits: Readonly<IGiteaAssetTransferLimits
85
110
  minimumBytesPerSecond: 256 * 1024,
86
111
  });
87
112
 
88
- /** Attachments a release publishes at the same time unless configured otherwise. */
89
- export const defaultGiteaAssetConcurrency = 2;
90
113
  /**
91
- * Upper bound of `release.targets.giteaAssets.concurrency`. Every transfer has
92
- * to hold the rate floor on its own, so N concurrent transfers need N times the
93
- * floor of the link.
114
+ * Attachments a release has in progress at the same time unless configured
115
+ * otherwise: one, so every attachment uploads and verifies alone, as fast as
116
+ * the link allows.
117
+ */
118
+ export const defaultGiteaAssetConcurrency = 1;
119
+ /**
120
+ * Upper bound of `release.targets.giteaAssets.concurrency`. Two transfers in
121
+ * the same direction share the link, so each takes longer than it would alone
122
+ * and a large upload can outlast the reverse proxy's timeout in front of
123
+ * Gitea (HTTP 504). Uploads therefore never overlap, nor do verification
124
+ * downloads; with 2 the next attachment uploads while the previous one is
125
+ * downloaded and hashed, which is the only overlap that does not share a
126
+ * direction. A higher value would add nothing.
94
127
  */
95
- export const maximumGiteaAssetConcurrency = 6;
128
+ export const maximumGiteaAssetConcurrency = 2;
96
129
 
130
+ /**
131
+ * Gitea processes a pushed tag in its push queue, after the push returned;
132
+ * a busy queue has been seen to take more than 90 s.
133
+ */
134
+ export const defaultGiteaTagProcessingTimeoutMs = 15 * 60_000;
135
+ export const defaultGiteaTagProcessingPollIntervalMs = 5_000;
136
+ const maximumTagProcessingTimeoutMs = 6 * 60 * 60_000;
97
137
  const maximumTransferTimeoutMs = 60 * 60_000;
98
138
  const maximumBytesPerSecond = 1024 * 1024 * 1024;
99
139
  /** Node fires longer timers immediately; a ceiling this far out never binds. */
@@ -738,6 +778,8 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
738
778
  readonly #token: string;
739
779
  private readonly fetchImplementation: typeof fetch;
740
780
  private readonly limits: IGiteaAssetTransferLimits;
781
+ private readonly tagProcessingTimeoutMs: number;
782
+ private readonly tagProcessingPollIntervalMs: number;
741
783
  private readonly repositoryApiPath: string;
742
784
  /**
743
785
  * The attachment identity this client downloaded and hashed against each
@@ -771,6 +813,21 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
771
813
  options.minimumBytesPerSecond ??
772
814
  defaultGiteaAssetTransferLimits.minimumBytesPerSecond,
773
815
  });
816
+ this.tagProcessingTimeoutMs =
817
+ options.tagProcessingTimeoutMs ?? defaultGiteaTagProcessingTimeoutMs;
818
+ this.tagProcessingPollIntervalMs =
819
+ options.tagProcessingPollIntervalMs ??
820
+ defaultGiteaTagProcessingPollIntervalMs;
821
+ for (const value of [
822
+ this.tagProcessingTimeoutMs,
823
+ this.tagProcessingPollIntervalMs,
824
+ ])
825
+ if (
826
+ !Number.isSafeInteger(value) ||
827
+ value <= 0 ||
828
+ value > maximumTagProcessingTimeoutMs
829
+ )
830
+ throw new Error("Invalid Gitea tag processing bound.");
774
831
  this.repositoryApiPath = `/repos/${this.destination.owner}/${this.destination.repository}`;
775
832
  }
776
833
 
@@ -1044,8 +1101,94 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1044
1101
  return found;
1045
1102
  }
1046
1103
 
1047
- public async createRelease(): Promise<IGiteaRelease> {
1104
+ /**
1105
+ * The anonymous status of the release's public page. Gitea renders it for a
1106
+ * published release and for the tag-only release row its push queue writes
1107
+ * when it processes a pushed tag, and answers 404 for a draft and for a tag
1108
+ * it has not processed yet. The API never shows a tag-only row.
1109
+ */
1110
+ private async publicReleasePageStatus(): Promise<number> {
1111
+ const watchdog = new GiteaTransferWatchdog(
1112
+ "GET",
1113
+ this.limits,
1114
+ maximumMetadataBytes,
1115
+ );
1116
+ let response: Response | undefined;
1117
+ try {
1118
+ watchdog.awaitResponse();
1119
+ response = await this.fetchImplementation(
1120
+ `${this.destination.apiOrigin}/${this.destination.owner}/${this.destination.repository}/releases/tag/${encodeURIComponent(this.tag)}`,
1121
+ {
1122
+ redirect: "manual",
1123
+ signal: watchdog.signal,
1124
+ headers: { Accept: "text/html" },
1125
+ },
1126
+ );
1127
+ watchdog.progress("received", 0);
1128
+ return response.status;
1129
+ } catch (error) {
1130
+ if (watchdog.failure) throw watchdog.failure;
1131
+ throw new GiteaAssetInconclusiveError(
1132
+ `Gitea release page check is inconclusive ${describeGiteaRequestFailure(
1133
+ error,
1134
+ { status: response?.status, progress: "headers only" },
1135
+ )}; no release was created.`,
1136
+ );
1137
+ } finally {
1138
+ watchdog.close();
1139
+ if (response?.body) await response.body.cancel().catch(() => undefined);
1140
+ }
1141
+ }
1142
+
1143
+ /**
1144
+ * Waits until Gitea has processed the pushed tag. Gitea handles a tag push
1145
+ * in its push queue after the push returned: it writes a tag-only release
1146
+ * row for the tag, or, when a release for the tag already exists, sets
1147
+ * `draft: false` on it (services/repository/push.go, pushUpdateAddTags). A
1148
+ * draft created before that runs is published by Gitea with whatever
1149
+ * attachments it has. Once the tag-only row exists, creating the release
1150
+ * converts that row into the draft in place, and the processed push never
1151
+ * touches it again. The caller has seen no release for the tag through the
1152
+ * API, which hides tag-only rows, so a public page proves the tag-only row.
1153
+ */
1154
+ private async awaitTagProcessed(
1155
+ onWaiting?: (elapsedMs: number) => void,
1156
+ ): Promise<void> {
1157
+ const started = Date.now();
1158
+ let reportedAt: number | undefined;
1159
+ while (true) {
1160
+ const status = await this.publicReleasePageStatus();
1161
+ if (status === 200) return;
1162
+ if (status !== 404)
1163
+ throw new GiteaAssetInconclusiveError(
1164
+ `Gitea release page check is inconclusive (HTTP ${status}); no release was created.`,
1165
+ );
1166
+ const elapsed = Date.now() - started;
1167
+ if (elapsed >= this.tagProcessingTimeoutMs)
1168
+ throw new GiteaTagProcessingTimeoutError(
1169
+ `Gitea has not processed the pushed tag ${this.tag} within ${formatSeconds(elapsed)}; the draft release was not created, because Gitea publishes a draft it finds for the tag once it processes the push. Resume once Gitea shows the tag.`,
1170
+ );
1171
+ if (reportedAt === undefined || elapsed - reportedAt >= 60_000) {
1172
+ reportedAt = elapsed;
1173
+ onWaiting?.(elapsed);
1174
+ }
1175
+ await new Promise<void>((resolve) =>
1176
+ setTimeout(
1177
+ resolve,
1178
+ Math.min(
1179
+ this.tagProcessingPollIntervalMs,
1180
+ this.tagProcessingTimeoutMs - elapsed,
1181
+ ),
1182
+ ),
1183
+ );
1184
+ }
1185
+ }
1186
+
1187
+ public async createRelease(
1188
+ onWaiting?: (elapsedMs: number) => void,
1189
+ ): Promise<IGiteaRelease> {
1048
1190
  await this.admitTag();
1191
+ await this.awaitTagProcessed(onWaiting);
1049
1192
  const result = this.release(
1050
1193
  await this.requestJson(
1051
1194
  `${this.repositoryApiPath}/releases`,
@@ -1088,10 +1231,17 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1088
1231
  public async publishRelease(
1089
1232
  releaseId: number,
1090
1233
  expected: IGiteaFrozenAsset[],
1234
+ expectedDraft: boolean,
1091
1235
  ): Promise<void> {
1092
1236
  positiveId(releaseId);
1093
1237
  const { inspection, attachments, release } =
1094
1238
  await this.inspectAssetsWithIds(releaseId, expected, []);
1239
+ if (release.draft !== expectedDraft)
1240
+ throw new GiteaReleaseStateChangedError(
1241
+ expectedDraft
1242
+ ? `Gitea release ${this.tag} was published before this run verified its complete attachment set.`
1243
+ : `Gitea release ${this.tag} became a draft during publication.`,
1244
+ );
1095
1245
  if (inspection.missing.length !== 0)
1096
1246
  throw new Error(
1097
1247
  "Gitea attachment set is incomplete; the release stays a draft.",
@@ -1456,6 +1606,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1456
1606
  releaseId: number,
1457
1607
  asset: IGiteaFrozenAsset,
1458
1608
  artifactDirectory: string,
1609
+ expectedDraft: boolean,
1459
1610
  ): Promise<void> {
1460
1611
  positiveId(releaseId);
1461
1612
  assertGiteaFrozenAssets([asset], this.destination, this.tag);
@@ -1464,10 +1615,17 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1464
1615
  );
1465
1616
  try {
1466
1617
  await verifyHandle(handle, asset);
1467
- if ((await this.inspectRelease())?.id !== releaseId)
1618
+ const release = await this.inspectRelease();
1619
+ if (release?.id !== releaseId)
1468
1620
  throw new GiteaAssetConflictError(
1469
1621
  "Gitea release identifier changed before upload.",
1470
1622
  );
1623
+ if (release.draft !== expectedDraft)
1624
+ throw new GiteaReleaseStateChangedError(
1625
+ expectedDraft
1626
+ ? `Gitea release ${this.tag} was published while its attachment set was incomplete; ${asset.name} was not uploaded and no further attachment starts.`
1627
+ : `Gitea release ${this.tag} became a draft during publication; ${asset.name} was not uploaded and no further attachment starts.`,
1628
+ );
1471
1629
  // Authenticated: a writer also sees the attachments of a draft.
1472
1630
  const listed = await this.requestJson(
1473
1631
  `${this.repositoryApiPath}/releases/${releaseId}/assets`,
@@ -19,11 +19,13 @@ import {
19
19
  import {
20
20
  GiteaAssetsClient,
21
21
  GiteaAssetConflictError,
22
+ GiteaReleaseStateChangedError,
22
23
  defaultGiteaAssetConcurrency,
23
24
  maximumGiteaAssetConcurrency,
24
25
  validateGiteaAssets,
25
26
  type IGiteaAssetTransferLimits,
26
27
  type IGiteaFrozenAsset,
28
+ type IGiteaRelease,
27
29
  } from "./helpers.giteaassets.js";
28
30
  import {
29
31
  formatReleaseDuration,
@@ -149,7 +151,7 @@ export interface IReleasePublicationOptions {
149
151
  tsdocker?: ITsdockerReleaseClient;
150
152
  /** Transfer bounds for the Gitea client built from the journal's destination. */
151
153
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
152
- /** Attachments published at the same time; default 2. */
154
+ /** Attachments of a draft in progress at the same time (1 or 2); default 1. */
153
155
  giteaAssetConcurrency?: number;
154
156
  /** Bound and retries of the Git target's remote inspection. */
155
157
  gitRemotePolicy?: IReleaseGitRemotePolicy;
@@ -1967,6 +1969,16 @@ export const runBoundedInOrder = async <T>(
1967
1969
  );
1968
1970
  };
1969
1971
 
1972
+ /** Runs the tasks it is given one at a time, in the order they were given. */
1973
+ const createExclusiveSlot = (): (<T>(taskArg: () => Promise<T>) => Promise<T>) => {
1974
+ let tail: Promise<unknown> = Promise.resolve();
1975
+ return <T>(taskArg: () => Promise<T>): Promise<T> => {
1976
+ const run = tail.then(taskArg);
1977
+ tail = run.catch(() => undefined);
1978
+ return run;
1979
+ };
1980
+ };
1981
+
1970
1982
  const resolveGiteaAssetConcurrency = (valueArg: number | undefined): number => {
1971
1983
  const value = valueArg ?? defaultGiteaAssetConcurrency;
1972
1984
  if (
@@ -1990,7 +2002,11 @@ const executeGiteaAssets = async (
1990
2002
  );
1991
2003
  const writer = createReleaseJournalWriter(journalArg);
1992
2004
  let releaseId = journalArg.giteaAssets.release.id;
1993
- let releaseIsDraft = true;
2005
+ const observed: {
2006
+ /** The release as Gitea last reported it; never the state this run intended. */
2007
+ release: IGiteaRelease | null;
2008
+ createdHere: boolean;
2009
+ } = { release: null, createdHere: false };
1994
2010
  printReleasePhase("Gitea release");
1995
2011
  await executeGiteaTarget(
1996
2012
  options,
@@ -2002,40 +2018,67 @@ const executeGiteaAssets = async (
2002
2018
  if (releaseId !== null && release.id !== releaseId)
2003
2019
  throw new GiteaAssetConflictError("Gitea release identity changed.");
2004
2020
  releaseId = release.id;
2005
- releaseIsDraft = release.draft;
2021
+ observed.release = release;
2006
2022
  return true;
2007
2023
  },
2008
2024
  async () => {
2009
- await client.createRelease();
2025
+ observed.createdHere = true;
2026
+ await client.createRelease((elapsedMs) =>
2027
+ printReleasePhase(
2028
+ `Gitea release: waiting for Gitea to process the pushed tag ${journalArg.release.tag} (${formatReleaseDuration(elapsedMs)})`,
2029
+ ),
2030
+ );
2010
2031
  },
2011
2032
  (target) => {
2012
2033
  if ("id" in target) target.id = releaseId;
2013
2034
  },
2014
2035
  );
2015
2036
  const verifiedReleaseId = releaseId;
2016
- if (verifiedReleaseId === null)
2037
+ const release = observed.release;
2038
+ if (verifiedReleaseId === null || release === null)
2017
2039
  throw new Error("Gitea release has no verified identity.");
2040
+ // The draft this run created must read back as a draft; Gitea refusing it
2041
+ // must not turn into a public upload.
2042
+ if (observed.createdHere && !release.draft)
2043
+ throw new GiteaReleaseStateChangedError(
2044
+ `Gitea release ${journalArg.release.tag} was created public instead of as a draft; no attachment was uploaded. A resume continues it as a published release, one attachment at a time in manifest order.`,
2045
+ );
2046
+ const releaseIsDraft = release.draft;
2018
2047
  const journal = requireGiteaJournal(writer.current());
2019
2048
  const expected = journal.giteaAssets.assets.map((entry) => entry.asset);
2020
2049
  const directory = options.store.getReleaseDirectory(journal.release.version);
2021
- // A draft stays invisible until every attachment verified, so no attachment
2022
- // is public before the notices and sources beside it: the largest start
2023
- // first, which shortens the whole publication. A release an older gitzone
2024
- // already published shows every attachment the moment it lands, so its
2025
- // missing attachments upload one at a time in manifest order, sources and
2026
- // notices first, as that gitzone did.
2027
- const order = releaseIsDraft
2028
- ? expected
2029
- .map((asset, index) => ({ asset, index }))
2030
- .sort((a, b) => b.asset.size - a.asset.size || a.index - b.index)
2031
- .map(({ asset }) => asset)
2032
- : expected;
2050
+ // Order and concurrency follow the state Gitea reported. A draft stays
2051
+ // invisible until every attachment verified, so no attachment is public
2052
+ // before the notices and sources beside it, and every upload first checks
2053
+ // that the release is still a draft. Pipelined (concurrency 2), the next
2054
+ // attachment uploads while the previous one is verified, largest first, so
2055
+ // the last verification is a short one; one at a time, attachments go in
2056
+ // manifest order. A published release (one an older gitzone created, or a
2057
+ // draft published before its set was complete) shows every attachment the
2058
+ // moment it lands, so its missing attachments upload one at a time in
2059
+ // manifest order, sources and notices first.
2033
2060
  const effectiveConcurrency = releaseIsDraft ? concurrency : 1;
2061
+ const order =
2062
+ effectiveConcurrency > 1
2063
+ ? expected
2064
+ .map((asset, index) => ({ asset, index }))
2065
+ .sort((a, b) => b.asset.size - a.asset.size || a.index - b.index)
2066
+ .map(({ asset }) => asset)
2067
+ : expected;
2034
2068
  printReleasePhase(
2035
2069
  releaseIsDraft
2036
- ? `Gitea assets: ${expected.length} attachments into the draft, ${effectiveConcurrency} at a time, largest first`
2070
+ ? effectiveConcurrency === 1
2071
+ ? `Gitea assets: ${expected.length} attachments into the draft, one at a time in manifest order`
2072
+ : `Gitea assets: ${expected.length} attachments into the draft, largest first, each uploading while the previous one is verified`
2037
2073
  : `Gitea assets: ${expected.length} attachments into the already published release, one at a time in manifest order`,
2038
2074
  );
2075
+ // Two transfers in the same direction share the link and each takes longer
2076
+ // than alone, long enough for a large upload to outlast the reverse proxy in
2077
+ // front of Gitea (HTTP 504). So uploads never overlap and neither do
2078
+ // verification downloads, whatever the concurrency; only an upload and
2079
+ // another attachment's verification download may run at the same time.
2080
+ const uploadSlot = createExclusiveSlot();
2081
+ const downloadSlot = createExclusiveSlot();
2039
2082
  await runBoundedInOrder(
2040
2083
  order,
2041
2084
  effectiveConcurrency,
@@ -2046,20 +2089,29 @@ const executeGiteaAssets = async (
2046
2089
  writer,
2047
2090
  { kind: "gitea-asset", name: asset.name },
2048
2091
  async (verifyBytes) => {
2049
- const inspection = await client.inspectAssets(
2050
- verifiedReleaseId,
2051
- expected,
2052
- verifyBytes ? [asset] : [],
2092
+ const inspection = await downloadSlot(() =>
2093
+ client.inspectAssets(
2094
+ verifiedReleaseId,
2095
+ expected,
2096
+ verifyBytes ? [asset] : [],
2097
+ ),
2053
2098
  );
2054
2099
  return inspection.present.some((entry) => entry.name === asset.name);
2055
2100
  },
2056
2101
  async () => {
2057
- startedAt = Date.now();
2058
- printReleasePhase(
2059
- `Gitea asset ${asset.name}: uploading ${asset.size} bytes`,
2060
- );
2061
2102
  await validateGiteaAssets(directory, [asset]);
2062
- await client.uploadAsset(verifiedReleaseId, asset, directory);
2103
+ await uploadSlot(async () => {
2104
+ startedAt = Date.now();
2105
+ printReleasePhase(
2106
+ `Gitea asset ${asset.name}: uploading ${asset.size} bytes`,
2107
+ );
2108
+ await client.uploadAsset(
2109
+ verifiedReleaseId,
2110
+ asset,
2111
+ directory,
2112
+ releaseIsDraft,
2113
+ );
2114
+ });
2063
2115
  },
2064
2116
  );
2065
2117
  if (startedAt !== undefined)
@@ -2081,8 +2133,12 @@ const executeGiteaAssets = async (
2081
2133
  // only verified. Setting `draft: false` is idempotent and observable, so
2082
2134
  // it needs no journal attempt: a resume after a crash finds the release
2083
2135
  // published, verifies it and continues.
2084
- printReleasePhase("Gitea release: publishing the verified draft");
2085
- await client.publishRelease(verifiedReleaseId, expected);
2136
+ printReleasePhase(
2137
+ releaseIsDraft
2138
+ ? "Gitea release: publishing the verified draft"
2139
+ : "Gitea release: verifying the already published release",
2140
+ );
2141
+ await client.publishRelease(verifiedReleaseId, expected, releaseIsDraft);
2086
2142
  } catch (error) {
2087
2143
  if (error instanceof GiteaAssetConflictError) {
2088
2144
  await writer.write((current) =>
@@ -57,6 +57,13 @@ export interface IGiteaAssetsClientOptions
57
57
  commit: string;
58
58
  token: string;
59
59
  fetchImplementation?: typeof fetch;
60
+ /**
61
+ * Longest wait for Gitea to process the pushed release tag before the draft
62
+ * is created; default 15 minutes.
63
+ */
64
+ tagProcessingTimeoutMs?: number;
65
+ /** Pause between two checks whether Gitea processed the tag; default 5 s. */
66
+ tagProcessingPollIntervalMs?: number;
60
67
  }
61
68
 
62
69
  export interface IGiteaAssetPreflight {
@@ -68,17 +75,31 @@ export interface IGiteaAssetPreflight {
68
75
  export interface IGiteaAssetsClient {
69
76
  preflight(): Promise<IGiteaAssetPreflight>;
70
77
  inspectRelease(): Promise<IGiteaRelease | null>;
71
- createRelease(): Promise<IGiteaRelease>;
78
+ /**
79
+ * Waits until Gitea has processed the pushed tag, then creates the draft.
80
+ * Gitea processes a tag push asynchronously and publishes any draft it then
81
+ * finds for the tag, so a draft created earlier would turn public on its own.
82
+ * `onWaiting` is called when the wait starts and about once a minute after.
83
+ */
84
+ createRelease(
85
+ onWaiting?: (elapsedMs: number) => void,
86
+ ): Promise<IGiteaRelease>;
72
87
  /** Downloads and hashes only the present attachments named in `verify`. */
73
88
  inspectAssets(
74
89
  releaseId: number,
75
90
  expected: IGiteaFrozenAsset[],
76
91
  verify?: readonly IGiteaFrozenAsset[],
77
92
  ): Promise<IGiteaAssetInspection>;
93
+ /**
94
+ * Uploads one attachment, only while the release is still a draft exactly
95
+ * when `expectedDraft` says so; otherwise a GiteaReleaseStateChangedError
96
+ * stops before any byte is sent.
97
+ */
78
98
  uploadAsset(
79
99
  releaseId: number,
80
100
  asset: IGiteaFrozenAsset,
81
101
  artifactDirectory: string,
102
+ expectedDraft: boolean,
82
103
  ): Promise<void>;
83
104
  /**
84
105
  * The complete set, nothing extra, every frozen identity unchanged. Downloads
@@ -96,9 +117,13 @@ export interface IGiteaAssetsClient {
96
117
  * listed attachment must be the one this client hashed (id and UUID; the id
97
118
  * alone on a server without UUIDs), otherwise a destination conflict leaves
98
119
  * the release a draft. An already published release is only verified.
120
+ * `expectedDraft` is the state the attachments were uploaded for: a draft
121
+ * that something else published meanwhile stops with a
122
+ * GiteaReleaseStateChangedError instead of passing as already published.
99
123
  */
100
124
  publishRelease(
101
125
  releaseId: number,
102
126
  expected: IGiteaFrozenAsset[],
127
+ expectedDraft: boolean,
103
128
  ): Promise<void>;
104
129
  }