@git.zone/cli 8.4.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.
@@ -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,6 +110,30 @@ export const defaultGiteaAssetTransferLimits: Readonly<IGiteaAssetTransferLimits
85
110
  minimumBytesPerSecond: 256 * 1024,
86
111
  });
87
112
 
113
+ /**
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.
127
+ */
128
+ export const maximumGiteaAssetConcurrency = 2;
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;
88
137
  const maximumTransferTimeoutMs = 60 * 60_000;
89
138
  const maximumBytesPerSecond = 1024 * 1024 * 1024;
90
139
  /** Node fires longer timers immediately; a ceiling this far out never binds. */
@@ -715,6 +764,12 @@ export const prepareGiteaAssets = async (
715
764
  return assets;
716
765
  };
717
766
 
767
+ interface IGiteaAttachmentIdentity {
768
+ id: number;
769
+ /** Absent only for a server that does not report attachment UUIDs. */
770
+ uuid: string | undefined;
771
+ }
772
+
718
773
  /** No method retries a remote mutation. The release journal owns attempt admission. */
719
774
  export class GiteaAssetsClient implements IGiteaAssetsClient {
720
775
  private readonly destination: IGiteaAssetDestination;
@@ -723,7 +778,15 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
723
778
  readonly #token: string;
724
779
  private readonly fetchImplementation: typeof fetch;
725
780
  private readonly limits: IGiteaAssetTransferLimits;
781
+ private readonly tagProcessingTimeoutMs: number;
782
+ private readonly tagProcessingPollIntervalMs: number;
726
783
  private readonly repositoryApiPath: string;
784
+ /**
785
+ * The attachment identity this client downloaded and hashed against each
786
+ * frozen asset, by name. Only this process's own downloads count, so a
787
+ * resume, which builds a new client, downloads every attachment again.
788
+ */
789
+ readonly #bytesVerified = new Map<string, IGiteaAttachmentIdentity>();
727
790
 
728
791
  constructor(options: IGiteaAssetsClientOptions) {
729
792
  this.destination = normalizeGiteaAssetDestination(options.destination);
@@ -750,6 +813,21 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
750
813
  options.minimumBytesPerSecond ??
751
814
  defaultGiteaAssetTransferLimits.minimumBytesPerSecond,
752
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.");
753
831
  this.repositoryApiPath = `/repos/${this.destination.owner}/${this.destination.repository}`;
754
832
  }
755
833
 
@@ -757,7 +835,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
757
835
  path: string,
758
836
  authenticated: boolean,
759
837
  options: {
760
- method?: "GET" | "POST";
838
+ method?: "GET" | "POST" | "PATCH";
761
839
  body?: string;
762
840
  /** Streams exactly `size` bytes of the open file; progress means accepted by the transport. */
763
841
  upload?: {
@@ -978,7 +1056,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
978
1056
  const publicUrl = `${this.destination.apiOrigin}/${this.destination.owner}/${this.destination.repository}/releases/tag/${encodeURIComponent(this.tag)}`;
979
1057
  if (
980
1058
  release.tag_name !== this.tag ||
981
- release.draft !== false ||
1059
+ typeof release.draft !== "boolean" ||
982
1060
  release.prerelease !== false ||
983
1061
  release.html_url !== publicUrl ||
984
1062
  release.url !==
@@ -987,7 +1065,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
987
1065
  throw new GiteaAssetConflictError(
988
1066
  "Gitea release identity conflicts with the exact public release.",
989
1067
  );
990
- return { id, tag: this.tag, publicUrl };
1068
+ return { id, tag: this.tag, publicUrl, draft: release.draft };
991
1069
  }
992
1070
 
993
1071
  public async inspectRelease(): Promise<IGiteaRelease | null> {
@@ -998,20 +1076,119 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
998
1076
  });
999
1077
  const anonymous = await this.requestJson(path, false, { allow404: true });
1000
1078
  if (authenticated === null && anonymous === null) return null;
1001
- if (authenticated === null || anonymous === null)
1079
+ if (authenticated === null)
1002
1080
  throw new Error(
1003
1081
  "Gitea release visibility is inconclusive; public and authenticated lookups differ.",
1004
1082
  );
1005
1083
  const found = this.release(authenticated);
1006
- if (this.release(anonymous).id !== found.id)
1084
+ // Gitea shows a draft only to writers.
1085
+ if (found.draft) {
1086
+ if (anonymous !== null)
1087
+ throw new Error(
1088
+ "Gitea release visibility is inconclusive; a draft is publicly visible.",
1089
+ );
1090
+ return found;
1091
+ }
1092
+ if (anonymous === null)
1093
+ throw new Error(
1094
+ "Gitea release visibility is inconclusive; public and authenticated lookups differ.",
1095
+ );
1096
+ const published = this.release(anonymous);
1097
+ if (published.id !== found.id || published.draft)
1007
1098
  throw new GiteaAssetConflictError(
1008
1099
  "Gitea release is not anonymously available with the same identity.",
1009
1100
  );
1010
1101
  return found;
1011
1102
  }
1012
1103
 
1013
- 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> {
1014
1190
  await this.admitTag();
1191
+ await this.awaitTagProcessed(onWaiting);
1015
1192
  const result = this.release(
1016
1193
  await this.requestJson(
1017
1194
  `${this.repositoryApiPath}/releases`,
@@ -1022,7 +1199,8 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1022
1199
  tag_name: this.tag,
1023
1200
  target_commitish: this.commit,
1024
1201
  name: this.tag,
1025
- draft: false,
1202
+ // Nothing is public before every attachment verified; see publishRelease.
1203
+ draft: true,
1026
1204
  prerelease: false,
1027
1205
  }),
1028
1206
  headers: { "Content-Type": "application/json" },
@@ -1041,7 +1219,158 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1041
1219
  return result;
1042
1220
  }
1043
1221
 
1044
- private async verifyPublicBytes(asset: IGiteaFrozenAsset): Promise<void> {
1222
+ /**
1223
+ * Publishes a draft whose complete attachment set verified, then proves the
1224
+ * published release, its attachment set and every attachment's anonymous
1225
+ * download. Every listed attachment must be the one this client hashed, so
1226
+ * call verifyComplete first; anything else stays a draft. Gitea serves a draft's attachments to nobody without write
1227
+ * access, so no attachment was public before this moment. Setting
1228
+ * `draft: false` is idempotent: a release that is already published is only
1229
+ * verified.
1230
+ */
1231
+ public async publishRelease(
1232
+ releaseId: number,
1233
+ expected: IGiteaFrozenAsset[],
1234
+ expectedDraft: boolean,
1235
+ ): Promise<void> {
1236
+ positiveId(releaseId);
1237
+ const { inspection, attachments, release } =
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
+ );
1245
+ if (inspection.missing.length !== 0)
1246
+ throw new Error(
1247
+ "Gitea attachment set is incomplete; the release stays a draft.",
1248
+ );
1249
+ // Only attachments this run hashed may become public: each listed
1250
+ // attachment must be the exact one hashed, by id and UUID. A server that
1251
+ // reports no UUIDs is held to the id alone; its attachments were all
1252
+ // downloaded again by verifyComplete, and Gitea never replaces an
1253
+ // attachment's bytes under its id.
1254
+ for (const asset of expected) {
1255
+ const listed = attachments.get(asset.name);
1256
+ const hashed = this.#bytesVerified.get(asset.name);
1257
+ if (
1258
+ listed === undefined ||
1259
+ hashed === undefined ||
1260
+ listed.id !== hashed.id ||
1261
+ listed.uuid !== hashed.uuid
1262
+ )
1263
+ throw new GiteaAssetConflictError(
1264
+ `Gitea attachment ${asset.name} is not the one this run downloaded and hashed; the release stays ${release.draft ? "a draft" : "as it is"}.`,
1265
+ );
1266
+ }
1267
+ if (release.draft) {
1268
+ const updated = this.release(
1269
+ await this.requestJson(
1270
+ `${this.repositoryApiPath}/releases/${releaseId}`,
1271
+ true,
1272
+ {
1273
+ method: "PATCH",
1274
+ body: JSON.stringify({ draft: false }),
1275
+ headers: { "Content-Type": "application/json" },
1276
+ },
1277
+ ),
1278
+ );
1279
+ if (updated.id !== releaseId || updated.draft)
1280
+ throw new GiteaAssetConflictError(
1281
+ "Published Gitea release identity cannot be verified.",
1282
+ );
1283
+ }
1284
+ const published = await this.inspectRelease();
1285
+ if (!published || published.id !== releaseId || published.draft)
1286
+ throw new Error(
1287
+ "Published Gitea release visibility is inconclusive; inspect before another mutation.",
1288
+ );
1289
+ const anonymousSet = await this.requestJson(
1290
+ `${this.repositoryApiPath}/releases/${releaseId}/assets`,
1291
+ false,
1292
+ );
1293
+ if (!Array.isArray(anonymousSet) || anonymousSet.length !== expected.length)
1294
+ throw new GiteaAssetConflictError(
1295
+ "Published Gitea attachment set differs from the verified set.",
1296
+ );
1297
+ const publicNames = new Set<string>();
1298
+ const publicIds = new Set<number>();
1299
+ for (const value of anonymousSet) {
1300
+ const asset = expected.find((entry) => entry.name === record(value).name);
1301
+ const verified = asset ? attachments.get(asset.name) : undefined;
1302
+ if (!asset || !verified || publicNames.has(asset.name))
1303
+ throw new GiteaAssetConflictError(
1304
+ "Published Gitea attachment set differs from the verified set.",
1305
+ );
1306
+ const identity = this.attachment(value, asset);
1307
+ if (
1308
+ publicIds.has(identity.id) ||
1309
+ identity.id !== verified.id ||
1310
+ identity.uuid !== verified.uuid
1311
+ )
1312
+ throw new GiteaAssetConflictError(
1313
+ "Published Gitea attachment set differs from the verified set.",
1314
+ );
1315
+ publicNames.add(asset.name);
1316
+ publicIds.add(identity.id);
1317
+ }
1318
+ for (const asset of expected) await this.verifyAnonymousAvailability(asset);
1319
+ }
1320
+
1321
+ /**
1322
+ * Requests an attachment's download URL and follows at most five HTTPS
1323
+ * redirects. An authenticated request, which a draft needs, sends the token
1324
+ * only to the configured Gitea origin and never along a redirect elsewhere.
1325
+ */
1326
+ private async openAttachment(
1327
+ asset: IGiteaFrozenAsset,
1328
+ authenticated: boolean,
1329
+ watchdog: GiteaTransferWatchdog,
1330
+ onStatus: (status: number | undefined) => void,
1331
+ ): Promise<Response> {
1332
+ let url = new URL(asset.publicUrl);
1333
+ for (let redirects = 0; ; redirects++) {
1334
+ if (
1335
+ url.protocol !== "https:" ||
1336
+ url.username ||
1337
+ url.password ||
1338
+ url.hash
1339
+ )
1340
+ throw new GiteaAssetConflictError("Unsafe asset download redirect.");
1341
+ watchdog.awaitResponse();
1342
+ onStatus(undefined);
1343
+ const response = await this.fetchImplementation(url.href, {
1344
+ redirect: "manual",
1345
+ signal: watchdog.signal,
1346
+ headers: {
1347
+ "Accept-Encoding": "identity",
1348
+ ...(authenticated && url.origin === this.destination.apiOrigin
1349
+ ? { Authorization: `token ${this.#token}` }
1350
+ : {}),
1351
+ },
1352
+ });
1353
+ onStatus(response.status);
1354
+ watchdog.progress("received", 0);
1355
+ if (![301, 302, 303, 307, 308].includes(response.status))
1356
+ return response;
1357
+ const location = response.headers.get("location");
1358
+ await response.body?.cancel();
1359
+ if (redirects >= 5 || !location)
1360
+ throw new GiteaAssetConflictError("Invalid asset download redirect.");
1361
+ url = new URL(location, url);
1362
+ }
1363
+ }
1364
+
1365
+ /**
1366
+ * Downloads and hashes one attachment. A published release's attachment is
1367
+ * downloaded anonymously; a draft's attachment is not public yet, so it is
1368
+ * downloaded with the token. Both serve the same stored object.
1369
+ */
1370
+ private async verifyAttachmentBytes(
1371
+ asset: IGiteaFrozenAsset,
1372
+ authenticated: boolean,
1373
+ ): Promise<void> {
1045
1374
  const watchdog = new GiteaTransferWatchdog(
1046
1375
  "download",
1047
1376
  this.limits,
@@ -1052,45 +1381,26 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1052
1381
  let status: number | undefined;
1053
1382
  let size = 0;
1054
1383
  try {
1055
- let url = new URL(asset.publicUrl);
1056
- for (let redirects = 0; ; redirects++) {
1057
- if (
1058
- url.protocol !== "https:" ||
1059
- url.username ||
1060
- url.password ||
1061
- url.hash
1062
- )
1063
- throw new GiteaAssetConflictError("Unsafe anonymous asset redirect.");
1064
- watchdog.awaitResponse();
1065
- status = undefined;
1066
- response = await this.fetchImplementation(url.href, {
1067
- redirect: "manual",
1068
- signal: watchdog.signal,
1069
- headers: { "Accept-Encoding": "identity" },
1070
- });
1071
- status = response.status;
1072
- watchdog.progress("received", 0);
1073
- if (![301, 302, 303, 307, 308].includes(response.status)) break;
1074
- if (redirects >= 5 || !response.headers.get("location"))
1075
- throw new GiteaAssetConflictError(
1076
- "Invalid anonymous asset redirect.",
1077
- );
1078
- const next = new URL(response.headers.get("location")!, url);
1079
- await response.body?.cancel();
1080
- url = next;
1081
- }
1384
+ response = await this.openAttachment(
1385
+ asset,
1386
+ authenticated,
1387
+ watchdog,
1388
+ (value) => {
1389
+ status = value;
1390
+ },
1391
+ );
1082
1392
  if (
1083
1393
  response.status !== 200 ||
1084
1394
  !response.body ||
1085
1395
  (response.headers.get("content-encoding") ?? "identity") !== "identity"
1086
1396
  )
1087
- throw new Error("Asset is not anonymously downloadable.");
1397
+ throw new Error("Asset is not downloadable.");
1088
1398
  const length = response.headers.get("content-length");
1089
1399
  if (
1090
1400
  length !== null &&
1091
1401
  (!/^\d+$/.test(length) || Number(length) !== asset.size)
1092
1402
  )
1093
- throw new GiteaAssetConflictError("Anonymous asset size mismatch.");
1403
+ throw new GiteaAssetConflictError("Downloaded asset size mismatch.");
1094
1404
  const hash = plugins.crypto.createHash("sha256");
1095
1405
  const reader = response.body.getReader();
1096
1406
  try {
@@ -1101,7 +1411,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1101
1411
  size += next.value.byteLength;
1102
1412
  if (size > asset.size)
1103
1413
  throw new GiteaAssetConflictError(
1104
- "Anonymous asset exceeds its frozen size.",
1414
+ "Downloaded asset exceeds its frozen size.",
1105
1415
  );
1106
1416
  hash.update(next.value);
1107
1417
  }
@@ -1110,12 +1420,12 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1110
1420
  reader.releaseLock();
1111
1421
  }
1112
1422
  if (size !== asset.size || hash.digest("hex") !== asset.sha256)
1113
- throw new GiteaAssetConflictError("Anonymous asset bytes mismatch.");
1423
+ throw new GiteaAssetConflictError("Downloaded asset bytes mismatch.");
1114
1424
  } catch (error) {
1115
1425
  if (watchdog.failure) throw watchdog.failure;
1116
1426
  if (error instanceof GiteaAssetConflictError) throw error;
1117
1427
  throw new GiteaAssetInconclusiveError(
1118
- `Gitea public asset verification is inconclusive ${describeGiteaRequestFailure(
1428
+ `Gitea ${authenticated ? "draft" : "public"} asset verification is inconclusive ${describeGiteaRequestFailure(
1119
1429
  error,
1120
1430
  { status, progress: `${size} of ${asset.size} bytes received` },
1121
1431
  )}; inspect availability before publication.`,
@@ -1127,42 +1437,122 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1127
1437
  }
1128
1438
  }
1129
1439
 
1130
- private attachment(value: unknown, asset: IGiteaFrozenAsset): number {
1440
+ /**
1441
+ * Proves an attachment of a published release is served anonymously with
1442
+ * its frozen size, without downloading its bytes again: the bytes were
1443
+ * hashed from the same stored object while the release was a draft.
1444
+ */
1445
+ private async verifyAnonymousAvailability(
1446
+ asset: IGiteaFrozenAsset,
1447
+ ): Promise<void> {
1448
+ const watchdog = new GiteaTransferWatchdog(
1449
+ "download",
1450
+ this.limits,
1451
+ maximumMetadataBytes,
1452
+ );
1453
+ let response: Response | undefined;
1454
+ let status: number | undefined;
1455
+ try {
1456
+ response = await this.openAttachment(asset, false, watchdog, (value) => {
1457
+ status = value;
1458
+ });
1459
+ const length = response.headers.get("content-length");
1460
+ if (
1461
+ response.status !== 200 ||
1462
+ (response.headers.get("content-encoding") ?? "identity") !==
1463
+ "identity" ||
1464
+ length === null ||
1465
+ !/^\d+$/.test(length)
1466
+ )
1467
+ throw new Error("Asset is not anonymously downloadable.");
1468
+ if (Number(length) !== asset.size)
1469
+ throw new GiteaAssetConflictError("Anonymous asset size mismatch.");
1470
+ } catch (error) {
1471
+ if (watchdog.failure) throw watchdog.failure;
1472
+ if (error instanceof GiteaAssetConflictError) throw error;
1473
+ throw new GiteaAssetInconclusiveError(
1474
+ `Gitea public asset availability is inconclusive ${describeGiteaRequestFailure(
1475
+ error,
1476
+ { status, progress: "headers only" },
1477
+ )}; inspect the published release.`,
1478
+ );
1479
+ } finally {
1480
+ watchdog.close();
1481
+ if (response?.body) await response.body.cancel().catch(() => undefined);
1482
+ }
1483
+ }
1484
+
1485
+ /**
1486
+ * The attachment's identity once its metadata matches the frozen asset.
1487
+ * Gitea stores an attachment's bytes under its UUID and its API can only
1488
+ * rename an attachment, so an unchanged id and UUID mean unchanged bytes.
1489
+ */
1490
+ private attachment(
1491
+ value: unknown,
1492
+ asset: IGiteaFrozenAsset,
1493
+ ): IGiteaAttachmentIdentity {
1131
1494
  const attachment = record(value);
1132
1495
  const id = positiveId(attachment.id);
1133
1496
  if (
1134
1497
  attachment.name !== asset.name ||
1135
1498
  attachment.size !== asset.size ||
1136
- attachment.browser_download_url !== asset.publicUrl
1499
+ attachment.browser_download_url !== asset.publicUrl ||
1500
+ (attachment.uuid !== undefined && typeof attachment.uuid !== "string")
1137
1501
  )
1138
1502
  throw new GiteaAssetConflictError(
1139
1503
  "Gitea attachment metadata conflicts with the frozen asset.",
1140
1504
  );
1141
- return id;
1505
+ return {
1506
+ id,
1507
+ uuid: typeof attachment.uuid === "string" ? attachment.uuid : undefined,
1508
+ };
1509
+ }
1510
+
1511
+ /**
1512
+ * Whether this client downloaded and hashed exactly this attachment, proven
1513
+ * by an unchanged id and UUID. Without a UUID, bytes are never taken as
1514
+ * verified: the download is repeated.
1515
+ */
1516
+ private bytesVerified(
1517
+ asset: IGiteaFrozenAsset,
1518
+ identity: IGiteaAttachmentIdentity,
1519
+ ): boolean {
1520
+ const verified = this.#bytesVerified.get(asset.name);
1521
+ return (
1522
+ verified !== undefined &&
1523
+ identity.uuid !== undefined &&
1524
+ verified.id === identity.id &&
1525
+ verified.uuid === identity.uuid
1526
+ );
1142
1527
  }
1143
1528
 
1144
1529
  private async inspectAssetsWithIds(
1145
1530
  releaseId: number,
1146
1531
  expected: IGiteaFrozenAsset[],
1147
1532
  verify: readonly IGiteaFrozenAsset[],
1533
+ /** Skip the download of an attachment this client already verified, unchanged. */
1534
+ reuseVerifiedBytes = false,
1148
1535
  ): Promise<{
1149
1536
  inspection: IGiteaAssetInspection;
1150
- attachmentIds: Map<string, number>;
1537
+ attachments: Map<string, IGiteaAttachmentIdentity>;
1538
+ release: IGiteaRelease;
1151
1539
  }> {
1152
1540
  positiveId(releaseId);
1153
1541
  assertGiteaFrozenAssets(expected, this.destination, this.tag);
1154
- if ((await this.inspectRelease())?.id !== releaseId)
1542
+ const release = await this.inspectRelease();
1543
+ if (!release || release.id !== releaseId)
1155
1544
  throw new GiteaAssetConflictError("Gitea release identifier changed.");
1545
+ // A draft's attachments are visible to writers only.
1156
1546
  const values = await this.requestJson(
1157
1547
  `${this.repositoryApiPath}/releases/${releaseId}/assets`,
1158
- false,
1548
+ release.draft,
1159
1549
  );
1160
1550
  if (!Array.isArray(values) || values.length > maximumAssets)
1161
1551
  throw new Error("Invalid Gitea attachment list.");
1162
1552
  const present: IGiteaFrozenAsset[] = [];
1163
1553
  const seenNames = new Set<string>();
1164
1554
  const seenIds = new Set<number>();
1165
- const attachmentIds = new Map<string, number>();
1555
+ const attachments = new Map<string, IGiteaAttachmentIdentity>();
1166
1556
  for (const value of values) {
1167
1557
  const name = record(value).name;
1168
1558
  const asset = expected.find((candidate) => candidate.name === name);
@@ -1170,16 +1560,23 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1170
1560
  throw new GiteaAssetConflictError(
1171
1561
  "Unexpected or duplicate Gitea release attachment.",
1172
1562
  );
1173
- const id = this.attachment(value, asset);
1174
- if (seenIds.has(id))
1563
+ const identity = this.attachment(value, asset);
1564
+ if (seenIds.has(identity.id))
1175
1565
  throw new GiteaAssetConflictError(
1176
1566
  "Duplicate Gitea release attachment identifier.",
1177
1567
  );
1178
1568
  seenNames.add(asset.name);
1179
- seenIds.add(id);
1180
- attachmentIds.set(asset.name, id);
1181
- if (verify.some((candidate) => candidate.name === asset.name))
1182
- await this.verifyPublicBytes(asset);
1569
+ seenIds.add(identity.id);
1570
+ attachments.set(asset.name, identity);
1571
+ if (
1572
+ verify.some((candidate) => candidate.name === asset.name) &&
1573
+ !(reuseVerifiedBytes && this.bytesVerified(asset, identity))
1574
+ ) {
1575
+ await this.verifyAttachmentBytes(asset, release.draft);
1576
+ // The final listing must still show this identity before the
1577
+ // download stands for it; verifyComplete and publishRelease check that.
1578
+ this.#bytesVerified.set(asset.name, identity);
1579
+ }
1183
1580
  present.push(asset);
1184
1581
  }
1185
1582
  return {
@@ -1187,7 +1584,8 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1187
1584
  present,
1188
1585
  missing: expected.filter((asset) => !seenNames.has(asset.name)),
1189
1586
  },
1190
- attachmentIds,
1587
+ attachments,
1588
+ release,
1191
1589
  };
1192
1590
  }
1193
1591
 
@@ -1208,6 +1606,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1208
1606
  releaseId: number,
1209
1607
  asset: IGiteaFrozenAsset,
1210
1608
  artifactDirectory: string,
1609
+ expectedDraft: boolean,
1211
1610
  ): Promise<void> {
1212
1611
  positiveId(releaseId);
1213
1612
  assertGiteaFrozenAssets([asset], this.destination, this.tag);
@@ -1216,13 +1615,21 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1216
1615
  );
1217
1616
  try {
1218
1617
  await verifyHandle(handle, asset);
1219
- if ((await this.inspectRelease())?.id !== releaseId)
1618
+ const release = await this.inspectRelease();
1619
+ if (release?.id !== releaseId)
1220
1620
  throw new GiteaAssetConflictError(
1221
1621
  "Gitea release identifier changed before upload.",
1222
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
+ );
1629
+ // Authenticated: a writer also sees the attachments of a draft.
1223
1630
  const listed = await this.requestJson(
1224
1631
  `${this.repositoryApiPath}/releases/${releaseId}/assets`,
1225
- false,
1632
+ true,
1226
1633
  );
1227
1634
  if (!Array.isArray(listed))
1228
1635
  throw new Error("Invalid Gitea attachment list.");
@@ -1244,6 +1651,8 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1244
1651
  );
1245
1652
  // The caller's inspection downloads and hashes the accepted attachment.
1246
1653
  this.attachment(result, asset);
1654
+ // A new attachment replaces whatever this name was verified as before.
1655
+ this.#bytesVerified.delete(asset.name);
1247
1656
  } finally {
1248
1657
  await handle.close();
1249
1658
  }
@@ -1253,23 +1662,21 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1253
1662
  releaseId: number,
1254
1663
  expected: IGiteaFrozenAsset[],
1255
1664
  ): Promise<void> {
1256
- const { inspection, attachmentIds } = await this.inspectAssetsWithIds(
1257
- releaseId,
1258
- expected,
1259
- expected,
1260
- );
1665
+ const { inspection, attachments, release } =
1666
+ await this.inspectAssetsWithIds(releaseId, expected, expected, true);
1261
1667
  if (inspection.missing.length !== 0)
1262
1668
  throw new Error(
1263
1669
  "Gitea attachment set is incomplete; npm publication is blocked.",
1264
1670
  );
1265
1671
  // Recheck release/tag identity after potentially long full downloads.
1266
- if ((await this.inspectRelease())?.id !== releaseId)
1672
+ const after = await this.inspectRelease();
1673
+ if (!after || after.id !== releaseId || after.draft !== release.draft)
1267
1674
  throw new GiteaAssetConflictError(
1268
1675
  "Gitea release changed during verification.",
1269
1676
  );
1270
1677
  const finalSet = await this.requestJson(
1271
1678
  `${this.repositoryApiPath}/releases/${releaseId}/assets`,
1272
- false,
1679
+ release.draft,
1273
1680
  );
1274
1681
  if (!Array.isArray(finalSet) || finalSet.length !== expected.length)
1275
1682
  throw new GiteaAssetConflictError(
@@ -1283,13 +1690,19 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1283
1690
  throw new GiteaAssetConflictError(
1284
1691
  "Gitea attachment set changed during verification.",
1285
1692
  );
1286
- const id = this.attachment(value, asset);
1287
- if (ids.has(id) || attachmentIds.get(asset.name) !== id)
1693
+ const identity = this.attachment(value, asset);
1694
+ const listed = attachments.get(asset.name);
1695
+ if (
1696
+ ids.has(identity.id) ||
1697
+ listed === undefined ||
1698
+ listed.id !== identity.id ||
1699
+ listed.uuid !== identity.uuid
1700
+ )
1288
1701
  throw new GiteaAssetConflictError(
1289
1702
  "Gitea attachment set changed during verification.",
1290
1703
  );
1291
1704
  names.add(asset.name);
1292
- ids.add(id);
1705
+ ids.add(identity.id);
1293
1706
  }
1294
1707
  }
1295
1708
  }