@bymax-one/nest-storage 1.1.1 → 1.1.3

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.
@@ -38,12 +38,19 @@ var STORAGE_ERROR_CODES = {
38
38
  STORAGE_OBJECT_NOT_FOUND: "STORAGE_OBJECT_NOT_FOUND",
39
39
  STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR",
40
40
  STORAGE_SIGNED_URL_TTL_INVALID: "STORAGE_SIGNED_URL_TTL_INVALID",
41
+ // Reserved: kept so the code keeps its place in this frozen contract. Nothing throws it today;
42
+ // a `multipart.partSizeBytes` under the S3 minimum fails at init as STORAGE_INVALID_CONFIG.
41
43
  STORAGE_PART_TOO_SMALL: "STORAGE_PART_TOO_SMALL",
42
44
  STORAGE_INVALID_PART_COUNT: "STORAGE_INVALID_PART_COUNT",
43
45
  STORAGE_BUCKET_UNDEFINED: "STORAGE_BUCKET_UNDEFINED",
44
46
  STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED",
45
47
  STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG",
46
- STORAGE_TIMEOUT: "STORAGE_TIMEOUT"
48
+ STORAGE_TIMEOUT: "STORAGE_TIMEOUT",
49
+ STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID",
50
+ STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED",
51
+ STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED",
52
+ STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED",
53
+ STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED"
47
54
  };
48
55
 
49
56
  // src/server/errors/storage-error-messages.ts
@@ -61,11 +68,16 @@ var STORAGE_ERROR_MESSAGES = {
61
68
  [STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR]: "Storage provider returned an error",
62
69
  [STORAGE_ERROR_CODES.STORAGE_SIGNED_URL_TTL_INVALID]: "Signed URL TTL is invalid",
63
70
  [STORAGE_ERROR_CODES.STORAGE_PART_TOO_SMALL]: "Multipart part size is below the 5 MB minimum",
64
- [STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT]: "Multipart part count is invalid (must be a positive integer)",
71
+ [STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT]: "Multipart part count is invalid (must be an integer from 1 to 10000)",
65
72
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED]: "Bucket is undefined (no default configured and none provided per call)",
66
73
  [STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED]: "Multipart upload was aborted",
67
74
  [STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG]: "Module configuration is invalid",
68
- [STORAGE_ERROR_CODES.STORAGE_TIMEOUT]: "Storage request timed out"
75
+ [STORAGE_ERROR_CODES.STORAGE_TIMEOUT]: "Storage request timed out",
76
+ [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_RULE_INVALID]: "Lifecycle rule input is invalid",
77
+ [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: "The storage provider does not support bucket lifecycle configuration",
78
+ [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: "The storage provider rejected the lifecycle configuration",
79
+ [STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED]: "The object has not changed since the supplied ETag",
80
+ [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: "The object does not satisfy the supplied precondition"
69
81
  };
70
82
  var STORAGE_ERROR_STATUS = {
71
83
  [STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED]: common.HttpStatus.SERVICE_UNAVAILABLE,
@@ -85,7 +97,12 @@ var STORAGE_ERROR_STATUS = {
85
97
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED]: common.HttpStatus.BAD_REQUEST,
86
98
  [STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED]: common.HttpStatus.INTERNAL_SERVER_ERROR,
87
99
  [STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG]: common.HttpStatus.INTERNAL_SERVER_ERROR,
88
- [STORAGE_ERROR_CODES.STORAGE_TIMEOUT]: common.HttpStatus.GATEWAY_TIMEOUT
100
+ [STORAGE_ERROR_CODES.STORAGE_TIMEOUT]: common.HttpStatus.GATEWAY_TIMEOUT,
101
+ [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_RULE_INVALID]: common.HttpStatus.BAD_REQUEST,
102
+ [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: common.HttpStatus.NOT_IMPLEMENTED,
103
+ [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: common.HttpStatus.UNPROCESSABLE_ENTITY,
104
+ [STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED]: common.HttpStatus.NOT_MODIFIED,
105
+ [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: common.HttpStatus.PRECONDITION_FAILED
89
106
  };
90
107
 
91
108
  // src/server/errors/storage-exception.ts
@@ -143,6 +160,10 @@ function validateOptions(options) {
143
160
  if (isObject(multipart) && typeof multipart.partSizeBytes === "number" && multipart.partSizeBytes < MIN_PART_SIZE_BYTES) {
144
161
  throw invalid("multipart.partSizeBytes must be >= 5 MB (S3 hard limit)");
145
162
  }
163
+ const idle = options.uploadIdleTimeoutMs;
164
+ if (idle !== void 0 && (typeof idle !== "number" || !Number.isInteger(idle) || idle < 0)) {
165
+ throw invalid("uploadIdleTimeoutMs must be an integer >= 0 (0 disables the guard)");
166
+ }
146
167
  if (options.serverSideEncryption === "aws:kms" && !options.kmsKeyId) {
147
168
  throw invalid('kmsKeyId is required when serverSideEncryption === "aws:kms"');
148
169
  }
@@ -188,10 +209,15 @@ var DEFAULT_IDEMPOTENCY_CACHE_MAX_ENTRIES = 1e3;
188
209
  var DEFAULT_IDEMPOTENCY_CACHE_TTL_MS = 864e5;
189
210
 
190
211
  // src/server/config/apply-defaults.ts
212
+ function resolveSignedUrls(configured) {
213
+ const merged = { ...DEFAULT_SIGNED_URLS, ...configured ?? {} };
214
+ return { ...merged, maxTtlSeconds: Math.min(merged.maxTtlSeconds, MAX_SIGNED_URL_TTL_SECONDS) };
215
+ }
191
216
  function applyDefaults(options) {
192
217
  const hasCredentials = Boolean(options.credentials.accessKeyId) && Boolean(options.credentials.secretAccessKey);
193
218
  const publicBaseUrl = options.publicBaseUrl ?? `${trimTrailingSlashes(options.endpoint)}/${options.bucket}`;
194
219
  const credentials = { ...options.credentials };
220
+ const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
195
221
  const resolved = {
196
222
  endpoint: options.endpoint,
197
223
  region: options.region,
@@ -203,7 +229,7 @@ function applyDefaults(options) {
203
229
  keyPrefix: options.keyPrefix ?? "",
204
230
  defaultCacheControl: options.defaultCacheControl ?? DEFAULT_CACHE_CONTROL,
205
231
  defaultContentDisposition: options.defaultContentDisposition ?? DEFAULT_CONTENT_DISPOSITION,
206
- signedUrls: { ...DEFAULT_SIGNED_URLS, ...options.signedUrls ?? {} },
232
+ signedUrls: resolveSignedUrls(options.signedUrls),
207
233
  multipart: { ...DEFAULT_MULTIPART, ...options.multipart ?? {} },
208
234
  ...options.validation !== void 0 ? { validation: options.validation } : {},
209
235
  ...options.scanner !== void 0 ? { scanner: options.scanner } : {},
@@ -212,7 +238,8 @@ function applyDefaults(options) {
212
238
  requestChecksumCalculation: options.requestChecksumCalculation ?? DEFAULT_CHECKSUM_CALCULATION,
213
239
  responseChecksumValidation: options.responseChecksumValidation ?? DEFAULT_CHECKSUM_VALIDATION,
214
240
  maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
215
- requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
241
+ requestTimeoutMs,
242
+ uploadIdleTimeoutMs: options.uploadIdleTimeoutMs ?? requestTimeoutMs,
216
243
  hasCredentials
217
244
  };
218
245
  Object.defineProperty(resolved, "credentials", {
@@ -293,6 +320,13 @@ var S3ClientProvider = class {
293
320
  ...this.options.credentials.sessionToken ? { sessionToken: this.options.credentials.sessionToken } : {}
294
321
  },
295
322
  maxAttempts: this.options.maxAttempts,
323
+ // `requestTimeout` bounds one attempt, from sending the request until the response
324
+ // headers arrive; the SDK only throws a `TimeoutError` (mapped to
325
+ // `STORAGE_TIMEOUT`) when `throwOnRequestTimeout` is set, otherwise it logs a warning.
326
+ requestHandler: {
327
+ requestTimeout: this.options.requestTimeoutMs,
328
+ throwOnRequestTimeout: true
329
+ },
296
330
  // Data-integrity checksums: AWS SDK v3 defaults to 'WHEN_SUPPORTED' (CRC32
297
331
  // headers), which non-AWS S3-compatible providers reject. Provider recipes
298
332
  // pass 'WHEN_REQUIRED'.
@@ -369,6 +403,316 @@ KeyResolverService = __decorateClass([
369
403
  common.Injectable(),
370
404
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS))
371
405
  ], KeyResolverService);
406
+ function mapAwsError(err, context) {
407
+ const e = err ?? {};
408
+ const httpStatus = e.$metadata?.httpStatusCode;
409
+ const awsCode = e.Code ?? e.name;
410
+ const requestId = e.$metadata?.requestId;
411
+ const details = {
412
+ ...context ?? {},
413
+ awsCode,
414
+ httpStatus,
415
+ requestId,
416
+ awsMessage: e.message
417
+ };
418
+ if (e.name === "NotFound" || httpStatus === 404) {
419
+ return new StorageException(
420
+ STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND,
421
+ common.HttpStatus.NOT_FOUND,
422
+ details
423
+ );
424
+ }
425
+ if (httpStatus === 304) {
426
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED, common.HttpStatus.NOT_MODIFIED, details);
427
+ }
428
+ if (httpStatus === 412) {
429
+ return new StorageException(
430
+ STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED,
431
+ common.HttpStatus.PRECONDITION_FAILED,
432
+ details
433
+ );
434
+ }
435
+ if (e.name === "TimeoutError") {
436
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, details);
437
+ }
438
+ return new StorageException(
439
+ STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR,
440
+ common.HttpStatus.BAD_GATEWAY,
441
+ details
442
+ );
443
+ }
444
+
445
+ // src/server/errors/lifecycle-error-mapper.ts
446
+ var UNSUPPORTED_NAMES = /* @__PURE__ */ new Set([
447
+ "NotImplemented",
448
+ "XNotImplemented",
449
+ "MethodNotAllowed"
450
+ ]);
451
+ var REJECTED_NAMES = /* @__PURE__ */ new Set([
452
+ "MalformedXML",
453
+ "InvalidArgument",
454
+ "InvalidRequest",
455
+ "BadRequest"
456
+ ]);
457
+ var UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([405, 501]);
458
+ function isNoLifecycleConfiguration(err) {
459
+ const e = err ?? {};
460
+ return (e.Code ?? e.name) === "NoSuchLifecycleConfiguration";
461
+ }
462
+ function mapLifecycleError(err, context) {
463
+ const mapped = mapAwsError(err, context);
464
+ const e = err ?? {};
465
+ const name = e.Code ?? e.name;
466
+ const status = e.$metadata?.httpStatusCode ?? 0;
467
+ const details = mapped.getResponse().error.details;
468
+ if (UNSUPPORTED_NAMES.has(name) || UNSUPPORTED_STATUSES.has(status)) {
469
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED, void 0, details);
470
+ }
471
+ if (REJECTED_NAMES.has(name)) {
472
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED, void 0, details);
473
+ }
474
+ return mapped;
475
+ }
476
+
477
+ // src/server/services/bucket-lifecycle.service.ts
478
+ var LEGACY_PREFIX_KEY = "Prefix";
479
+ function legacyPrefix(rule) {
480
+ const value = new Map(Object.entries(rule)).get(LEGACY_PREFIX_KEY);
481
+ return typeof value === "string" ? value : void 0;
482
+ }
483
+ var MAX_RULE_ID_LENGTH = 255;
484
+ function ruleInvalid(reason) {
485
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_RULE_INVALID, void 0, {
486
+ reason
487
+ });
488
+ }
489
+ function assertDays(field, value) {
490
+ if (!Number.isInteger(value) || value < 1) {
491
+ throw ruleInvalid(`${field} must be an integer of at least 1`);
492
+ }
493
+ }
494
+ exports.BucketLifecycleService = class BucketLifecycleService {
495
+ constructor(options, s3Provider, keyResolver) {
496
+ this.options = options;
497
+ this.s3Provider = s3Provider;
498
+ this.keyResolver = keyResolver;
499
+ }
500
+ options;
501
+ s3Provider;
502
+ keyResolver;
503
+ /**
504
+ * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
505
+ * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
506
+ * relative to it, as `list()` returns keys, so a prefix read here can be passed
507
+ * straight to `upsert()` without being prefixed twice. A rule that is not confined
508
+ * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
509
+ * everything else about a rule is returned as the provider stores it.
510
+ *
511
+ * @param options - Optional per-call bucket override.
512
+ * @returns Every rule in the bucket.
513
+ * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
514
+ */
515
+ async get(options) {
516
+ this.assertConfigured();
517
+ const bucket = this.resolveBucket(options?.bucket);
518
+ return (await this.read(bucket)).rules.map((rule) => this.toView(rule));
519
+ }
520
+ /**
521
+ * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
522
+ * the full set back. Rules with other ids are sent exactly as they were read.
523
+ *
524
+ * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
525
+ * @param options - Optional per-call bucket override.
526
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
527
+ * that names a rule outside `keyPrefix`;
528
+ * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
529
+ * @example
530
+ * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
531
+ */
532
+ async upsert(rule, options) {
533
+ this.assertConfigured();
534
+ const owned = this.toRule(rule);
535
+ const bucket = this.resolveBucket(options?.bucket);
536
+ const snapshot = await this.read(bucket);
537
+ const index = snapshot.rules.findIndex((existing) => existing.ID === owned.ID);
538
+ this.assertOwnable(snapshot.rules[index]);
539
+ const rules = [...snapshot.rules];
540
+ if (index === -1) {
541
+ rules.push(owned);
542
+ } else {
543
+ rules[index] = owned;
544
+ }
545
+ await this.write(bucket, rules, snapshot, "upsert");
546
+ }
547
+ /**
548
+ * Removes the rule with this id. When it was the last rule the configuration is
549
+ * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
550
+ *
551
+ * @param id - The rule id.
552
+ * @param options - Optional per-call bucket override.
553
+ * @returns `true` when a rule was removed, `false` when no rule had that id.
554
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
555
+ * outside `keyPrefix`; a provider failure otherwise.
556
+ */
557
+ async remove(id, options) {
558
+ this.assertConfigured();
559
+ this.assertRuleId(id);
560
+ const bucket = this.resolveBucket(options?.bucket);
561
+ const snapshot = await this.read(bucket);
562
+ const target = snapshot.rules.find((existing) => existing.ID === id);
563
+ if (target === void 0) {
564
+ return false;
565
+ }
566
+ this.assertOwnable(target);
567
+ const rules = snapshot.rules.filter((existing) => existing.ID !== id);
568
+ await this.write(bucket, rules, snapshot, "remove");
569
+ return true;
570
+ }
571
+ /**
572
+ * Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
573
+ * with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
574
+ * (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
575
+ */
576
+ isWithinKeyPrefix(rule) {
577
+ const keyPrefix = this.keyResolver.getPrefix();
578
+ if (keyPrefix === "") {
579
+ return true;
580
+ }
581
+ const prefix = rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? legacyPrefix(rule);
582
+ return prefix?.startsWith(keyPrefix) === true;
583
+ }
584
+ /** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
585
+ toView(rule) {
586
+ if (this.isWithinKeyPrefix(rule)) {
587
+ return this.stripRulePrefixes(rule);
588
+ }
589
+ return { ...rule, isOutsideKeyPrefix: true };
590
+ }
591
+ /** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
592
+ assertOwnable(existing) {
593
+ if (existing === void 0) {
594
+ return;
595
+ }
596
+ if (!this.isWithinKeyPrefix(existing)) {
597
+ throw ruleInvalid("A rule with this id exists outside the module keyPrefix and is not changed");
598
+ }
599
+ }
600
+ /**
601
+ * Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
602
+ * carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
603
+ * `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
604
+ */
605
+ stripRulePrefixes(rule) {
606
+ const strip = (prefix) => this.keyResolver.stripPrefix(prefix);
607
+ const { Filter: filter, ...rest } = rule;
608
+ const legacy = legacyPrefix(rule);
609
+ return {
610
+ ...rest,
611
+ ...legacy !== void 0 ? { [LEGACY_PREFIX_KEY]: strip(legacy) } : {},
612
+ ...filter !== void 0 ? {
613
+ Filter: {
614
+ ...filter,
615
+ ...filter.Prefix !== void 0 ? { Prefix: strip(filter.Prefix) } : {},
616
+ ...filter.And?.Prefix !== void 0 ? { And: { ...filter.And, Prefix: strip(filter.And.Prefix) } } : {}
617
+ }
618
+ } : {}
619
+ };
620
+ }
621
+ /** Reads the configuration; "none yet" is an empty snapshot. */
622
+ async read(bucket) {
623
+ try {
624
+ const response = await this.s3Provider.getClient().send(new clientS3.GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
625
+ return {
626
+ rules: response.Rules ?? [],
627
+ transitionDefaultMinimumObjectSize: response.TransitionDefaultMinimumObjectSize
628
+ };
629
+ } catch (err) {
630
+ if (isNoLifecycleConfiguration(err)) {
631
+ return { rules: [], transitionDefaultMinimumObjectSize: void 0 };
632
+ }
633
+ throw mapLifecycleError(err, { bucket, op: "lifecycle.get" });
634
+ }
635
+ }
636
+ /**
637
+ * Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
638
+ * requires at least one rule on a put. The default-minimum-object-size setting
639
+ * read earlier is sent back so a write does not silently change transition behaviour.
640
+ */
641
+ async write(bucket, rules, snapshot, op) {
642
+ const client = this.s3Provider.getClient();
643
+ try {
644
+ if (rules.length === 0) {
645
+ await client.send(new clientS3.DeleteBucketLifecycleCommand({ Bucket: bucket }));
646
+ return;
647
+ }
648
+ await client.send(
649
+ new clientS3.PutBucketLifecycleConfigurationCommand({
650
+ Bucket: bucket,
651
+ LifecycleConfiguration: { Rules: rules },
652
+ ...snapshot.transitionDefaultMinimumObjectSize !== void 0 ? { TransitionDefaultMinimumObjectSize: snapshot.transitionDefaultMinimumObjectSize } : {}
653
+ })
654
+ );
655
+ } catch (err) {
656
+ throw mapLifecycleError(err, { bucket, op: `lifecycle.${op}` });
657
+ }
658
+ }
659
+ /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
660
+ toRule(rule) {
661
+ this.assertRuleId(rule.id);
662
+ if (rule.abortIncompleteMultipartDays !== void 0) {
663
+ assertDays("abortIncompleteMultipartDays", rule.abortIncompleteMultipartDays);
664
+ if (rule.expirationDays !== void 0) {
665
+ throw ruleInvalid("Give exactly one of expirationDays and abortIncompleteMultipartDays");
666
+ }
667
+ if (typeof rule.prefix !== "string") {
668
+ throw ruleInvalid("Prefix must be a string");
669
+ }
670
+ const prefix = rule.prefix === "" ? this.keyResolver.getPrefix() : this.keyResolver.normalize(rule.prefix);
671
+ return {
672
+ ID: rule.id,
673
+ Status: "Enabled",
674
+ Filter: { Prefix: prefix },
675
+ AbortIncompleteMultipartUpload: { DaysAfterInitiation: rule.abortIncompleteMultipartDays }
676
+ };
677
+ }
678
+ if (typeof rule.prefix !== "string" || rule.prefix.length === 0) {
679
+ throw ruleInvalid("Prefix must be a non-empty string");
680
+ }
681
+ assertDays("expirationDays", rule.expirationDays);
682
+ return {
683
+ ID: rule.id,
684
+ Status: "Enabled",
685
+ Filter: { Prefix: this.keyResolver.normalize(rule.prefix) },
686
+ Expiration: { Days: rule.expirationDays }
687
+ };
688
+ }
689
+ assertRuleId(id) {
690
+ if (typeof id !== "string" || id.length === 0) {
691
+ throw ruleInvalid("Rule id must be a non-empty string");
692
+ }
693
+ if (id.length > MAX_RULE_ID_LENGTH) {
694
+ throw ruleInvalid(`Rule id must be at most ${String(MAX_RULE_ID_LENGTH)} characters`);
695
+ }
696
+ }
697
+ assertConfigured() {
698
+ if (!this.s3Provider.isConfigured()) {
699
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED);
700
+ }
701
+ }
702
+ resolveBucket(perCall) {
703
+ const bucket = perCall ?? this.options.bucket;
704
+ if (!bucket) {
705
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED);
706
+ }
707
+ return bucket;
708
+ }
709
+ };
710
+ exports.BucketLifecycleService = __decorateClass([
711
+ common.Injectable(),
712
+ __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
713
+ __decorateParam(1, common.Inject(S3ClientProvider)),
714
+ __decorateParam(2, common.Inject(KeyResolverService))
715
+ ], exports.BucketLifecycleService);
372
716
  function isBufferLike(body) {
373
717
  return body instanceof Uint8Array;
374
718
  }
@@ -385,6 +729,21 @@ async function peekFirstBytes(body, maxBytes) {
385
729
  }
386
730
  return teeAndPeek(body, maxBytes);
387
731
  }
732
+ function destroyStream(stream) {
733
+ const target = stream;
734
+ if (!target) {
735
+ return;
736
+ }
737
+ target.once?.("error", () => void 0);
738
+ target.destroy?.();
739
+ }
740
+ function releaseSourceOnEarlyClose(source, replacement, sourceEnded) {
741
+ replacement.once("close", () => {
742
+ if (!sourceEnded()) {
743
+ destroyStream(source);
744
+ }
745
+ });
746
+ }
388
747
  async function teeAndPeek(source, maxBytes) {
389
748
  const peekPT = new stream.PassThrough();
390
749
  const uploadPT = new stream.PassThrough();
@@ -412,12 +771,16 @@ async function teeAndPeek(source, maxBytes) {
412
771
  uploadPT.once("drain", () => source.resume());
413
772
  }
414
773
  });
774
+ let sourceEnded = false;
415
775
  source.on("end", () => {
776
+ sourceEnded = true;
416
777
  closePeek();
417
778
  uploadPT.end();
418
779
  });
780
+ releaseSourceOnEarlyClose(source, uploadPT, () => sourceEnded);
419
781
  source.on("error", (err) => {
420
782
  closePeek();
783
+ uploadPT.once("error", () => void 0);
421
784
  uploadPT.destroy(err);
422
785
  });
423
786
  const head = await collectStream(peekPT);
@@ -430,6 +793,19 @@ async function collectStream(stream) {
430
793
  }
431
794
  return Buffer.concat(chunks);
432
795
  }
796
+ async function readStreamUpTo(source, maxBytes) {
797
+ const chunks = [];
798
+ let total = 0;
799
+ for await (const chunk of source) {
800
+ const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
801
+ total += buf.byteLength;
802
+ if (total > maxBytes) {
803
+ return void 0;
804
+ }
805
+ chunks.push(buf);
806
+ }
807
+ return Buffer.concat(chunks);
808
+ }
433
809
 
434
810
  // src/server/utils/mime-match.ts
435
811
  function mimeMatches(mime, whitelist) {
@@ -625,33 +1001,92 @@ FileScannerService = __decorateClass([
625
1001
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
626
1002
  __decorateParam(1, common.Inject(BYMAX_STORAGE_FILE_SCANNER))
627
1003
  ], FileScannerService);
628
- function mapAwsError(err, context) {
629
- const e = err ?? {};
630
- const httpStatus = e.$metadata?.httpStatusCode;
631
- const awsCode = e.Code ?? e.name;
632
- const requestId = e.$metadata?.requestId;
633
- const details = {
634
- ...context ?? {},
635
- awsCode,
636
- httpStatus,
637
- requestId,
638
- awsMessage: e.message
639
- };
640
- if (e.name === "NotFound" || httpStatus === 404) {
641
- return new StorageException(
642
- STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND,
643
- common.HttpStatus.NOT_FOUND,
644
- details
1004
+
1005
+ // src/server/utils/describe-error.ts
1006
+ var NON_PRINTABLE_REJECTION = "non-printable rejection value";
1007
+ function describeError(value) {
1008
+ try {
1009
+ if (typeof value === "object" && value !== null) {
1010
+ const message = value.message;
1011
+ if (typeof message === "string") {
1012
+ return message;
1013
+ }
1014
+ }
1015
+ return String(value);
1016
+ } catch {
1017
+ return NON_PRINTABLE_REJECTION;
1018
+ }
1019
+ }
1020
+ var SourceIdleError = class extends Error {
1021
+ constructor(idleMs) {
1022
+ super(`The upload source delivered no bytes for ${String(idleMs)} ms`);
1023
+ this.idleMs = idleMs;
1024
+ this.name = "SourceIdleError";
1025
+ }
1026
+ idleMs;
1027
+ };
1028
+ function withinIdleTime(next, idleMs) {
1029
+ return new Promise((resolve, reject) => {
1030
+ const timer = setTimeout(() => {
1031
+ reject(new SourceIdleError(idleMs));
1032
+ }, idleMs);
1033
+ next.then(
1034
+ (value) => {
1035
+ clearTimeout(timer);
1036
+ resolve(value);
1037
+ },
1038
+ (error) => {
1039
+ clearTimeout(timer);
1040
+ reject(error instanceof Error ? error : new Error(describeError(error)));
1041
+ }
645
1042
  );
1043
+ });
1044
+ }
1045
+ function withIdleTimeout(source, idleMs) {
1046
+ const iterator = source[Symbol.asyncIterator]();
1047
+ const wrapper = new stream.Readable({
1048
+ objectMode: false,
1049
+ // No read-ahead: with a buffer to fill, Node calls read() while the consumer is paused, and the
1050
+ // clock would run for bytes nobody has asked for. At 0, read() runs only on demand.
1051
+ highWaterMark: 0,
1052
+ read() {
1053
+ withinIdleTime(iterator.next(), idleMs).then(
1054
+ (step) => {
1055
+ wrapper.push(step.done === true ? null : step.value);
1056
+ },
1057
+ (error) => {
1058
+ wrapper.destroy(error);
1059
+ }
1060
+ );
1061
+ },
1062
+ destroy(error, callback) {
1063
+ destroyStream(source);
1064
+ callback(error);
1065
+ }
1066
+ });
1067
+ wrapper.once("error", () => void 0);
1068
+ return wrapper;
1069
+ }
1070
+ function guardIdleBody(body, idleMs) {
1071
+ if (isBufferLike(body)) {
1072
+ return body;
646
1073
  }
647
- if (e.name === "TimeoutError") {
648
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, details);
1074
+ return idleMs === 0 ? body : withIdleTimeout(body, idleMs);
1075
+ }
1076
+
1077
+ // src/server/errors/multipart-error-mapper.ts
1078
+ function mapMultipartError(err, context) {
1079
+ if (err instanceof SourceIdleError) {
1080
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, {
1081
+ ...context,
1082
+ phase: "source-idle",
1083
+ idleMs: err.idleMs
1084
+ });
649
1085
  }
650
- return new StorageException(
651
- STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR,
652
- common.HttpStatus.BAD_GATEWAY,
653
- details
654
- );
1086
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED, void 0, {
1087
+ ...context,
1088
+ awsMessage: describeError(err)
1089
+ });
655
1090
  }
656
1091
 
657
1092
  // src/server/utils/header-utils.ts
@@ -715,11 +1150,26 @@ exports.StorageService = class StorageService {
715
1150
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
716
1151
  * window, the cached result is returned without re-uploading.
717
1152
  *
1153
+ * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
1154
+ * upload is rejected for any reason (configuration, validation, scan, provider failure)
1155
+ * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
1156
+ * that nothing listens to), which releases the file handle or socket behind it; a cache hit
1157
+ * destroys it unread. A stream consumed by a successful upload ends on its own.
1158
+ *
718
1159
  * @param options - The upload request.
719
1160
  * @returns The upload result.
720
1161
  * @throws StorageException for missing configuration, body, or content type.
721
1162
  */
722
1163
  async upload(options) {
1164
+ try {
1165
+ return await this.uploadOwningBody(options);
1166
+ } catch (err) {
1167
+ destroyStream(options.body);
1168
+ throw err;
1169
+ }
1170
+ }
1171
+ /** The upload itself; `upload()` destroys a stream body when this rejects. */
1172
+ async uploadOwningBody(options) {
723
1173
  this.assertConfigured();
724
1174
  const rawBody = options.body;
725
1175
  if (rawBody === void 0 || rawBody === null) {
@@ -734,6 +1184,7 @@ exports.StorageService = class StorageService {
734
1184
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
735
1185
  const cached = this.idempotencyCache.get(cacheKey);
736
1186
  if (cached) {
1187
+ destroyStream(options.body);
737
1188
  return { ...cached, fromIdempotencyCache: true };
738
1189
  }
739
1190
  }
@@ -744,8 +1195,9 @@ exports.StorageService = class StorageService {
744
1195
  ...options.size !== void 0 ? { size: options.size } : {},
745
1196
  ...options.metadata !== void 0 ? { metadata: options.metadata } : {}
746
1197
  });
747
- const validatedOptions = { ...options, body: validated.body };
748
- await this.runPreUploadScan(validated.body, finalKey, bucket, options);
1198
+ const body = await this.bufferForPreUploadScan(validated.body, finalKey);
1199
+ const validatedOptions = { ...options, body };
1200
+ await this.runPreUploadScan(body, finalKey, bucket, options);
749
1201
  const strategy = pickUploadStrategy(
750
1202
  validatedOptions.body,
751
1203
  validatedOptions.size,
@@ -761,6 +1213,35 @@ exports.StorageService = class StorageService {
761
1213
  }
762
1214
  return result;
763
1215
  }
1216
+ /**
1217
+ * In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
1218
+ * and the upload see the same bytes; a stream is single-use, and one the scanner
1219
+ * had consumed would leave the upload with nothing to send. The read is bounded by
1220
+ * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
1221
+ * buffered without limit. Other bodies and modes pass through unchanged.
1222
+ */
1223
+ async bufferForPreUploadScan(body, finalKey) {
1224
+ if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload" || isBufferLike(body)) {
1225
+ return body;
1226
+ }
1227
+ const maxSizeBytes = this.options.validation?.maxSizeBytes;
1228
+ if (maxSizeBytes === void 0) {
1229
+ destroyStream(body);
1230
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1231
+ key: finalKey,
1232
+ reason: "Pre-upload scanning of a stream needs validation.maxSizeBytes to bound the buffer; set it or use scanner mode post-upload"
1233
+ });
1234
+ }
1235
+ const buffered = await readStreamUpTo(body, maxSizeBytes);
1236
+ if (buffered === void 0) {
1237
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1238
+ key: finalKey,
1239
+ maxSizeBytes,
1240
+ reason: "The stream is longer than validation.maxSizeBytes, so it cannot be scanned before upload"
1241
+ });
1242
+ }
1243
+ return buffered;
1244
+ }
764
1245
  /** Runs a pre-upload scan when configured; throws on infected. */
765
1246
  async runPreUploadScan(body, finalKey, bucket, options) {
766
1247
  if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload") {
@@ -776,15 +1257,12 @@ exports.StorageService = class StorageService {
776
1257
  });
777
1258
  }
778
1259
  /**
779
- * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
780
- * the scanner always receives its declared contract type; streams pass through
781
- * unchanged.
1260
+ * Coerces the scan body to a `Buffer` so the scanner always receives its declared
1261
+ * contract type. In pre-upload mode a stream has already been buffered by
1262
+ * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
782
1263
  */
783
1264
  normalizeScanBody(body) {
784
- if (isBufferLike(body)) {
785
- return Buffer.isBuffer(body) ? body : Buffer.from(body);
786
- }
787
- return body;
1265
+ return Buffer.isBuffer(body) ? body : Buffer.from(body);
788
1266
  }
789
1267
  /**
790
1268
  * Runs a post-upload scan. On infection, deletes the just-uploaded object
@@ -806,7 +1284,7 @@ exports.StorageService = class StorageService {
806
1284
  await this.delete(finalKey, { bucket }).catch((deleteErr) => {
807
1285
  this.logger.error(
808
1286
  `Post-upload cleanup failed for infected/inconclusive object: ${finalKey}`,
809
- deleteErr.message
1287
+ describeError(deleteErr)
810
1288
  );
811
1289
  });
812
1290
  throw scanErr;
@@ -847,7 +1325,7 @@ exports.StorageService = class StorageService {
847
1325
  if (err instanceof StorageException && err.code === STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
848
1326
  return false;
849
1327
  }
850
- this.logger.warn(`exists() \u2014 treating a non-404 error as "false": ${err.message}`);
1328
+ this.logger.warn(`exists() \u2014 treating a non-404 error as "false": ${describeError(err)}`);
851
1329
  return false;
852
1330
  }
853
1331
  }
@@ -973,7 +1451,7 @@ exports.StorageService = class StorageService {
973
1451
  /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
974
1452
  toObjectMetadata(response, finalKey, bucket) {
975
1453
  return {
976
- key: finalKey,
1454
+ key: this.keyResolver.stripPrefix(finalKey),
977
1455
  bucket,
978
1456
  size: response.ContentLength ?? 0,
979
1457
  contentType: response.ContentType ?? "application/octet-stream",
@@ -1031,7 +1509,7 @@ exports.StorageService = class StorageService {
1031
1509
  const params = {
1032
1510
  Bucket: bucket,
1033
1511
  Key: finalKey,
1034
- Body: options.body,
1512
+ Body: guardIdleBody(options.body, this.options.uploadIdleTimeoutMs),
1035
1513
  ContentType: options.contentType,
1036
1514
  CacheControl: buildCacheControl(options.cacheControl, this.options.defaultCacheControl),
1037
1515
  ContentDisposition: buildContentDisposition(
@@ -1067,11 +1545,7 @@ exports.StorageService = class StorageService {
1067
1545
  multipart: true
1068
1546
  });
1069
1547
  } catch (err) {
1070
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED, void 0, {
1071
- key: finalKey,
1072
- bucket,
1073
- awsMessage: err.message
1074
- });
1548
+ throw mapMultipartError(err, { key: finalKey, bucket });
1075
1549
  }
1076
1550
  }
1077
1551
  /** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
@@ -1084,7 +1558,7 @@ exports.StorageService = class StorageService {
1084
1558
  /** Assembles an `UploadResult`, omitting optional fields that are absent. */
1085
1559
  buildUploadResult(params) {
1086
1560
  return {
1087
- key: params.finalKey,
1561
+ key: this.keyResolver.stripPrefix(params.finalKey),
1088
1562
  bucket: params.bucket,
1089
1563
  etag: params.etag ?? "",
1090
1564
  contentType: params.contentType,
@@ -1239,7 +1713,7 @@ exports.StorageService = class StorageService {
1239
1713
  }
1240
1714
  }
1241
1715
  } catch (err) {
1242
- const message = err instanceof Error ? err.message : String(err);
1716
+ const message = describeError(err);
1243
1717
  for (const key of chunk) {
1244
1718
  failed.push({ key: this.keyResolver.stripPrefix(key), error: message });
1245
1719
  }
@@ -1270,6 +1744,7 @@ function clampTtl(ttlSeconds, defaultTtl, maxTtl) {
1270
1744
  }
1271
1745
 
1272
1746
  // src/server/services/signed-url.service.ts
1747
+ var MAX_MULTIPART_PARTS = 1e4;
1273
1748
  exports.SignedUrlService = class SignedUrlService {
1274
1749
  constructor(options, s3Provider, keyResolver) {
1275
1750
  this.options = options;
@@ -1395,14 +1870,15 @@ exports.SignedUrlService = class SignedUrlService {
1395
1870
  * @param options - The multipart URL options.
1396
1871
  * @returns `uploadId`, `partUrls`, and `completeUrl`.
1397
1872
  * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
1873
+ * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
1398
1874
  * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
1399
1875
  * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
1400
1876
  */
1401
1877
  async getMultipartUploadUrls(options) {
1402
1878
  this.assertConfigured();
1403
- if (options.parts <= 0) {
1879
+ if (!Number.isInteger(options.parts) || options.parts < 1 || options.parts > MAX_MULTIPART_PARTS) {
1404
1880
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT, void 0, {
1405
- reason: "parts must be a positive integer",
1881
+ reason: `parts must be an integer from 1 to ${String(MAX_MULTIPART_PARTS)}`,
1406
1882
  provided: options.parts
1407
1883
  });
1408
1884
  }
@@ -1558,7 +2034,14 @@ var IdempotencyCache = class {
1558
2034
  // src/server/bymax-storage.module.ts
1559
2035
  function resolveAsyncOptions(options) {
1560
2036
  validateOptions(options);
1561
- return applyDefaults(options);
2037
+ const resolved = applyDefaults(options);
2038
+ const configured = options.signedUrls?.maxTtlSeconds;
2039
+ if (configured !== void 0 && configured > resolved.signedUrls.maxTtlSeconds) {
2040
+ new common.Logger(exports.BymaxStorageModule.name).warn(
2041
+ `signedUrls.maxTtlSeconds=${String(configured)} exceeds the SigV4 presigned-URL limit; using ${String(resolved.signedUrls.maxTtlSeconds)} seconds (7 days) instead.`
2042
+ );
2043
+ }
2044
+ return resolved;
1562
2045
  }
1563
2046
  exports.BymaxStorageModule = class BymaxStorageModule {
1564
2047
  /**
@@ -1656,6 +2139,7 @@ exports.BymaxStorageModule = class BymaxStorageModule {
1656
2139
  },
1657
2140
  exports.StorageService,
1658
2141
  exports.SignedUrlService,
2142
+ exports.BucketLifecycleService,
1659
2143
  // ValidationService and FileScannerService are internal — consumed via
1660
2144
  // StorageService.upload() only, not exported from the module.
1661
2145
  ValidationService,
@@ -1678,6 +2162,7 @@ exports.BymaxStorageModule = class BymaxStorageModule {
1678
2162
  return [
1679
2163
  exports.StorageService,
1680
2164
  exports.SignedUrlService,
2165
+ exports.BucketLifecycleService,
1681
2166
  BYMAX_STORAGE_OPTIONS,
1682
2167
  BYMAX_STORAGE_S3_CLIENT,
1683
2168
  BYMAX_STORAGE_UPLOAD_VALIDATORS,