@git.zone/cli 7.2.5 → 7.2.7

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.
Files changed (30) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +30 -1
  3. package/dist_ts/helpers.workflow.js +55 -3
  4. package/dist_ts/mod_config/index.js +23 -2
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +34 -0
  6. package/dist_ts/mod_release/classes.releasejournal.js +134 -2
  7. package/dist_ts/mod_release/helpers.giteaassets.d.ts +75 -3
  8. package/dist_ts/mod_release/helpers.giteaassets.js +303 -53
  9. package/dist_ts/mod_release/helpers.gitremote.d.ts +52 -0
  10. package/dist_ts/mod_release/helpers.gitremote.js +87 -0
  11. package/dist_ts/mod_release/helpers.releasebranch.d.ts +5 -0
  12. package/dist_ts/mod_release/helpers.releasebranch.js +39 -15
  13. package/dist_ts/mod_release/helpers.releasepreparation.js +18 -8
  14. package/dist_ts/mod_release/helpers.releasepublication.d.ts +6 -1
  15. package/dist_ts/mod_release/helpers.releasepublication.js +31 -21
  16. package/dist_ts/mod_release/index.js +216 -64
  17. package/dist_ts/mod_release/interfaces.giteaassets.d.ts +18 -3
  18. package/package.json +3 -3
  19. package/readme.md +106 -24
  20. package/ts/00_commitinfo_data.ts +1 -1
  21. package/ts/helpers.workflow.ts +123 -1
  22. package/ts/mod_config/index.ts +25 -0
  23. package/ts/mod_release/classes.releasejournal.ts +181 -1
  24. package/ts/mod_release/helpers.giteaassets.ts +438 -75
  25. package/ts/mod_release/helpers.gitremote.ts +147 -0
  26. package/ts/mod_release/helpers.releasebranch.ts +75 -30
  27. package/ts/mod_release/helpers.releasepreparation.ts +25 -7
  28. package/ts/mod_release/helpers.releasepublication.ts +45 -42
  29. package/ts/mod_release/index.ts +333 -85
  30. package/ts/mod_release/interfaces.giteaassets.ts +20 -2
@@ -8,6 +8,7 @@ import type {
8
8
  IGiteaAssetPreflight,
9
9
  IGiteaRelease,
10
10
  IGiteaAssetsClient,
11
+ IGiteaAssetTransferLimits,
11
12
  } from "./interfaces.giteaassets.js";
12
13
  export type * from "./interfaces.giteaassets.js";
13
14
 
@@ -33,6 +34,295 @@ class GiteaAssetHttpError extends Error {
33
34
  }
34
35
  }
35
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
+
81
+ export const defaultGiteaAssetTransferLimits: Readonly<IGiteaAssetTransferLimits> =
82
+ Object.freeze({
83
+ responseTimeoutMs: 2 * 60_000,
84
+ stallTimeoutMs: 60_000,
85
+ minimumBytesPerSecond: 256 * 1024,
86
+ });
87
+
88
+ const maximumTransferTimeoutMs = 60 * 60_000;
89
+ const maximumBytesPerSecond = 1024 * 1024 * 1024;
90
+ /** Node fires longer timers immediately; a ceiling this far out never binds. */
91
+ const maximumTimerMs = 2_147_483_647;
92
+ const inconclusive =
93
+ "the result is inconclusive; inspect the retained release before another mutation.";
94
+ const formatSeconds = (milliseconds: number): string =>
95
+ `${Math.round(milliseconds / 100) / 10} s`;
96
+
97
+ /** A Gitea request ended by a transfer bound; messages carry no URL or credential. */
98
+ export class GiteaAssetTimeoutError extends Error {
99
+ constructor(message: string) {
100
+ super(message);
101
+ this.name = "GiteaAssetTimeoutError";
102
+ }
103
+ }
104
+
105
+ /** No response headers arrived within the response bound. */
106
+ export class GiteaAssetResponseTimeoutError extends GiteaAssetTimeoutError {
107
+ constructor(operation: string, limitMs: number) {
108
+ super(
109
+ `Gitea asset ${operation} received no response within ${formatSeconds(limitMs)}; ${inconclusive}`,
110
+ );
111
+ this.name = "GiteaAssetResponseTimeoutError";
112
+ }
113
+ }
114
+
115
+ /** The transfer moved no byte for the stall bound. */
116
+ export class GiteaAssetTransferStalledError extends GiteaAssetTimeoutError {
117
+ constructor(
118
+ operation: string,
119
+ direction: "sent" | "received",
120
+ limitMs: number,
121
+ bytes: number,
122
+ ) {
123
+ super(
124
+ `Gitea asset ${operation} stalled: no bytes ${direction} for ${formatSeconds(limitMs)} after ${bytes} bytes; ${inconclusive}`,
125
+ );
126
+ this.name = "GiteaAssetTransferStalledError";
127
+ }
128
+ }
129
+
130
+ /** Every upload byte was sent, but the server did not answer within the size allowance. */
131
+ export class GiteaAssetUploadNotAcknowledgedError extends GiteaAssetTimeoutError {
132
+ constructor(bytes: number, limitMs: number, minimumBytesPerSecond: number) {
133
+ super(
134
+ `Gitea asset upload was not acknowledged: all ${bytes} bytes were sent, but no response arrived within ${formatSeconds(limitMs)}, the allowance for its size at ${Math.round(minimumBytesPerSecond / 1024)} KiB/s; ${inconclusive}`,
135
+ );
136
+ this.name = "GiteaAssetUploadNotAcknowledgedError";
137
+ }
138
+ }
139
+
140
+ /** The transfer kept moving but stayed below the configured rate floor. */
141
+ export class GiteaAssetTransferTooSlowError extends GiteaAssetTimeoutError {
142
+ constructor(
143
+ operation: string,
144
+ elapsedMs: number,
145
+ bytes: number,
146
+ expectedBytes: number,
147
+ minimumBytesPerSecond: number,
148
+ ) {
149
+ super(
150
+ `Gitea asset ${operation} was still progressing but too slow: ${bytes} of ${expectedBytes} bytes after ${formatSeconds(elapsedMs)}, below the ${Math.round(minimumBytesPerSecond / 1024)} KiB/s floor; ${inconclusive}`,
151
+ );
152
+ this.name = "GiteaAssetTransferTooSlowError";
153
+ }
154
+ }
155
+
156
+ const assertTransferLimits = (
157
+ limits: IGiteaAssetTransferLimits,
158
+ ): IGiteaAssetTransferLimits => {
159
+ for (const value of [limits.responseTimeoutMs, limits.stallTimeoutMs])
160
+ if (
161
+ !Number.isSafeInteger(value) ||
162
+ value <= 0 ||
163
+ value > maximumTransferTimeoutMs
164
+ )
165
+ throw new Error("Invalid Gitea asset request timeout.");
166
+ if (
167
+ !Number.isSafeInteger(limits.minimumBytesPerSecond) ||
168
+ limits.minimumBytesPerSecond <= 0 ||
169
+ limits.minimumBytesPerSecond > maximumBytesPerSecond
170
+ )
171
+ throw new Error("Invalid Gitea asset minimum transfer rate.");
172
+ return limits;
173
+ };
174
+
175
+ type TWatchdogPhase = "response" | "stall" | "acknowledgement";
176
+
177
+ /**
178
+ * Bounds one request by progress instead of wall-clock time: the response
179
+ * bound covers waiting for headers, the stall bound restarts on every byte,
180
+ * an upload's acknowledgement wait scales with its size, and a ceiling of
181
+ * expected bytes at the rate floor ends a trickle.
182
+ */
183
+ export class GiteaTransferWatchdog {
184
+ readonly #controller = new AbortController();
185
+ readonly #started = Date.now();
186
+ readonly #ceiling: NodeJS.Timeout;
187
+ /** Servers process and store a large upload before answering; allow its size at the floor. */
188
+ readonly #acknowledgementMs: number;
189
+ #timer: NodeJS.Timeout | undefined;
190
+ #phase: TWatchdogPhase | undefined;
191
+ #direction: "sent" | "received" = "sent";
192
+ #bytes = 0;
193
+ #failure: GiteaAssetTimeoutError | undefined;
194
+ /** A late body pull or chunk after close must never re-arm a timer. */
195
+ #closed = false;
196
+
197
+ constructor(
198
+ private readonly operation: string,
199
+ private readonly limits: IGiteaAssetTransferLimits,
200
+ /** Bytes the request moves in total, including an upload body. */
201
+ private readonly expectedBytes: number,
202
+ private readonly uploadBytes = 0,
203
+ ) {
204
+ const atFloor = (bytes: number) =>
205
+ Math.ceil((bytes * 1000) / limits.minimumBytesPerSecond);
206
+ this.#acknowledgementMs = Math.max(
207
+ limits.responseTimeoutMs,
208
+ atFloor(uploadBytes),
209
+ );
210
+ const ceilingMs = Math.min(
211
+ maximumTimerMs,
212
+ limits.responseTimeoutMs +
213
+ limits.stallTimeoutMs +
214
+ atFloor(expectedBytes) +
215
+ (uploadBytes ? this.#acknowledgementMs : 0),
216
+ );
217
+ this.#ceiling = setTimeout(
218
+ () =>
219
+ this.#fail(
220
+ new GiteaAssetTransferTooSlowError(
221
+ operation,
222
+ Date.now() - this.#started,
223
+ this.#bytes,
224
+ expectedBytes,
225
+ limits.minimumBytesPerSecond,
226
+ ),
227
+ ),
228
+ ceilingMs,
229
+ );
230
+ }
231
+
232
+ get signal(): AbortSignal {
233
+ return this.#controller.signal;
234
+ }
235
+
236
+ get failure(): GiteaAssetTimeoutError | undefined {
237
+ return this.#failure;
238
+ }
239
+
240
+ /** Bytes sent and received so far. */
241
+ get bytes(): number {
242
+ return this.#bytes;
243
+ }
244
+
245
+ /** Wait for response headers; every redirect hop starts a new wait. */
246
+ awaitResponse(): void {
247
+ this.#arm("response");
248
+ }
249
+
250
+ /** The whole upload body is sent; wait for the server to store and answer it. */
251
+ awaitAcknowledgement(): void {
252
+ this.#arm("acknowledgement");
253
+ }
254
+
255
+ /** Record moved bytes; the stall bound restarts from this moment. */
256
+ progress(direction: "sent" | "received", bytes: number): void {
257
+ if (this.#closed) return;
258
+ this.#direction = direction;
259
+ this.#bytes += bytes;
260
+ this.#arm("stall");
261
+ }
262
+
263
+ close(): void {
264
+ this.#closed = true;
265
+ clearTimeout(this.#ceiling);
266
+ clearTimeout(this.#timer);
267
+ this.#controller.abort();
268
+ }
269
+
270
+ #arm(phase: TWatchdogPhase): void {
271
+ if (this.#failure || this.#closed) return;
272
+ if (this.#timer && this.#phase === phase) {
273
+ this.#timer.refresh();
274
+ return;
275
+ }
276
+ clearTimeout(this.#timer);
277
+ this.#phase = phase;
278
+ const bounds: Record<
279
+ TWatchdogPhase,
280
+ [number, () => GiteaAssetTimeoutError]
281
+ > = {
282
+ response: [
283
+ this.limits.responseTimeoutMs,
284
+ () =>
285
+ new GiteaAssetResponseTimeoutError(
286
+ this.operation,
287
+ this.limits.responseTimeoutMs,
288
+ ),
289
+ ],
290
+ stall: [
291
+ this.limits.stallTimeoutMs,
292
+ () =>
293
+ new GiteaAssetTransferStalledError(
294
+ this.operation,
295
+ this.#direction,
296
+ this.limits.stallTimeoutMs,
297
+ this.#bytes,
298
+ ),
299
+ ],
300
+ acknowledgement: [
301
+ this.#acknowledgementMs,
302
+ () =>
303
+ new GiteaAssetUploadNotAcknowledgedError(
304
+ this.uploadBytes,
305
+ this.#acknowledgementMs,
306
+ this.limits.minimumBytesPerSecond,
307
+ ),
308
+ ],
309
+ };
310
+ const [milliseconds, failure] = bounds[phase];
311
+ this.#timer = setTimeout(
312
+ () => this.#fail(failure()),
313
+ Math.min(maximumTimerMs, milliseconds),
314
+ );
315
+ }
316
+
317
+ #fail(error: GiteaAssetTimeoutError): void {
318
+ if (this.#failure) return;
319
+ this.#failure = error;
320
+ clearTimeout(this.#ceiling);
321
+ clearTimeout(this.#timer);
322
+ this.#controller.abort();
323
+ }
324
+ }
325
+
36
326
  const record = (value: unknown): Record<string, unknown> => {
37
327
  if (!value || typeof value !== "object" || Array.isArray(value)) {
38
328
  throw new Error("Invalid Gitea asset object.");
@@ -432,7 +722,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
432
722
  private readonly commit: string;
433
723
  readonly #token: string;
434
724
  private readonly fetchImplementation: typeof fetch;
435
- private readonly timeoutMs: number;
725
+ private readonly limits: IGiteaAssetTransferLimits;
436
726
  private readonly repositoryApiPath: string;
437
727
 
438
728
  constructor(options: IGiteaAssetsClientOptions) {
@@ -450,35 +740,57 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
450
740
  this.commit = options.commit;
451
741
  this.#token = options.token;
452
742
  this.fetchImplementation = options.fetchImplementation ?? fetch;
453
- this.timeoutMs = options.timeoutMs ?? 15 * 60_000;
454
- if (
455
- !Number.isSafeInteger(this.timeoutMs) ||
456
- this.timeoutMs <= 0 ||
457
- this.timeoutMs > 60 * 60_000
458
- )
459
- throw new Error("Invalid Gitea asset request timeout.");
743
+ this.limits = assertTransferLimits({
744
+ responseTimeoutMs:
745
+ options.responseTimeoutMs ??
746
+ defaultGiteaAssetTransferLimits.responseTimeoutMs,
747
+ stallTimeoutMs:
748
+ options.stallTimeoutMs ?? defaultGiteaAssetTransferLimits.stallTimeoutMs,
749
+ minimumBytesPerSecond:
750
+ options.minimumBytesPerSecond ??
751
+ defaultGiteaAssetTransferLimits.minimumBytesPerSecond,
752
+ });
460
753
  this.repositoryApiPath = `/repos/${this.destination.owner}/${this.destination.repository}`;
461
754
  }
462
755
 
463
756
  private async requestJson(
464
757
  path: string,
465
758
  authenticated: boolean,
466
- method = "GET",
467
- body?: BodyInit,
468
- headers?: Record<string, string>,
469
- allow404 = false,
759
+ options: {
760
+ method?: "GET" | "POST";
761
+ body?: string;
762
+ /** Streams exactly `size` bytes of the open file; progress means accepted by the transport. */
763
+ upload?: {
764
+ handle: Awaited<ReturnType<typeof openRegularFile>>;
765
+ size: number;
766
+ };
767
+ headers?: Record<string, string>;
768
+ allow404?: boolean;
769
+ } = {},
470
770
  ): Promise<unknown | null> {
471
- const controller = new AbortController();
472
- const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
771
+ const method = options.method ?? "GET";
772
+ const watchdog = new GiteaTransferWatchdog(
773
+ options.upload ? "upload" : method,
774
+ this.limits,
775
+ (options.upload?.size ?? 0) + maximumMetadataBytes,
776
+ options.upload?.size,
777
+ );
473
778
  let response: Response | undefined;
474
779
  try {
780
+ let body: BodyInit | undefined = options.body;
781
+ if (options.upload) {
782
+ body = this.uploadBody(options.upload.handle, options.upload.size, watchdog);
783
+ watchdog.progress("sent", 0);
784
+ } else {
785
+ watchdog.awaitResponse();
786
+ }
475
787
  const init: RequestInit & { duplex?: "half" } = {
476
788
  method,
477
789
  redirect: "manual",
478
- signal: controller.signal,
790
+ signal: watchdog.signal,
479
791
  headers: {
480
792
  Accept: "application/json",
481
- ...headers,
793
+ ...options.headers,
482
794
  ...(authenticated ? { Authorization: `token ${this.#token}` } : {}),
483
795
  },
484
796
  ...(body === undefined ? {} : { body, duplex: "half" }),
@@ -487,29 +799,74 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
487
799
  `${this.destination.apiOrigin}/api/v1${path}`,
488
800
  init,
489
801
  );
490
- if (allow404 && response.status === 404) return null;
802
+ watchdog.progress("received", 0);
803
+ if (options.allow404 && response.status === 404) return null;
491
804
  if (response.status !== (method === "POST" ? 201 : 200)) {
492
805
  throw new GiteaAssetHttpError(method, response.status);
493
806
  }
494
- const bytes = await this.readResponse(response, maximumMetadataBytes);
807
+ const bytes = await this.readResponse(
808
+ response,
809
+ maximumMetadataBytes,
810
+ watchdog,
811
+ );
495
812
  return JSON.parse(bytes.toString("utf8"));
496
813
  } catch (error) {
497
814
  // Never include response text, fetch errors, URLs or causes that can expose the token.
815
+ if (watchdog.failure) throw watchdog.failure;
498
816
  if (error instanceof GiteaAssetHttpError) throw error;
499
- throw new Error(
500
- `Gitea asset ${method} result is inconclusive; inspect the retained release before another mutation.`,
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.`,
501
825
  );
502
826
  } finally {
503
- controller.abort();
504
- clearTimeout(timeout);
827
+ watchdog.close();
505
828
  if (response?.body && !response.body.locked)
506
829
  await response.body.cancel().catch(() => undefined);
507
830
  }
508
831
  }
509
832
 
833
+ /** Pull-driven: the next chunk is read only when fetch has taken the last one. */
834
+ private uploadBody(
835
+ handle: Awaited<ReturnType<typeof openRegularFile>>,
836
+ size: number,
837
+ watchdog: GiteaTransferWatchdog,
838
+ ): ReadableStream<Uint8Array> {
839
+ let position = 0;
840
+ return new ReadableStream<Uint8Array>(
841
+ {
842
+ pull: async (controller) => {
843
+ if (position === size) {
844
+ watchdog.awaitAcknowledgement();
845
+ controller.close();
846
+ return;
847
+ }
848
+ const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, size - position));
849
+ const { bytesRead } = await handle.read(
850
+ chunk,
851
+ 0,
852
+ chunk.length,
853
+ position,
854
+ );
855
+ if (bytesRead === 0)
856
+ throw new Error("Gitea asset changed during upload.");
857
+ position += bytesRead;
858
+ watchdog.progress("sent", bytesRead);
859
+ controller.enqueue(chunk.subarray(0, bytesRead));
860
+ },
861
+ },
862
+ { highWaterMark: 0 },
863
+ );
864
+ }
865
+
510
866
  private async readResponse(
511
867
  response: Response,
512
868
  maximum: number,
869
+ watchdog: GiteaTransferWatchdog,
513
870
  ): Promise<Buffer> {
514
871
  if (!response.body) throw new Error("Missing Gitea response body.");
515
872
  const declared = response.headers.get("content-length");
@@ -525,6 +882,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
525
882
  while (true) {
526
883
  const result = await reader.read();
527
884
  if (result.done) break;
885
+ watchdog.progress("received", result.value.byteLength);
528
886
  size += result.value.byteLength;
529
887
  if (size > maximum) throw new Error("Oversized Gitea response.");
530
888
  chunks.push(Buffer.from(result.value));
@@ -635,22 +993,10 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
635
993
  public async inspectRelease(): Promise<IGiteaRelease | null> {
636
994
  await this.admitTag();
637
995
  const path = `${this.repositoryApiPath}/releases/tags/${encodeURIComponent(this.tag)}`;
638
- const authenticated = await this.requestJson(
639
- path,
640
- true,
641
- "GET",
642
- undefined,
643
- undefined,
644
- true,
645
- );
646
- const anonymous = await this.requestJson(
647
- path,
648
- false,
649
- "GET",
650
- undefined,
651
- undefined,
652
- true,
653
- );
996
+ const authenticated = await this.requestJson(path, true, {
997
+ allow404: true,
998
+ });
999
+ const anonymous = await this.requestJson(path, false, { allow404: true });
654
1000
  if (authenticated === null && anonymous === null) return null;
655
1001
  if (authenticated === null || anonymous === null)
656
1002
  throw new Error(
@@ -670,15 +1016,17 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
670
1016
  await this.requestJson(
671
1017
  `${this.repositoryApiPath}/releases`,
672
1018
  true,
673
- "POST",
674
- JSON.stringify({
675
- tag_name: this.tag,
676
- target_commitish: this.commit,
677
- name: this.tag,
678
- draft: false,
679
- prerelease: false,
680
- }),
681
- { "Content-Type": "application/json" },
1019
+ {
1020
+ method: "POST",
1021
+ body: JSON.stringify({
1022
+ tag_name: this.tag,
1023
+ target_commitish: this.commit,
1024
+ name: this.tag,
1025
+ draft: false,
1026
+ prerelease: false,
1027
+ }),
1028
+ headers: { "Content-Type": "application/json" },
1029
+ },
682
1030
  ),
683
1031
  );
684
1032
  const verified = await this.inspectRelease();
@@ -694,9 +1042,15 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
694
1042
  }
695
1043
 
696
1044
  private async verifyPublicBytes(asset: IGiteaFrozenAsset): Promise<void> {
697
- const controller = new AbortController();
698
- const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
1045
+ const watchdog = new GiteaTransferWatchdog(
1046
+ "download",
1047
+ this.limits,
1048
+ asset.size,
1049
+ );
699
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;
700
1054
  try {
701
1055
  let url = new URL(asset.publicUrl);
702
1056
  for (let redirects = 0; ; redirects++) {
@@ -707,11 +1061,15 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
707
1061
  url.hash
708
1062
  )
709
1063
  throw new GiteaAssetConflictError("Unsafe anonymous asset redirect.");
1064
+ watchdog.awaitResponse();
1065
+ status = undefined;
710
1066
  response = await this.fetchImplementation(url.href, {
711
1067
  redirect: "manual",
712
- signal: controller.signal,
1068
+ signal: watchdog.signal,
713
1069
  headers: { "Accept-Encoding": "identity" },
714
1070
  });
1071
+ status = response.status;
1072
+ watchdog.progress("received", 0);
715
1073
  if (![301, 302, 303, 307, 308].includes(response.status)) break;
716
1074
  if (redirects >= 5 || !response.headers.get("location"))
717
1075
  throw new GiteaAssetConflictError(
@@ -734,12 +1092,12 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
734
1092
  )
735
1093
  throw new GiteaAssetConflictError("Anonymous asset size mismatch.");
736
1094
  const hash = plugins.crypto.createHash("sha256");
737
- let size = 0;
738
1095
  const reader = response.body.getReader();
739
1096
  try {
740
1097
  while (true) {
741
1098
  const next = await reader.read();
742
1099
  if (next.done) break;
1100
+ watchdog.progress("received", next.value.byteLength);
743
1101
  size += next.value.byteLength;
744
1102
  if (size > asset.size)
745
1103
  throw new GiteaAssetConflictError(
@@ -754,13 +1112,16 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
754
1112
  if (size !== asset.size || hash.digest("hex") !== asset.sha256)
755
1113
  throw new GiteaAssetConflictError("Anonymous asset bytes mismatch.");
756
1114
  } catch (error) {
1115
+ if (watchdog.failure) throw watchdog.failure;
757
1116
  if (error instanceof GiteaAssetConflictError) throw error;
758
- throw new Error(
759
- "Gitea public asset verification is inconclusive; inspect availability before publication.",
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.`,
760
1122
  );
761
1123
  } finally {
762
- controller.abort();
763
- clearTimeout(timeout);
1124
+ watchdog.close();
764
1125
  if (response?.body && !response.body.locked)
765
1126
  await response.body.cancel().catch(() => undefined);
766
1127
  }
@@ -783,6 +1144,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
783
1144
  private async inspectAssetsWithIds(
784
1145
  releaseId: number,
785
1146
  expected: IGiteaFrozenAsset[],
1147
+ verify: readonly IGiteaFrozenAsset[],
786
1148
  ): Promise<{
787
1149
  inspection: IGiteaAssetInspection;
788
1150
  attachmentIds: Map<string, number>;
@@ -816,7 +1178,8 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
816
1178
  seenNames.add(asset.name);
817
1179
  seenIds.add(id);
818
1180
  attachmentIds.set(asset.name, id);
819
- await this.verifyPublicBytes(asset);
1181
+ if (verify.some((candidate) => candidate.name === asset.name))
1182
+ await this.verifyPublicBytes(asset);
820
1183
  present.push(asset);
821
1184
  }
822
1185
  return {
@@ -828,11 +1191,17 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
828
1191
  };
829
1192
  }
830
1193
 
1194
+ /**
1195
+ * Every listed attachment must match its frozen metadata; only the present
1196
+ * attachments named in `verify` (all by default) are downloaded and hashed.
1197
+ */
831
1198
  public async inspectAssets(
832
1199
  releaseId: number,
833
1200
  expected: IGiteaFrozenAsset[],
1201
+ verify: readonly IGiteaFrozenAsset[] = expected,
834
1202
  ): Promise<IGiteaAssetInspection> {
835
- return (await this.inspectAssetsWithIds(releaseId, expected)).inspection;
1203
+ return (await this.inspectAssetsWithIds(releaseId, expected, verify))
1204
+ .inspection;
836
1205
  }
837
1206
 
838
1207
  public async uploadAsset(
@@ -861,27 +1230,20 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
861
1230
  throw new GiteaAssetConflictError(
862
1231
  "Gitea upload requires an absent attachment name; inspect the retained release.",
863
1232
  );
864
- const stream = handle.createReadStream({
865
- autoClose: false,
866
- start: 0,
867
- highWaterMark: 64 * 1024,
868
- });
869
- try {
870
- const result = await this.requestJson(
871
- `${this.repositoryApiPath}/releases/${releaseId}/assets?name=${encodeURIComponent(asset.name)}`,
872
- true,
873
- "POST",
874
- stream as unknown as BodyInit,
875
- {
1233
+ const result = await this.requestJson(
1234
+ `${this.repositoryApiPath}/releases/${releaseId}/assets?name=${encodeURIComponent(asset.name)}`,
1235
+ true,
1236
+ {
1237
+ method: "POST",
1238
+ upload: { handle, size: asset.size },
1239
+ headers: {
876
1240
  "Content-Type": "application/octet-stream",
877
1241
  "Content-Length": String(asset.size),
878
1242
  },
879
- );
880
- this.attachment(result, asset);
881
- } finally {
882
- stream.destroy();
883
- }
884
- await this.verifyPublicBytes(asset);
1243
+ },
1244
+ );
1245
+ // The caller's inspection downloads and hashes the accepted attachment.
1246
+ this.attachment(result, asset);
885
1247
  } finally {
886
1248
  await handle.close();
887
1249
  }
@@ -894,6 +1256,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
894
1256
  const { inspection, attachmentIds } = await this.inspectAssetsWithIds(
895
1257
  releaseId,
896
1258
  expected,
1259
+ expected,
897
1260
  );
898
1261
  if (inspection.missing.length !== 0)
899
1262
  throw new Error(