@bymax-one/nest-storage 1.1.11 → 1.1.13

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.
@@ -53,7 +53,8 @@ var STORAGE_ERROR_CODES = {
53
53
  STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED",
54
54
  STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND",
55
55
  STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED",
56
- STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH"
56
+ STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH",
57
+ STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED"
57
58
  };
58
59
 
59
60
  // src/server/errors/storage-error-messages.ts
@@ -83,8 +84,10 @@ var STORAGE_ERROR_MESSAGES = {
83
84
  [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: "The object does not satisfy the supplied precondition",
84
85
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND]: "The bucket does not exist",
85
86
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED]: "The bucket cannot be accessed with these credentials (it may also not exist)",
86
- [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: "The bucket belongs to a different region than the configured one"
87
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: "The bucket belongs to a different region than the configured one",
88
+ [STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED]: "The call was aborted by its AbortSignal"
87
89
  };
90
+ var CLIENT_CLOSED_REQUEST = 499;
88
91
  var STORAGE_ERROR_STATUS = {
89
92
  [STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED]: common.HttpStatus.SERVICE_UNAVAILABLE,
90
93
  [STORAGE_ERROR_CODES.STORAGE_KEY_INVALID]: common.HttpStatus.BAD_REQUEST,
@@ -103,7 +106,7 @@ var STORAGE_ERROR_STATUS = {
103
106
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED]: common.HttpStatus.BAD_REQUEST,
104
107
  [STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED]: common.HttpStatus.INTERNAL_SERVER_ERROR,
105
108
  [STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG]: common.HttpStatus.INTERNAL_SERVER_ERROR,
106
- [STORAGE_ERROR_CODES.STORAGE_TIMEOUT]: common.HttpStatus.GATEWAY_TIMEOUT,
109
+ [STORAGE_ERROR_CODES.STORAGE_TIMEOUT]: common.HttpStatus.SERVICE_UNAVAILABLE,
107
110
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_RULE_INVALID]: common.HttpStatus.BAD_REQUEST,
108
111
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: common.HttpStatus.NOT_IMPLEMENTED,
109
112
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: common.HttpStatus.UNPROCESSABLE_ENTITY,
@@ -111,7 +114,8 @@ var STORAGE_ERROR_STATUS = {
111
114
  [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: common.HttpStatus.PRECONDITION_FAILED,
112
115
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND]: common.HttpStatus.NOT_FOUND,
113
116
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED]: common.HttpStatus.FORBIDDEN,
114
- [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: common.HttpStatus.INTERNAL_SERVER_ERROR
117
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: common.HttpStatus.INTERNAL_SERVER_ERROR,
118
+ [STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED]: CLIENT_CLOSED_REQUEST
115
119
  };
116
120
 
117
121
  // src/server/errors/storage-exception.ts
@@ -132,14 +136,17 @@ var StorageException = class extends common.HttpException {
132
136
  }
133
137
  };
134
138
 
139
+ // src/server/constants/timer.constants.ts
140
+ var MAX_TIMER_MS = 2147483647;
141
+
135
142
  // src/server/utils/header-value.ts
136
143
  var HEADER_VALUE = /^[\t \x21-\x7E]*$/;
137
144
  var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
138
145
  var VALUE_REASON = "must be a string of tab, space and printable ASCII characters";
139
146
  var KEY_REASON = "every key must be a non-empty header name of letters, digits and the characters !#$%&'*+-.^_`|~";
140
- function refuse(field, reason) {
147
+ function refuse(field2, reason) {
141
148
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
142
- field,
149
+ field: field2,
143
150
  reason
144
151
  });
145
152
  }
@@ -147,9 +154,9 @@ function isHeaderValue(value) {
147
154
  return typeof value === "string" && HEADER_VALUE.test(value);
148
155
  }
149
156
  function assertHeaderValues(fields) {
150
- for (const [field, value] of Object.entries(fields)) {
157
+ for (const [field2, value] of Object.entries(fields)) {
151
158
  if (value !== void 0 && !isHeaderValue(value)) {
152
- refuse(field, VALUE_REASON);
159
+ refuse(field2, VALUE_REASON);
153
160
  }
154
161
  }
155
162
  }
@@ -180,6 +187,34 @@ function isObject(value) {
180
187
  function isNonEmptyString(value) {
181
188
  return typeof value === "string" && value.length > 0;
182
189
  }
190
+ var BEFORE_AUTHORITY = /^(?:[a-z][a-z\d+.-]*:)?[/\\]*/i;
191
+ function asParsed(value) {
192
+ return value.replace(/[\t\n\r]/g, "").replace(/^[\p{Cc} ]+/u, "");
193
+ }
194
+ function parsedCarriesCredentials(value) {
195
+ try {
196
+ const url = new URL(value);
197
+ return url.username !== "" || url.password !== "";
198
+ } catch {
199
+ return false;
200
+ }
201
+ }
202
+ function authorityCarriesCredentials(text) {
203
+ const rest = text.replace(BEFORE_AUTHORITY, "");
204
+ const end = rest.search(/[/?#]/);
205
+ return (end === -1 ? rest : rest.slice(0, end)).includes("@");
206
+ }
207
+ function urlCarriesCredentials(value) {
208
+ return parsedCarriesCredentials(value) || authorityCarriesCredentials(asParsed(value));
209
+ }
210
+ function assertTimerMs(options, name, min) {
211
+ const value = options[name];
212
+ if (value !== void 0 && (typeof value !== "number" || !Number.isInteger(value) || value < min || value > MAX_TIMER_MS)) {
213
+ throw invalid(
214
+ `${name} must be an integer from ${String(min)} to ${String(MAX_TIMER_MS)}` + (min === 0 ? " (0 disables the guard)" : "")
215
+ );
216
+ }
217
+ }
183
218
  function validateOptions(options) {
184
219
  if (!isObject(options)) {
185
220
  throw invalid("options object is required");
@@ -187,6 +222,12 @@ function validateOptions(options) {
187
222
  if (!isNonEmptyString(options.endpoint)) {
188
223
  throw invalid("options.endpoint must be a non-empty string");
189
224
  }
225
+ for (const name of ["endpoint", "publicBaseUrl", "cdnBaseUrl"]) {
226
+ const value = options[name];
227
+ if (typeof value === "string" && urlCarriesCredentials(value)) {
228
+ throw invalid(`options.${name} must not carry credentials; pass them in options.credentials`);
229
+ }
230
+ }
190
231
  if (!isNonEmptyString(options.region)) {
191
232
  throw invalid("options.region must be a non-empty string");
192
233
  }
@@ -204,10 +245,13 @@ function validateOptions(options) {
204
245
  if (isObject(multipart) && typeof multipart.partSizeBytes === "number" && multipart.partSizeBytes < MIN_PART_SIZE_BYTES) {
205
246
  throw invalid("multipart.partSizeBytes must be >= 5 MB (S3 hard limit)");
206
247
  }
207
- const idle = options.uploadIdleTimeoutMs;
208
- if (idle !== void 0 && (typeof idle !== "number" || !Number.isInteger(idle) || idle < 0)) {
209
- throw invalid("uploadIdleTimeoutMs must be an integer >= 0 (0 disables the guard)");
248
+ const maxAttempts = options.maxAttempts;
249
+ if (maxAttempts !== void 0 && (typeof maxAttempts !== "number" || !Number.isInteger(maxAttempts) || maxAttempts < 1)) {
250
+ throw invalid("maxAttempts must be an integer >= 1");
210
251
  }
252
+ assertTimerMs(options, "requestTimeoutMs", 1);
253
+ assertTimerMs(options, "uploadIdleTimeoutMs", 0);
254
+ assertTimerMs(options, "bodyIdleTimeoutMs", 0);
211
255
  if (options.serverSideEncryption === "aws:kms" && !options.kmsKeyId) {
212
256
  throw invalid('kmsKeyId is required when serverSideEncryption === "aws:kms"');
213
257
  }
@@ -289,6 +333,7 @@ function applyDefaults(options) {
289
333
  maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
290
334
  requestTimeoutMs,
291
335
  uploadIdleTimeoutMs: options.uploadIdleTimeoutMs ?? requestTimeoutMs,
336
+ bodyIdleTimeoutMs: options.bodyIdleTimeoutMs ?? requestTimeoutMs,
292
337
  hasCredentials
293
338
  };
294
339
  Object.defineProperty(resolved, "credentials", {
@@ -298,6 +343,18 @@ function applyDefaults(options) {
298
343
  });
299
344
  return resolved;
300
345
  }
346
+
347
+ // src/server/utils/describe-endpoint.ts
348
+ function describeEndpoint(endpoint) {
349
+ try {
350
+ const url = new URL(endpoint);
351
+ return `${url.protocol}//${url.host}`;
352
+ } catch {
353
+ return "<unparseable endpoint>";
354
+ }
355
+ }
356
+
357
+ // src/server/providers/s3-client.provider.ts
301
358
  var S3ClientProvider = class {
302
359
  constructor(options) {
303
360
  this.options = options;
@@ -383,7 +440,7 @@ var S3ClientProvider = class {
383
440
  responseChecksumValidation: this.options.responseChecksumValidation
384
441
  };
385
442
  this.logger.log(
386
- `S3Client initialized: endpoint=${this.options.endpoint} region=${this.options.region}`
443
+ `S3Client initialized: endpoint=${describeEndpoint(this.options.endpoint)} region=${this.options.region}`
387
444
  );
388
445
  return new clientS3.S3Client(config);
389
446
  }
@@ -452,6 +509,127 @@ KeyResolverService = __decorateClass([
452
509
  common.Injectable(),
453
510
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS))
454
511
  ], KeyResolverService);
512
+
513
+ // src/server/utils/describe-error.ts
514
+ var NON_PRINTABLE_REJECTION = "non-printable rejection value";
515
+ function describeError(value) {
516
+ try {
517
+ if (typeof value === "object" && value !== null) {
518
+ const message = value.message;
519
+ if (typeof message === "string") {
520
+ return message;
521
+ }
522
+ }
523
+ return String(value);
524
+ } catch {
525
+ return NON_PRINTABLE_REJECTION;
526
+ }
527
+ }
528
+
529
+ // src/server/utils/log-value.ts
530
+ var LEFT_LITERAL_BY_JSON = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
531
+ function logValue(value) {
532
+ const text = typeof value === "string" ? value : describeError(value);
533
+ return JSON.stringify(text).replace(
534
+ LEFT_LITERAL_BY_JSON,
535
+ (char) => {
536
+ const codePoint = Number(char.codePointAt(0));
537
+ const hex = codePoint.toString(16);
538
+ return codePoint > 65535 ? `\\u{${hex}}` : `\\u${hex.padStart(4, "0")}`;
539
+ }
540
+ );
541
+ }
542
+
543
+ // src/server/utils/provider-failure-log.ts
544
+ var SECRET_IN_MESSAGE = /(X-Amz-(?:Signature|Credential|Security-Token)|AWSAccessKeyId|Signature)=[^&\s"']+/gi;
545
+ var MAX_MESSAGE_LENGTH = 300;
546
+ var logger = new common.Logger("StorageProvider");
547
+ function field(value) {
548
+ return typeof value === "string" || typeof value === "number" ? logValue(value) : "-";
549
+ }
550
+ function describeProviderFailure(err) {
551
+ const failure = typeof err === "object" && err !== null ? err : {};
552
+ const message = describeError(err).replace(SECRET_IN_MESSAGE, "$1=[redacted]");
553
+ return [
554
+ `name=${field(failure.name)}`,
555
+ `code=${field(failure.Code)}`,
556
+ `status=${field(failure.$metadata?.httpStatusCode)}`,
557
+ `requestId=${field(failure.$metadata?.requestId)}`,
558
+ `message=${logValue(message.slice(0, MAX_MESSAGE_LENGTH))}`
559
+ ].join(" ");
560
+ }
561
+ function logProviderFailure(err, context) {
562
+ const op = typeof context?.op === "string" ? logValue(context.op) : "-";
563
+ const key = typeof context?.key === "string" ? logValue(context.key) : "-";
564
+ logger.warn(`Provider call failed: op=${op} key=${key} ${describeProviderFailure(err)}`);
565
+ }
566
+ var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
567
+ "ECONNREFUSED",
568
+ "ECONNRESET",
569
+ "ECONNABORTED",
570
+ "ENOTFOUND",
571
+ "EAI_AGAIN",
572
+ "EHOSTUNREACH",
573
+ "ENETUNREACH",
574
+ "EPIPE",
575
+ "ETIMEDOUT"
576
+ ]);
577
+ var UNREACHABLE_IN_MESSAGE = new RegExp(
578
+ `^(?:AWS SDK error wrapper for \\w+: )?(?:(?:connect|read|write|getaddrinfo) (?:${[...UNREACHABLE_CODES].join("|")})\\b|socket hang up)`
579
+ );
580
+ var ADDRESSES_FAILED = "AWS SDK error wrapper for AggregateError";
581
+ var CREDENTIAL_CODES = /* @__PURE__ */ new Set([
582
+ "InvalidAccessKeyId",
583
+ "SignatureDoesNotMatch"
584
+ ]);
585
+ function cutConnection(failure, noAnswer) {
586
+ const codes = [failure.code, failure.cause?.code];
587
+ if (Array.isArray(failure.errors)) {
588
+ codes.push(...failure.errors.map((inner) => inner.code));
589
+ }
590
+ if (codes.some((code) => typeof code === "string" && UNREACHABLE_CODES.has(code))) {
591
+ return true;
592
+ }
593
+ const message = typeof failure.message === "string" ? failure.message : "";
594
+ return noAnswer && (UNREACHABLE_IN_MESSAGE.test(message) || message.startsWith(ADDRESSES_FAILED));
595
+ }
596
+ function providerFailureReason(err) {
597
+ const failure = err ?? {};
598
+ const status = failure.$metadata?.httpStatusCode;
599
+ if (failure.name === "TimeoutError" && failure.code === "ETIMEDOUT") {
600
+ return "timeout";
601
+ }
602
+ if (cutConnection(failure, status === void 0)) {
603
+ return "unreachable";
604
+ }
605
+ if (failure.name === "TimeoutError") {
606
+ return "timeout";
607
+ }
608
+ if (typeof status === "number" && status >= 500 && status !== 501) {
609
+ return "provider-error";
610
+ }
611
+ const awsCode = failure.Code ?? failure.name;
612
+ if (status === 403 && typeof awsCode === "string" && CREDENTIAL_CODES.has(awsCode)) {
613
+ return "credentials-refused";
614
+ }
615
+ return "rejected";
616
+ }
617
+ function classifyProviderFailure(err) {
618
+ const reason = providerFailureReason(err);
619
+ if (reason === "credentials-refused") {
620
+ return "credentials-refused";
621
+ }
622
+ return reason === "rejected" ? "other" : "unavailable";
623
+ }
624
+ function providerFailureStatus(err) {
625
+ const failure = classifyProviderFailure(err);
626
+ if (failure === "unavailable") {
627
+ return common.HttpStatus.SERVICE_UNAVAILABLE;
628
+ }
629
+ return failure === "credentials-refused" ? common.HttpStatus.INTERNAL_SERVER_ERROR : void 0;
630
+ }
631
+
632
+ // src/server/errors/aws-error-mapper.ts
455
633
  function mapAwsError(err, context) {
456
634
  const e = err ?? {};
457
635
  const httpStatus = e.$metadata?.httpStatusCode;
@@ -462,7 +640,8 @@ function mapAwsError(err, context) {
462
640
  awsCode,
463
641
  httpStatus,
464
642
  requestId,
465
- awsMessage: e.message
643
+ // A fixed word, never what the driver or the provider wrote.
644
+ reason: providerFailureReason(err)
466
645
  };
467
646
  if (awsCode === "NoSuchBucket") {
468
647
  return new StorageException(
@@ -479,7 +658,11 @@ function mapAwsError(err, context) {
479
658
  );
480
659
  }
481
660
  if (httpStatus === 304) {
482
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED, common.HttpStatus.NOT_MODIFIED, details);
661
+ return new StorageException(
662
+ STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED,
663
+ common.HttpStatus.NOT_MODIFIED,
664
+ details
665
+ );
483
666
  }
484
667
  if (httpStatus === 412) {
485
668
  return new StorageException(
@@ -489,11 +672,17 @@ function mapAwsError(err, context) {
489
672
  );
490
673
  }
491
674
  if (e.name === "TimeoutError") {
492
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, details);
675
+ logProviderFailure(err, context);
676
+ return new StorageException(
677
+ STORAGE_ERROR_CODES.STORAGE_TIMEOUT,
678
+ void 0,
679
+ details
680
+ );
493
681
  }
682
+ logProviderFailure(err, context);
494
683
  return new StorageException(
495
684
  STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR,
496
- common.HttpStatus.BAD_GATEWAY,
685
+ providerFailureStatus(err),
497
686
  details
498
687
  );
499
688
  }
@@ -522,10 +711,18 @@ function mapLifecycleError(err, context) {
522
711
  const status = e.$metadata?.httpStatusCode ?? 0;
523
712
  const details = mapped.getResponse().error.details;
524
713
  if (UNSUPPORTED_NAMES.has(name) || UNSUPPORTED_STATUSES.has(status)) {
525
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED, void 0, details);
714
+ return new StorageException(
715
+ STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED,
716
+ void 0,
717
+ details
718
+ );
526
719
  }
527
720
  if (REJECTED_NAMES.has(name)) {
528
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED, void 0, details);
721
+ return new StorageException(
722
+ STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED,
723
+ void 0,
724
+ details
725
+ );
529
726
  }
530
727
  return mapped;
531
728
  }
@@ -542,9 +739,9 @@ function ruleInvalid(reason) {
542
739
  reason
543
740
  });
544
741
  }
545
- function assertDays(field, value) {
742
+ function assertDays(field2, value) {
546
743
  if (!Number.isInteger(value) || value < 1) {
547
- throw ruleInvalid(`${field} must be an integer of at least 1`);
744
+ throw ruleInvalid(`${field2} must be an integer of at least 1`);
548
745
  }
549
746
  }
550
747
  exports.BucketLifecycleService = class BucketLifecycleService {
@@ -862,6 +1059,25 @@ async function readStreamUpTo(source, maxBytes) {
862
1059
  }
863
1060
  return Buffer.concat(chunks);
864
1061
  }
1062
+ async function readStream(source) {
1063
+ const chunks = [];
1064
+ for await (const chunk of source) {
1065
+ chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
1066
+ }
1067
+ return Buffer.concat(chunks);
1068
+ }
1069
+ function toUploadBody(body) {
1070
+ if (typeof body === "string") {
1071
+ return Buffer.from(body, "utf8");
1072
+ }
1073
+ if (body instanceof ArrayBuffer) {
1074
+ return Buffer.from(body);
1075
+ }
1076
+ if (ArrayBuffer.isView(body) && !(body instanceof Uint8Array)) {
1077
+ return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
1078
+ }
1079
+ return body;
1080
+ }
865
1081
 
866
1082
  // src/server/utils/mime-match.ts
867
1083
  var SINGLE_MEDIA_TYPE = /^[ \t]*[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+[ \t]*(?:;[\t \x21-\x2B\x2D-\x7E]*)?$/;
@@ -1044,7 +1260,7 @@ var FileScannerService = class {
1044
1260
  }
1045
1261
  const result = await this.scanner.scan(input);
1046
1262
  if (result.status === "infected") {
1047
- this.logger.warn(`Infected file detected: key=${input.key} engine=${result.engine} threat=${result.threat ?? "unknown"}`);
1263
+ this.logger.warn(`Infected file detected: key=${logValue(input.key)} engine=${logValue(result.engine)} threat=${logValue(result.threat ?? "unknown")}`);
1048
1264
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_SCAN_INFECTED, void 0, {
1049
1265
  engine: result.engine,
1050
1266
  threat: result.threat,
@@ -1058,7 +1274,7 @@ var FileScannerService = class {
1058
1274
  details: result.details
1059
1275
  });
1060
1276
  }
1061
- this.logger.warn(`Inconclusive scan result accepted: key=${input.key} engine=${result.engine}`);
1277
+ this.logger.warn(`Inconclusive scan result accepted: key=${logValue(input.key)} engine=${logValue(result.engine)}`);
1062
1278
  }
1063
1279
  return result;
1064
1280
  }
@@ -1068,22 +1284,6 @@ FileScannerService = __decorateClass([
1068
1284
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
1069
1285
  __decorateParam(1, common.Inject(BYMAX_STORAGE_FILE_SCANNER))
1070
1286
  ], FileScannerService);
1071
-
1072
- // src/server/utils/describe-error.ts
1073
- var NON_PRINTABLE_REJECTION = "non-printable rejection value";
1074
- function describeError(value) {
1075
- try {
1076
- if (typeof value === "object" && value !== null) {
1077
- const message = value.message;
1078
- if (typeof message === "string") {
1079
- return message;
1080
- }
1081
- }
1082
- return String(value);
1083
- } catch {
1084
- return NON_PRINTABLE_REJECTION;
1085
- }
1086
- }
1087
1287
  var SourceIdleError = class extends Error {
1088
1288
  constructor(idleMs) {
1089
1289
  super(`The upload source delivered no bytes for ${String(idleMs)} ms`);
@@ -1109,7 +1309,7 @@ function withinIdleTime(next, idleMs) {
1109
1309
  );
1110
1310
  });
1111
1311
  }
1112
- function withIdleTimeout(source, idleMs) {
1312
+ function withIdleTimeout(source, idleMs, toError) {
1113
1313
  const iterator = source[Symbol.asyncIterator]();
1114
1314
  const wrapper = new stream.Readable({
1115
1315
  objectMode: false,
@@ -1122,7 +1322,7 @@ function withIdleTimeout(source, idleMs) {
1122
1322
  wrapper.push(step.done === true ? null : step.value);
1123
1323
  },
1124
1324
  (error) => {
1125
- wrapper.destroy(error);
1325
+ wrapper.destroy(toError ? toError(error) : error);
1126
1326
  }
1127
1327
  );
1128
1328
  },
@@ -1140,25 +1340,71 @@ function guardIdleBody(body, idleMs) {
1140
1340
  }
1141
1341
  return idleMs === 0 ? body : withIdleTimeout(body, idleMs);
1142
1342
  }
1343
+ var SizeLimitError = class extends Error {
1344
+ constructor(limitBytes, kind) {
1345
+ super(`The upload body is longer than ${String(limitBytes)} bytes`);
1346
+ this.limitBytes = limitBytes;
1347
+ this.kind = kind;
1348
+ this.name = "SizeLimitError";
1349
+ }
1350
+ limitBytes;
1351
+ kind;
1352
+ };
1353
+ function withSizeLimit(source, limitBytes, kind) {
1354
+ let seen = 0;
1355
+ const guard = new stream.Transform({
1356
+ transform(chunk, _encoding, callback) {
1357
+ seen += Buffer.byteLength(chunk);
1358
+ if (seen > limitBytes) {
1359
+ callback(new SizeLimitError(limitBytes, kind));
1360
+ return;
1361
+ }
1362
+ callback(null, chunk);
1363
+ }
1364
+ });
1365
+ stream.pipeline(source, guard, () => void 0);
1366
+ return guard;
1367
+ }
1368
+
1369
+ // src/server/errors/size-limit-exception.ts
1370
+ function sizeLimitException(limitBytes, kind, context) {
1371
+ const bound = kind === "declared" ? { declaredSize: limitBytes } : { maxSize: limitBytes };
1372
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_SIZE_EXCEEDED, void 0, {
1373
+ ...context,
1374
+ ...bound
1375
+ });
1376
+ }
1377
+ function mapSizeLimitError(err, context) {
1378
+ if (!(err instanceof SizeLimitError)) {
1379
+ return void 0;
1380
+ }
1381
+ return sizeLimitException(err.limitBytes, err.kind, context);
1382
+ }
1143
1383
 
1144
1384
  // src/server/errors/multipart-error-mapper.ts
1145
1385
  var ABORT_FAILED_MESSAGE = "Multipart upload failed and could not be aborted";
1146
1386
  function mapMultipartError(err, context) {
1147
1387
  if (err instanceof SourceIdleError) {
1148
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, {
1388
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, void 0, {
1149
1389
  ...context,
1150
1390
  phase: "source-idle",
1151
1391
  idleMs: err.idleMs
1152
1392
  });
1153
1393
  }
1394
+ const tooLong = mapSizeLimitError(err, context);
1395
+ if (tooLong) {
1396
+ return tooLong;
1397
+ }
1154
1398
  const bucketMissing = mapAwsError(err, context);
1155
1399
  if (bucketMissing.code === STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND) {
1156
1400
  return bucketMissing;
1157
1401
  }
1158
1402
  return new StorageException(
1159
1403
  STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED,
1160
- void 0,
1161
- { ...context, awsMessage: describeError(err) },
1404
+ // An outage ends the upload as an outage; any other cause is a failure of the upload itself.
1405
+ providerFailureStatus(err),
1406
+ // A fixed word, never what the driver or the provider wrote.
1407
+ { ...context, reason: providerFailureReason(err) },
1162
1408
  // The code's message says the upload was aborted; it is not, when the abort itself failed.
1163
1409
  context.abort === "failed" ? ABORT_FAILED_MESSAGE : void 0
1164
1410
  );
@@ -1167,43 +1413,149 @@ function knownStatus(error) {
1167
1413
  const name = common.HttpStatus[error.getStatus()];
1168
1414
  return name === void 0 ? void 0 : common.HttpStatus[name];
1169
1415
  }
1170
- function describeCleanupError(error) {
1416
+ function cleanupErrorCode(error) {
1417
+ return error instanceof StorageException ? error.code : "UNKNOWN";
1418
+ }
1419
+ function describeCleanupFailure(error) {
1171
1420
  if (!(error instanceof StorageException)) {
1172
1421
  return describeError(error);
1173
1422
  }
1174
- const body = error.getResponse();
1175
- const awsMessage = body.error?.details?.awsMessage;
1176
- return typeof awsMessage === "string" ? `${error.code}: ${awsMessage}` : error.code;
1423
+ return error.code;
1177
1424
  }
1178
1425
  function withCleanupFailure(scanError, keys, cleanupError) {
1179
1426
  if (!(scanError instanceof StorageException)) {
1180
1427
  return scanError;
1181
1428
  }
1182
1429
  const body = scanError.getResponse();
1183
- return new StorageException(scanError.code, knownStatus(scanError), {
1184
- ...body.error?.details ?? {},
1185
- key: keys.key,
1186
- storedKey: keys.storedKey,
1187
- cleanup: "failed",
1188
- cleanupError: describeCleanupError(cleanupError)
1430
+ return new StorageException(
1431
+ scanError.code,
1432
+ knownStatus(scanError),
1433
+ {
1434
+ ...body.error?.details ?? {},
1435
+ key: keys.key,
1436
+ storedKey: keys.storedKey,
1437
+ cleanup: "failed",
1438
+ cleanupError: cleanupErrorCode(cleanupError)
1439
+ }
1440
+ );
1441
+ }
1442
+ var CLEANUP_DEADLINE_MS = 1e4;
1443
+ function reasonName(signal) {
1444
+ const reason = signal.reason;
1445
+ if (typeof reason === "object" && reason !== null && "name" in reason && typeof reason.name === "string") {
1446
+ return reason.name;
1447
+ }
1448
+ return "AbortError";
1449
+ }
1450
+ function requestAborted(signal, context) {
1451
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED, void 0, {
1452
+ ...context,
1453
+ reason: reasonName(signal)
1454
+ });
1455
+ }
1456
+ function throwIfAborted(signal, context) {
1457
+ if (signal?.aborted) {
1458
+ throw requestAborted(signal, context);
1459
+ }
1460
+ }
1461
+ function sendOptions(signal) {
1462
+ return signal ? { abortSignal: signal } : void 0;
1463
+ }
1464
+ function failureOrAbort(signal, context, mapped) {
1465
+ return signal?.aborted ? requestAborted(signal, context) : mapped;
1466
+ }
1467
+ function bindToSignal(client, signal) {
1468
+ let created = Promise.resolve(void 0);
1469
+ const bound = new Proxy(client, {
1470
+ get(target, property) {
1471
+ if (property !== "send") {
1472
+ const value = Reflect.get(target, property, target);
1473
+ return value;
1474
+ }
1475
+ return (command, options) => {
1476
+ if (command instanceof clientS3.CreateMultipartUploadCommand) {
1477
+ const sent = target.send(command, options);
1478
+ created = sent.then(
1479
+ (response) => response.UploadId,
1480
+ () => void 0
1481
+ );
1482
+ return sent;
1483
+ }
1484
+ return target.send(command, { ...options, abortSignal: signal });
1485
+ };
1486
+ }
1487
+ });
1488
+ return { client: bound, createdUploadId: () => created };
1489
+ }
1490
+ async function within(promise, ms) {
1491
+ let timer;
1492
+ const late = new Promise((resolve) => {
1493
+ timer = setTimeout(() => {
1494
+ resolve(void 0);
1495
+ }, ms);
1189
1496
  });
1497
+ try {
1498
+ return await Promise.race([promise, late]);
1499
+ } finally {
1500
+ clearTimeout(timer);
1501
+ }
1190
1502
  }
1191
- async function closeMultipartUpload(client, bucket, key, uploadId) {
1503
+ async function abortable(work, signal, context) {
1504
+ if (!signal) {
1505
+ return work;
1506
+ }
1507
+ if (signal.aborted) {
1508
+ work.catch(() => void 0);
1509
+ throw requestAborted(signal, context);
1510
+ }
1511
+ const release = new AbortController();
1512
+ const aborted = new Promise((_resolve, reject) => {
1513
+ signal.addEventListener(
1514
+ "abort",
1515
+ () => {
1516
+ reject(requestAborted(signal, context));
1517
+ },
1518
+ // Stryker disable next-line BooleanLiteral: `release.abort()` in the `finally` removes the listener, and a signal aborts once, so `once` is not observable (equivalent).
1519
+ { once: true, signal: release.signal }
1520
+ );
1521
+ });
1522
+ try {
1523
+ return await Promise.race([work, aborted]);
1524
+ } finally {
1525
+ release.abort();
1526
+ work.catch(() => void 0);
1527
+ }
1528
+ }
1529
+
1530
+ // src/server/utils/multipart-abort.ts
1531
+ async function closeMultipartUpload(client, bucket, key, uploadId, onFailure) {
1192
1532
  if (uploadId === void 0) {
1193
1533
  return {};
1194
1534
  }
1195
1535
  try {
1196
1536
  await client.send(
1197
- new clientS3.AbortMultipartUploadCommand({ Bucket: bucket, Key: key, UploadId: uploadId })
1537
+ new clientS3.AbortMultipartUploadCommand({ Bucket: bucket, Key: key, UploadId: uploadId }),
1538
+ { abortSignal: AbortSignal.timeout(CLEANUP_DEADLINE_MS) }
1198
1539
  );
1199
1540
  return { abort: "completed" };
1200
1541
  } catch (err) {
1201
1542
  if (err?.name === "NoSuchUpload") {
1202
1543
  return { abort: "completed" };
1203
1544
  }
1204
- return { abort: "failed", abortError: describeError(err) };
1545
+ onFailure?.(err);
1546
+ return { abort: "failed" };
1205
1547
  }
1206
1548
  }
1549
+ function closeWhenCreated(client, bucket, key, created, onFailure) {
1550
+ void created.then((uploadId) => closeMultipartUpload(client, bucket, key, uploadId, onFailure));
1551
+ }
1552
+ function abortFailureLogger(logger2, key) {
1553
+ return (err) => {
1554
+ logger2.warn(
1555
+ `Multipart abort failed, the upload stays open on the provider: ${logValue(key)} ${describeProviderFailure(err)}`
1556
+ );
1557
+ };
1558
+ }
1207
1559
  async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
1208
1560
  const deleted = [];
1209
1561
  const failed = [];
@@ -1224,14 +1576,16 @@ async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
1224
1576
  if (failure.Key !== void 0) {
1225
1577
  failed.push({
1226
1578
  key: stripPrefix(failure.Key),
1227
- error: `${failure.Code ?? "Unknown"}: ${failure.Message ?? ""}`
1579
+ // The provider's code, which a caller can branch on; its sentence is not repeated.
1580
+ error: failure.Code ?? "Unknown"
1228
1581
  });
1229
1582
  }
1230
1583
  }
1231
1584
  } catch (err) {
1232
- const message = describeError(err);
1585
+ logProviderFailure(err, { op: "deleteMany" });
1586
+ const reason = providerFailureReason(err);
1233
1587
  for (const key of chunk) {
1234
- failed.push({ key: stripPrefix(key), error: message });
1588
+ failed.push({ key: stripPrefix(key), error: reason });
1235
1589
  }
1236
1590
  }
1237
1591
  return { deleted, failed };
@@ -1239,7 +1593,12 @@ async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
1239
1593
  function mapBucketCheckError(err, context) {
1240
1594
  const failure = err ?? {};
1241
1595
  const status = failure.$metadata?.httpStatusCode;
1242
- const details = { ...context, httpStatus: status, awsCode: failure.name };
1596
+ const details = {
1597
+ ...context,
1598
+ httpStatus: status,
1599
+ awsCode: failure.name,
1600
+ reason: providerFailureReason(err)
1601
+ };
1243
1602
  if (status === 301 || failure.name === "PermanentRedirect") {
1244
1603
  return new StorageException(
1245
1604
  STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH,
@@ -1322,6 +1681,141 @@ function pickUploadStrategy(body, declaredSize, thresholdBytes) {
1322
1681
  return "single-shot";
1323
1682
  }
1324
1683
 
1684
+ // src/server/utils/upload-body.ts
1685
+ function withBytesBody(options) {
1686
+ const body = toUploadBody(options.body);
1687
+ return isBufferLike(body) ? { ...options, body, size: body.byteLength } : { ...options, body };
1688
+ }
1689
+ function boundStreamSize(body, declaredSize, options) {
1690
+ const limit = declaredSize ?? options.validation?.maxSizeBytes;
1691
+ const singleShot = pickUploadStrategy(body, declaredSize, options.multipart.thresholdBytes) === "single-shot";
1692
+ if (isBufferLike(body) || singleShot || limit === void 0) {
1693
+ return body;
1694
+ }
1695
+ return withSizeLimit(body, limit, declaredSize === void 0 ? "max" : "declared");
1696
+ }
1697
+
1698
+ // src/server/utils/download-body.ts
1699
+ function guardDownloadBody(body, idleMs, context, signal) {
1700
+ if (idleMs === 0) {
1701
+ return body;
1702
+ }
1703
+ return withIdleTimeout(body, idleMs, (error) => {
1704
+ if (error instanceof SourceIdleError) {
1705
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, void 0, {
1706
+ ...context,
1707
+ phase: "body-idle",
1708
+ idleMs: error.idleMs
1709
+ });
1710
+ }
1711
+ return signal?.aborted ? requestAborted(signal, context) : error;
1712
+ });
1713
+ }
1714
+
1715
+ // src/server/utils/public-url.ts
1716
+ function buildPublicUrl(options, finalKey, bucket) {
1717
+ const base = trimTrailingSlashes(options.cdnBaseUrl ?? options.publicBaseUrl);
1718
+ return baseCarriesBucket(base, bucket) ? `${base}/${finalKey}` : `${base}/${bucket}/${finalKey}`;
1719
+ }
1720
+ function baseCarriesBucket(base, bucket) {
1721
+ const schemeless = base.replace(/^[a-z][a-z\d+.-]*:\/\//i, "");
1722
+ const pathStart = schemeless.indexOf("/");
1723
+ const authority = pathStart === -1 ? schemeless : schemeless.slice(0, pathStart);
1724
+ const path = pathStart === -1 ? "" : schemeless.slice(pathStart);
1725
+ const leadingHostLabel = authority.split(".")[0];
1726
+ const pathSegments = path.split("/").filter((segment) => segment.length > 0);
1727
+ return leadingHostLabel === bucket || pathSegments.includes(bucket);
1728
+ }
1729
+
1730
+ // src/server/utils/upload-support.ts
1731
+ function normalizeScanBody(body) {
1732
+ return Buffer.isBuffer(body) ? body : Buffer.from(body);
1733
+ }
1734
+ function forwardProgress(uploader, onProgress) {
1735
+ if (!onProgress) return;
1736
+ uploader.on("httpUploadProgress", (event) => {
1737
+ emitProgress(onProgress, event.loaded, event.total, event.part);
1738
+ });
1739
+ }
1740
+ function normalizeSingleShotBody(body) {
1741
+ if (isBufferLike(body)) {
1742
+ return Buffer.isBuffer(body) ? body : Buffer.from(body);
1743
+ }
1744
+ return body;
1745
+ }
1746
+ function buildUploadResult(keyResolver, options, params) {
1747
+ return {
1748
+ key: keyResolver.stripPrefix(params.finalKey),
1749
+ bucket: params.bucket,
1750
+ etag: params.etag ?? "",
1751
+ contentType: params.contentType,
1752
+ publicUrl: buildPublicUrl(options, params.finalKey, params.bucket),
1753
+ multipart: params.multipart,
1754
+ fromIdempotencyCache: false,
1755
+ ...params.size !== void 0 ? { size: params.size } : {},
1756
+ ...params.versionId !== void 0 ? { versionId: params.versionId } : {}
1757
+ };
1758
+ }
1759
+ function emitProgress(onProgress, loaded, total, part) {
1760
+ onProgress({
1761
+ loaded: loaded ?? 0,
1762
+ ...total !== void 0 ? { total } : {},
1763
+ ...part !== void 0 ? { part } : {}
1764
+ });
1765
+ }
1766
+ function putObjectHeaders(options, resolved, finalKey, bucket) {
1767
+ return {
1768
+ Bucket: bucket,
1769
+ Key: finalKey,
1770
+ ContentType: options.contentType,
1771
+ CacheControl: buildCacheControl(options.cacheControl, resolved.defaultCacheControl),
1772
+ ContentDisposition: buildContentDisposition(
1773
+ options.contentDisposition,
1774
+ resolved.defaultContentDisposition
1775
+ ),
1776
+ // `public-read` only takes effect on buckets that allow ACLs (see header-utils).
1777
+ ACL: buildACL(options.publicRead, resolved.defaultPublicRead),
1778
+ Metadata: options.metadata,
1779
+ ...buildSSE(options.serverSideEncryption, options.kmsKeyId, resolved)
1780
+ };
1781
+ }
1782
+ function validationInput(options, finalKey) {
1783
+ return {
1784
+ key: finalKey,
1785
+ body: options.body,
1786
+ contentType: options.contentType,
1787
+ ...options.size !== void 0 ? { size: options.size } : {},
1788
+ ...options.metadata !== void 0 ? { metadata: options.metadata } : {},
1789
+ cacheControl: options.cacheControl,
1790
+ contentDisposition: options.contentDisposition,
1791
+ kmsKeyId: options.kmsKeyId
1792
+ };
1793
+ }
1794
+
1795
+ // src/server/utils/download-buffer.ts
1796
+ function assertMaxBytes(maxBytes) {
1797
+ if (maxBytes !== void 0 && (typeof maxBytes !== "number" || !Number.isInteger(maxBytes) || maxBytes < 1)) {
1798
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1799
+ reason: "maxBytes must be an integer >= 1"
1800
+ });
1801
+ }
1802
+ }
1803
+ async function readDownloadBody(stream, metadata, maxBytes) {
1804
+ if (maxBytes === void 0) {
1805
+ return readStream(stream);
1806
+ }
1807
+ const context = { key: metadata.key, bucket: metadata.bucket };
1808
+ if (metadata.size > maxBytes) {
1809
+ destroyStream(stream);
1810
+ throw sizeLimitException(maxBytes, "max", { ...context, contentLength: metadata.size });
1811
+ }
1812
+ const buffer = await readStreamUpTo(stream, maxBytes);
1813
+ if (buffer === void 0) {
1814
+ throw sizeLimitException(maxBytes, "max", context);
1815
+ }
1816
+ return buffer;
1817
+ }
1818
+
1325
1819
  // src/server/services/storage.service.ts
1326
1820
  var MAX_LIST_KEYS = 1e3;
1327
1821
  var DELETE_BATCH_LIMIT = 1e3;
@@ -1365,17 +1859,19 @@ exports.StorageService = class StorageService {
1365
1859
  }
1366
1860
  }
1367
1861
  /** The upload itself; `upload()` destroys a stream body when this rejects. */
1368
- async uploadOwningBody(options) {
1862
+ async uploadOwningBody(requested) {
1369
1863
  this.assertConfigured();
1370
- const rawBody = options.body;
1864
+ const rawBody = requested.body;
1371
1865
  if (rawBody === void 0 || rawBody === null) {
1372
1866
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BODY_MISSING);
1373
1867
  }
1868
+ const options = withBytesBody(requested);
1374
1869
  if (!options.contentType) {
1375
1870
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_CONTENT_TYPE_REQUIRED);
1376
1871
  }
1377
1872
  const finalKey = this.keyResolver.normalize(options.key);
1378
1873
  const bucket = this.resolveBucket(options.bucket);
1874
+ throwIfAborted(options.abortSignal, { key: finalKey, bucket, op: "upload" });
1379
1875
  if (options.idempotencyKey) {
1380
1876
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
1381
1877
  const cached = this.idempotencyCache.get(cacheKey);
@@ -1385,32 +1881,28 @@ exports.StorageService = class StorageService {
1385
1881
  return { ...cached, fromIdempotencyCache: true };
1386
1882
  }
1387
1883
  }
1388
- const validated = await this.validation.validate({
1389
- key: finalKey,
1390
- body: options.body,
1391
- contentType: options.contentType,
1392
- ...options.size !== void 0 ? { size: options.size } : {},
1393
- ...options.metadata !== void 0 ? { metadata: options.metadata } : {},
1394
- cacheControl: options.cacheControl,
1395
- contentDisposition: options.contentDisposition,
1396
- kmsKeyId: options.kmsKeyId
1397
- });
1398
- const body = await this.bufferForPreUploadScan(validated.body, finalKey);
1884
+ const context = { key: finalKey, bucket, op: "upload" };
1885
+ const signal = options.abortSignal;
1886
+ const input = validationInput(options, finalKey);
1887
+ const validated = await abortable(this.validation.validate(input), signal, context);
1888
+ const scanned = await abortable(
1889
+ this.bufferForPreUploadScan(validated.body, finalKey),
1890
+ signal,
1891
+ context
1892
+ );
1893
+ const body = boundStreamSize(scanned, options.size, this.options);
1399
1894
  const validatedOptions = { ...options, body };
1400
- await this.runPreUploadScan(body, finalKey, bucket, options);
1895
+ await abortable(this.runPreUploadScan(body, finalKey, bucket, options), signal, context);
1896
+ throwIfAborted(signal, context);
1401
1897
  const strategy = pickUploadStrategy(
1402
1898
  validatedOptions.body,
1403
1899
  validatedOptions.size,
1404
1900
  this.options.multipart.thresholdBytes
1405
1901
  );
1406
1902
  const result = strategy === "multipart" ? await this.uploadMultipart(validatedOptions, finalKey, bucket) : await this.uploadSingleShot(validatedOptions, finalKey, bucket);
1407
- await this.runPostUploadScan(finalKey, bucket, options);
1408
- if (options.idempotencyKey) {
1409
- this.idempotencyCache.set(
1410
- this.idempotencyCache.computeKey(options.idempotencyKey, finalKey),
1411
- result
1412
- );
1413
- }
1903
+ const stored = { ...context, stored: true };
1904
+ await abortable(this.runPostUploadScan(finalKey, bucket, options), signal, stored);
1905
+ this.rememberUpload(options, finalKey, result);
1414
1906
  return result;
1415
1907
  }
1416
1908
  /**
@@ -1449,20 +1941,20 @@ exports.StorageService = class StorageService {
1449
1941
  }
1450
1942
  await this.scanner.scan({
1451
1943
  mode: "pre-upload",
1452
- body: this.normalizeScanBody(body),
1944
+ body: normalizeScanBody(body),
1453
1945
  key: finalKey,
1454
1946
  bucket,
1455
1947
  contentType: options.contentType,
1456
1948
  ...options.size !== void 0 ? { size: options.size } : {}
1457
1949
  });
1458
1950
  }
1459
- /**
1460
- * Coerces the scan body to a `Buffer` so the scanner always receives its declared
1461
- * contract type. In pre-upload mode a stream has already been buffered by
1462
- * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
1463
- */
1464
- normalizeScanBody(body) {
1465
- return Buffer.isBuffer(body) ? body : Buffer.from(body);
1951
+ /** Remembers the result of an upload under its idempotency key, when it has one. */
1952
+ rememberUpload(options, finalKey, result) {
1953
+ if (!options.idempotencyKey) return;
1954
+ this.idempotencyCache.set(
1955
+ this.idempotencyCache.computeKey(options.idempotencyKey, finalKey),
1956
+ result
1957
+ );
1466
1958
  }
1467
1959
  /**
1468
1960
  * Runs a post-upload scan. On infection, deletes the just-uploaded object
@@ -1483,11 +1975,11 @@ exports.StorageService = class StorageService {
1483
1975
  } catch (scanErr) {
1484
1976
  const key = this.keyResolver.stripPrefix(finalKey);
1485
1977
  try {
1486
- await this.delete(key, { bucket });
1978
+ await this.delete(key, { bucket, abortSignal: AbortSignal.timeout(CLEANUP_DEADLINE_MS) });
1487
1979
  } catch (deleteErr) {
1488
1980
  this.logger.error(
1489
- `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${finalKey}`,
1490
- describeError(deleteErr)
1981
+ `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${logValue(finalKey)}`,
1982
+ logValue(describeCleanupFailure(deleteErr))
1491
1983
  );
1492
1984
  throw withCleanupFailure(scanErr, { key, storedKey: finalKey }, deleteErr);
1493
1985
  }
@@ -1506,11 +1998,16 @@ exports.StorageService = class StorageService {
1506
1998
  this.assertConfigured();
1507
1999
  const finalKey = this.keyResolver.normalize(key);
1508
2000
  const bucket = this.resolveBucket(options?.bucket);
2001
+ const context = { key: finalKey, bucket, op: "head" };
2002
+ throwIfAborted(options?.abortSignal, context);
1509
2003
  try {
1510
- const response = await this.s3Provider.getClient().send(new clientS3.HeadObjectCommand({ Bucket: bucket, Key: finalKey }));
2004
+ const response = await this.s3Provider.getClient().send(
2005
+ new clientS3.HeadObjectCommand({ Bucket: bucket, Key: finalKey }),
2006
+ sendOptions(options?.abortSignal)
2007
+ );
1511
2008
  return this.toObjectMetadata(response, finalKey, bucket);
1512
2009
  } catch (err) {
1513
- throw mapAwsError(err, { key: finalKey, bucket, op: "head" });
2010
+ throw failureOrAbort(options?.abortSignal, context, mapAwsError(err, context));
1514
2011
  }
1515
2012
  }
1516
2013
  /**
@@ -1529,7 +2026,12 @@ exports.StorageService = class StorageService {
1529
2026
  if (err instanceof StorageException && err.code === STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
1530
2027
  return false;
1531
2028
  }
1532
- this.logger.warn(`exists() \u2014 treating a non-404 error as "false": ${describeError(err)}`);
2029
+ if (err instanceof StorageException && err.code === STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED) {
2030
+ throw err;
2031
+ }
2032
+ this.logger.warn(
2033
+ `exists() \u2014 treating a non-404 error as "false": ${logValue(describeError(err))}`
2034
+ );
1533
2035
  return false;
1534
2036
  }
1535
2037
  }
@@ -1544,7 +2046,7 @@ exports.StorageService = class StorageService {
1544
2046
  getPublicUrl(key, options) {
1545
2047
  const finalKey = this.keyResolver.normalize(key);
1546
2048
  const bucket = this.resolveBucket(options?.bucket);
1547
- return this.buildPublicUrl(finalKey, bucket);
2049
+ return buildPublicUrl(this.options, finalKey, bucket);
1548
2050
  }
1549
2051
  /**
1550
2052
  * Streams an object. The returned `stream` is a Node `Readable` consumable via
@@ -1557,9 +2059,15 @@ exports.StorageService = class StorageService {
1557
2059
  */
1558
2060
  async download(options) {
1559
2061
  this.assertConfigured();
1560
- assertHeaderValues({ range: options.range, ifNoneMatch: options.ifNoneMatch, ifMatch: options.ifMatch });
2062
+ assertHeaderValues({
2063
+ range: options.range,
2064
+ ifNoneMatch: options.ifNoneMatch,
2065
+ ifMatch: options.ifMatch
2066
+ });
1561
2067
  const finalKey = this.keyResolver.normalize(options.key);
1562
2068
  const bucket = this.resolveBucket(options.bucket);
2069
+ const context = { key: finalKey, bucket, op: "download" };
2070
+ throwIfAborted(options.abortSignal, context);
1563
2071
  try {
1564
2072
  const response = await this.s3Provider.getClient().send(
1565
2073
  new clientS3.GetObjectCommand({
@@ -1568,7 +2076,8 @@ exports.StorageService = class StorageService {
1568
2076
  Range: options.range,
1569
2077
  IfNoneMatch: options.ifNoneMatch,
1570
2078
  IfMatch: options.ifMatch
1571
- })
2079
+ }),
2080
+ sendOptions(options.abortSignal)
1572
2081
  );
1573
2082
  if (!response.Body) {
1574
2083
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND, void 0, {
@@ -1576,26 +2085,33 @@ exports.StorageService = class StorageService {
1576
2085
  bucket
1577
2086
  });
1578
2087
  }
1579
- const stream = response.Body;
2088
+ const stream = guardDownloadBody(
2089
+ response.Body,
2090
+ this.options.bodyIdleTimeoutMs,
2091
+ { key: finalKey, bucket },
2092
+ options.abortSignal
2093
+ );
1580
2094
  return { stream, metadata: this.toObjectMetadata(response, finalKey, bucket) };
1581
2095
  } catch (err) {
1582
2096
  if (err instanceof StorageException) {
1583
2097
  throw err;
1584
2098
  }
1585
- throw mapAwsError(err, { key: finalKey, bucket, op: "download" });
2099
+ throw failureOrAbort(options.abortSignal, context, mapAwsError(err, context));
1586
2100
  }
1587
2101
  }
1588
2102
  /**
1589
- * Materializes an object fully into memory via the sdk-stream-mixin. NOT
1590
- * recommended for files larger than 10 MB — use {@link download} for those.
2103
+ * Reads an object fully into memory through the same idle-guarded stream as {@link download}.
2104
+ * Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
1591
2105
  *
1592
- * @param options - The download request.
2106
+ * @param options - The download request; `maxBytes` is the most bytes to hold.
1593
2107
  * @returns The object buffer and its metadata.
2108
+ * @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
2109
+ * bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
1594
2110
  */
1595
2111
  async downloadBuffer(options) {
2112
+ assertMaxBytes(options.maxBytes);
1596
2113
  const { stream, metadata } = await this.download(options);
1597
- const bytes = await stream.transformToByteArray();
1598
- return { buffer: Buffer.from(bytes), metadata };
2114
+ return { buffer: await readDownloadBody(stream, metadata, options.maxBytes), metadata };
1599
2115
  }
1600
2116
  /**
1601
2117
  * Deletes an object. Idempotent: a missing object is a no-op (logged as a
@@ -1608,14 +2124,19 @@ exports.StorageService = class StorageService {
1608
2124
  this.assertConfigured();
1609
2125
  const finalKey = this.keyResolver.normalize(key);
1610
2126
  const bucket = this.resolveBucket(options?.bucket);
2127
+ const context = { key: finalKey, bucket, op: "delete" };
2128
+ throwIfAborted(options?.abortSignal, context);
1611
2129
  try {
1612
- await this.s3Provider.getClient().send(new clientS3.DeleteObjectCommand({ Bucket: bucket, Key: finalKey }));
2130
+ await this.s3Provider.getClient().send(
2131
+ new clientS3.DeleteObjectCommand({ Bucket: bucket, Key: finalKey }),
2132
+ sendOptions(options?.abortSignal)
2133
+ );
1613
2134
  } catch (err) {
1614
- const mapped = mapAwsError(err, { key: finalKey, bucket, op: "delete" });
2135
+ const mapped = failureOrAbort(options?.abortSignal, context, mapAwsError(err, context));
1615
2136
  if (mapped.code !== STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
1616
2137
  throw mapped;
1617
2138
  }
1618
- this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${finalKey}`);
2139
+ this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${logValue(finalKey)}`);
1619
2140
  }
1620
2141
  this.idempotencyCache.invalidate(bucket, this.keyResolver.stripPrefix(finalKey));
1621
2142
  }
@@ -1633,10 +2154,12 @@ exports.StorageService = class StorageService {
1633
2154
  async checkBucket(options) {
1634
2155
  this.assertConfigured();
1635
2156
  const bucket = this.resolveBucket(options?.bucket);
2157
+ const context = { bucket, op: "checkBucket" };
2158
+ throwIfAborted(options?.abortSignal, context);
1636
2159
  try {
1637
- await this.s3Provider.getClient().send(new clientS3.HeadBucketCommand({ Bucket: bucket }));
2160
+ await this.s3Provider.getClient().send(new clientS3.HeadBucketCommand({ Bucket: bucket }), sendOptions(options?.abortSignal));
1638
2161
  } catch (err) {
1639
- throw mapBucketCheckError(err, { bucket, op: "checkBucket" });
2162
+ throw failureOrAbort(options?.abortSignal, context, mapBucketCheckError(err, context));
1640
2163
  }
1641
2164
  }
1642
2165
  /** Throws when the S3 client was never built (missing credentials). */
@@ -1653,26 +2176,6 @@ exports.StorageService = class StorageService {
1653
2176
  }
1654
2177
  return bucket;
1655
2178
  }
1656
- /** Builds a public URL, avoiding a duplicated bucket segment in the base. */
1657
- buildPublicUrl(finalKey, bucket) {
1658
- const base = trimTrailingSlashes(this.options.cdnBaseUrl ?? this.options.publicBaseUrl);
1659
- return this.baseCarriesBucket(base, bucket) ? `${base}/${finalKey}` : `${base}/${bucket}/${finalKey}`;
1660
- }
1661
- /**
1662
- * Reports whether the base URL already carries the bucket as a real segment —
1663
- * the leading host label (virtual-hosted-style `bucket.host`) or a path segment
1664
- * (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
1665
- * so `bucket="test"` is not matched by a `latest` elsewhere in the base.
1666
- */
1667
- baseCarriesBucket(base, bucket) {
1668
- const schemeless = base.replace(/^[a-z][a-z\d+.-]*:\/\//i, "");
1669
- const pathStart = schemeless.indexOf("/");
1670
- const authority = pathStart === -1 ? schemeless : schemeless.slice(0, pathStart);
1671
- const path = pathStart === -1 ? "" : schemeless.slice(pathStart);
1672
- const leadingHostLabel = authority.split(".")[0];
1673
- const pathSegments = path.split("/").filter((segment) => segment.length > 0);
1674
- return leadingHostLabel === bucket || pathSegments.includes(bucket);
1675
- }
1676
2179
  /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
1677
2180
  toObjectMetadata(response, finalKey, bucket) {
1678
2181
  return {
@@ -1693,27 +2196,16 @@ exports.StorageService = class StorageService {
1693
2196
  async uploadSingleShot(options, finalKey, bucket) {
1694
2197
  const total = options.size ?? getBodySize(options.body);
1695
2198
  const input = {
1696
- Bucket: bucket,
1697
- Key: finalKey,
1698
- Body: this.normalizeSingleShotBody(options.body),
1699
- ContentType: options.contentType,
1700
- ContentLength: total,
1701
- CacheControl: buildCacheControl(options.cacheControl, this.options.defaultCacheControl),
1702
- ContentDisposition: buildContentDisposition(
1703
- options.contentDisposition,
1704
- this.options.defaultContentDisposition
1705
- ),
1706
- // `public-read` only takes effect on buckets that allow ACLs (see header-utils).
1707
- ACL: buildACL(options.publicRead, this.options.defaultPublicRead),
1708
- Metadata: options.metadata,
1709
- ...buildSSE(options.serverSideEncryption, options.kmsKeyId, this.options)
2199
+ ...putObjectHeaders(options, this.options, finalKey, bucket),
2200
+ Body: normalizeSingleShotBody(options.body),
2201
+ ContentLength: total
1710
2202
  };
1711
2203
  try {
1712
- const response = await this.s3Provider.getClient().send(new clientS3.PutObjectCommand(input));
2204
+ const response = await this.s3Provider.getClient().send(new clientS3.PutObjectCommand(input), sendOptions(options.abortSignal));
1713
2205
  if (options.onProgress) {
1714
- this.emitProgress(options.onProgress, total, total);
2206
+ emitProgress(options.onProgress, total, total);
1715
2207
  }
1716
- return this.buildUploadResult({
2208
+ return buildUploadResult(this.keyResolver, this.options, {
1717
2209
  finalKey,
1718
2210
  bucket,
1719
2211
  etag: response.ETag,
@@ -1723,7 +2215,8 @@ exports.StorageService = class StorageService {
1723
2215
  multipart: false
1724
2216
  });
1725
2217
  } catch (err) {
1726
- throw mapAwsError(err, { key: finalKey, bucket, op: "upload-single" });
2218
+ const context = { key: finalKey, bucket, op: "upload-single" };
2219
+ throw failureOrAbort(options.abortSignal, context, mapAwsError(err, context));
1727
2220
  }
1728
2221
  }
1729
2222
  /**
@@ -1734,30 +2227,26 @@ exports.StorageService = class StorageService {
1734
2227
  */
1735
2228
  async uploadMultipart(options, finalKey, bucket) {
1736
2229
  const params = {
1737
- Bucket: bucket,
1738
- Key: finalKey,
1739
- Body: guardIdleBody(options.body, this.options.uploadIdleTimeoutMs),
1740
- ContentType: options.contentType,
1741
- CacheControl: buildCacheControl(options.cacheControl, this.options.defaultCacheControl),
1742
- ContentDisposition: buildContentDisposition(
1743
- options.contentDisposition,
1744
- this.options.defaultContentDisposition
1745
- ),
1746
- ACL: buildACL(options.publicRead, this.options.defaultPublicRead),
1747
- Metadata: options.metadata,
1748
- ...buildSSE(options.serverSideEncryption, options.kmsKeyId, this.options)
2230
+ ...putObjectHeaders(options, this.options, finalKey, bucket),
2231
+ Body: guardIdleBody(options.body, this.options.uploadIdleTimeoutMs)
1749
2232
  };
2233
+ const signal = options.abortSignal;
2234
+ const bound = signal ? bindToSignal(this.s3Provider.getClient(), signal) : void 0;
1750
2235
  const uploader = new libStorage.Upload({
1751
- client: this.s3Provider.getClient(),
2236
+ client: bound?.client ?? this.s3Provider.getClient(),
1752
2237
  params,
1753
2238
  queueSize: this.options.multipart.queueSize,
1754
2239
  partSize: this.options.multipart.partSizeBytes,
1755
2240
  leavePartsOnError: true
1756
2241
  });
1757
- this.forwardProgress(uploader, options.onProgress);
2242
+ forwardProgress(uploader, options.onProgress);
2243
+ const abortUpload = () => {
2244
+ void uploader.abort();
2245
+ };
2246
+ signal?.addEventListener("abort", abortUpload, { once: true });
1758
2247
  try {
1759
2248
  const response = await uploader.done();
1760
- return this.buildUploadResult({
2249
+ return buildUploadResult(this.keyResolver, this.options, {
1761
2250
  finalKey,
1762
2251
  bucket,
1763
2252
  etag: response.ETag,
@@ -1767,54 +2256,41 @@ exports.StorageService = class StorageService {
1767
2256
  multipart: true
1768
2257
  });
1769
2258
  } catch (err) {
1770
- return this.failMultipart(err, finalKey, bucket, uploader.uploadId);
2259
+ return await this.failMultipart(err, finalKey, bucket, {
2260
+ uploadId: uploader.uploadId,
2261
+ signal,
2262
+ createdUploadId: bound?.createdUploadId
2263
+ });
2264
+ } finally {
2265
+ signal?.removeEventListener("abort", abortUpload);
1771
2266
  }
1772
2267
  }
1773
- /** Relays the uploader's progress events to the caller's callback, when there is one. */
1774
- forwardProgress(uploader, onProgress) {
1775
- if (!onProgress) return;
1776
- uploader.on("httpUploadProgress", (event) => {
1777
- this.emitProgress(onProgress, event.loaded, event.total, event.part);
1778
- });
1779
- }
1780
- /** Aborts the multipart upload that failed, then throws the original failure with the outcome. */
1781
- async failMultipart(err, finalKey, bucket, uploadId) {
2268
+ /**
2269
+ * Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
2270
+ * the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
2271
+ * real failure into one. An upload id the provider answered late is waited for, within the cleanup
2272
+ * deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
2273
+ */
2274
+ async failMultipart(err, finalKey, bucket, upload) {
2275
+ const abortedBy = upload.signal?.aborted === true ? upload.signal : void 0;
2276
+ const client = this.s3Provider.getClient();
2277
+ const lookup = abortedBy ? upload.createdUploadId?.() : void 0;
2278
+ let uploadId = upload.uploadId;
2279
+ if (uploadId === void 0 && lookup) {
2280
+ uploadId = await within(lookup, CLEANUP_DEADLINE_MS);
2281
+ if (uploadId === void 0) {
2282
+ closeWhenCreated(client, bucket, finalKey, lookup, abortFailureLogger(this.logger, finalKey));
2283
+ }
2284
+ }
1782
2285
  const abort = await closeMultipartUpload(
1783
- this.s3Provider.getClient(),
2286
+ client,
1784
2287
  bucket,
1785
2288
  finalKey,
1786
- uploadId
2289
+ uploadId,
2290
+ abortFailureLogger(this.logger, finalKey)
1787
2291
  );
1788
- throw mapMultipartError(err, { key: finalKey, bucket, ...abort });
1789
- }
1790
- /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
1791
- normalizeSingleShotBody(body) {
1792
- if (isBufferLike(body)) {
1793
- return Buffer.isBuffer(body) ? body : Buffer.from(body);
1794
- }
1795
- return body;
1796
- }
1797
- /** Assembles an `UploadResult`, omitting optional fields that are absent. */
1798
- buildUploadResult(params) {
1799
- return {
1800
- key: this.keyResolver.stripPrefix(params.finalKey),
1801
- bucket: params.bucket,
1802
- etag: params.etag ?? "",
1803
- contentType: params.contentType,
1804
- publicUrl: this.buildPublicUrl(params.finalKey, params.bucket),
1805
- multipart: params.multipart,
1806
- fromIdempotencyCache: false,
1807
- ...params.size !== void 0 ? { size: params.size } : {},
1808
- ...params.versionId !== void 0 ? { versionId: params.versionId } : {}
1809
- };
1810
- }
1811
- /** Emits a progress event, omitting `total`/`part` when they are unknown. */
1812
- emitProgress(onProgress, loaded, total, part) {
1813
- onProgress({
1814
- loaded: loaded ?? 0,
1815
- ...total !== void 0 ? { total } : {},
1816
- ...part !== void 0 ? { part } : {}
1817
- });
2292
+ const context = { key: finalKey, bucket, op: "upload-multipart", ...abort };
2293
+ throw abortedBy ? requestAborted(abortedBy, context) : mapMultipartError(err, context);
1818
2294
  }
1819
2295
  /**
1820
2296
  * Lists objects in the bucket as a single page. Applies the global key prefix
@@ -1830,6 +2306,8 @@ exports.StorageService = class StorageService {
1830
2306
  const bucket = this.resolveBucket(options.bucket);
1831
2307
  const maxKeys = Math.min(options.maxKeys ?? MAX_LIST_KEYS, MAX_LIST_KEYS);
1832
2308
  const prefix = options.prefix ? this.keyResolver.normalize(options.prefix) : this.keyResolver.getPrefix();
2309
+ const context = { bucket, prefix, op: "list" };
2310
+ throwIfAborted(options.abortSignal, context);
1833
2311
  try {
1834
2312
  const response = await this.s3Provider.getClient().send(
1835
2313
  new clientS3.ListObjectsV2Command({
@@ -1838,11 +2316,12 @@ exports.StorageService = class StorageService {
1838
2316
  MaxKeys: maxKeys,
1839
2317
  ContinuationToken: options.continuationToken,
1840
2318
  Delimiter: options.delimiter
1841
- })
2319
+ }),
2320
+ sendOptions(options.abortSignal)
1842
2321
  );
1843
2322
  return toListResult(response, (key) => this.keyResolver.stripPrefix(key));
1844
2323
  } catch (err) {
1845
- throw mapAwsError(err, { bucket, prefix, op: "list" });
2324
+ throw failureOrAbort(options.abortSignal, context, mapAwsError(err, context));
1846
2325
  }
1847
2326
  }
1848
2327
  /**