@bymax-one/nest-storage 1.1.0 → 1.1.2

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.
@@ -22,7 +22,6 @@ var BYMAX_STORAGE_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_STORAGE_OPTIONS");
22
22
  var BYMAX_STORAGE_S3_CLIENT = /* @__PURE__ */ Symbol("BYMAX_STORAGE_S3_CLIENT");
23
23
  var BYMAX_STORAGE_UPLOAD_VALIDATORS = /* @__PURE__ */ Symbol("BYMAX_STORAGE_UPLOAD_VALIDATORS");
24
24
  var BYMAX_STORAGE_FILE_SCANNER = /* @__PURE__ */ Symbol("BYMAX_STORAGE_FILE_SCANNER");
25
- var BYMAX_STORAGE_LOGGER = /* @__PURE__ */ Symbol("BYMAX_STORAGE_LOGGER");
26
25
  var BYMAX_STORAGE_IDEMPOTENCY_CACHE = /* @__PURE__ */ Symbol("BYMAX_STORAGE_IDEMPOTENCY_CACHE");
27
26
 
28
27
  // src/shared/constants/error-codes.constants.ts
@@ -39,12 +38,19 @@ var STORAGE_ERROR_CODES = {
39
38
  STORAGE_OBJECT_NOT_FOUND: "STORAGE_OBJECT_NOT_FOUND",
40
39
  STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR",
41
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.
42
43
  STORAGE_PART_TOO_SMALL: "STORAGE_PART_TOO_SMALL",
43
44
  STORAGE_INVALID_PART_COUNT: "STORAGE_INVALID_PART_COUNT",
44
45
  STORAGE_BUCKET_UNDEFINED: "STORAGE_BUCKET_UNDEFINED",
45
46
  STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED",
46
47
  STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG",
47
- 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"
48
54
  };
49
55
 
50
56
  // src/server/errors/storage-error-messages.ts
@@ -62,11 +68,16 @@ var STORAGE_ERROR_MESSAGES = {
62
68
  [STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR]: "Storage provider returned an error",
63
69
  [STORAGE_ERROR_CODES.STORAGE_SIGNED_URL_TTL_INVALID]: "Signed URL TTL is invalid",
64
70
  [STORAGE_ERROR_CODES.STORAGE_PART_TOO_SMALL]: "Multipart part size is below the 5 MB minimum",
65
- [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)",
66
72
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED]: "Bucket is undefined (no default configured and none provided per call)",
67
73
  [STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED]: "Multipart upload was aborted",
68
74
  [STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG]: "Module configuration is invalid",
69
- [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"
70
81
  };
71
82
  var STORAGE_ERROR_STATUS = {
72
83
  [STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED]: common.HttpStatus.SERVICE_UNAVAILABLE,
@@ -86,7 +97,12 @@ var STORAGE_ERROR_STATUS = {
86
97
  [STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED]: common.HttpStatus.BAD_REQUEST,
87
98
  [STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED]: common.HttpStatus.INTERNAL_SERVER_ERROR,
88
99
  [STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG]: common.HttpStatus.INTERNAL_SERVER_ERROR,
89
- [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
90
106
  };
91
107
 
92
108
  // src/server/errors/storage-exception.ts
@@ -189,6 +205,10 @@ var DEFAULT_IDEMPOTENCY_CACHE_MAX_ENTRIES = 1e3;
189
205
  var DEFAULT_IDEMPOTENCY_CACHE_TTL_MS = 864e5;
190
206
 
191
207
  // src/server/config/apply-defaults.ts
208
+ function resolveSignedUrls(configured) {
209
+ const merged = { ...DEFAULT_SIGNED_URLS, ...configured ?? {} };
210
+ return { ...merged, maxTtlSeconds: Math.min(merged.maxTtlSeconds, MAX_SIGNED_URL_TTL_SECONDS) };
211
+ }
192
212
  function applyDefaults(options) {
193
213
  const hasCredentials = Boolean(options.credentials.accessKeyId) && Boolean(options.credentials.secretAccessKey);
194
214
  const publicBaseUrl = options.publicBaseUrl ?? `${trimTrailingSlashes(options.endpoint)}/${options.bucket}`;
@@ -204,7 +224,7 @@ function applyDefaults(options) {
204
224
  keyPrefix: options.keyPrefix ?? "",
205
225
  defaultCacheControl: options.defaultCacheControl ?? DEFAULT_CACHE_CONTROL,
206
226
  defaultContentDisposition: options.defaultContentDisposition ?? DEFAULT_CONTENT_DISPOSITION,
207
- signedUrls: { ...DEFAULT_SIGNED_URLS, ...options.signedUrls ?? {} },
227
+ signedUrls: resolveSignedUrls(options.signedUrls),
208
228
  multipart: { ...DEFAULT_MULTIPART, ...options.multipart ?? {} },
209
229
  ...options.validation !== void 0 ? { validation: options.validation } : {},
210
230
  ...options.scanner !== void 0 ? { scanner: options.scanner } : {},
@@ -294,6 +314,13 @@ var S3ClientProvider = class {
294
314
  ...this.options.credentials.sessionToken ? { sessionToken: this.options.credentials.sessionToken } : {}
295
315
  },
296
316
  maxAttempts: this.options.maxAttempts,
317
+ // `requestTimeout` bounds one attempt, from sending the request until the response
318
+ // headers arrive; the SDK only throws a `TimeoutError` (mapped to
319
+ // `STORAGE_TIMEOUT`) when `throwOnRequestTimeout` is set, otherwise it logs a warning.
320
+ requestHandler: {
321
+ requestTimeout: this.options.requestTimeoutMs,
322
+ throwOnRequestTimeout: true
323
+ },
297
324
  // Data-integrity checksums: AWS SDK v3 defaults to 'WHEN_SUPPORTED' (CRC32
298
325
  // headers), which non-AWS S3-compatible providers reject. Provider recipes
299
326
  // pass 'WHEN_REQUIRED'.
@@ -370,6 +397,316 @@ KeyResolverService = __decorateClass([
370
397
  common.Injectable(),
371
398
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS))
372
399
  ], KeyResolverService);
400
+ function mapAwsError(err, context) {
401
+ const e = err ?? {};
402
+ const httpStatus = e.$metadata?.httpStatusCode;
403
+ const awsCode = e.Code ?? e.name;
404
+ const requestId = e.$metadata?.requestId;
405
+ const details = {
406
+ ...context ?? {},
407
+ awsCode,
408
+ httpStatus,
409
+ requestId,
410
+ awsMessage: e.message
411
+ };
412
+ if (e.name === "NotFound" || httpStatus === 404) {
413
+ return new StorageException(
414
+ STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND,
415
+ common.HttpStatus.NOT_FOUND,
416
+ details
417
+ );
418
+ }
419
+ if (httpStatus === 304) {
420
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED, common.HttpStatus.NOT_MODIFIED, details);
421
+ }
422
+ if (httpStatus === 412) {
423
+ return new StorageException(
424
+ STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED,
425
+ common.HttpStatus.PRECONDITION_FAILED,
426
+ details
427
+ );
428
+ }
429
+ if (e.name === "TimeoutError") {
430
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, details);
431
+ }
432
+ return new StorageException(
433
+ STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR,
434
+ common.HttpStatus.BAD_GATEWAY,
435
+ details
436
+ );
437
+ }
438
+
439
+ // src/server/errors/lifecycle-error-mapper.ts
440
+ var UNSUPPORTED_NAMES = /* @__PURE__ */ new Set([
441
+ "NotImplemented",
442
+ "XNotImplemented",
443
+ "MethodNotAllowed"
444
+ ]);
445
+ var REJECTED_NAMES = /* @__PURE__ */ new Set([
446
+ "MalformedXML",
447
+ "InvalidArgument",
448
+ "InvalidRequest",
449
+ "BadRequest"
450
+ ]);
451
+ var UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([405, 501]);
452
+ function isNoLifecycleConfiguration(err) {
453
+ const e = err ?? {};
454
+ return (e.Code ?? e.name) === "NoSuchLifecycleConfiguration";
455
+ }
456
+ function mapLifecycleError(err, context) {
457
+ const mapped = mapAwsError(err, context);
458
+ const e = err ?? {};
459
+ const name = e.Code ?? e.name;
460
+ const status = e.$metadata?.httpStatusCode ?? 0;
461
+ const details = mapped.getResponse().error.details;
462
+ if (UNSUPPORTED_NAMES.has(name) || UNSUPPORTED_STATUSES.has(status)) {
463
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED, void 0, details);
464
+ }
465
+ if (REJECTED_NAMES.has(name)) {
466
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED, void 0, details);
467
+ }
468
+ return mapped;
469
+ }
470
+
471
+ // src/server/services/bucket-lifecycle.service.ts
472
+ var LEGACY_PREFIX_KEY = "Prefix";
473
+ function legacyPrefix(rule) {
474
+ const value = new Map(Object.entries(rule)).get(LEGACY_PREFIX_KEY);
475
+ return typeof value === "string" ? value : void 0;
476
+ }
477
+ var MAX_RULE_ID_LENGTH = 255;
478
+ function ruleInvalid(reason) {
479
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_RULE_INVALID, void 0, {
480
+ reason
481
+ });
482
+ }
483
+ function assertDays(field, value) {
484
+ if (!Number.isInteger(value) || value < 1) {
485
+ throw ruleInvalid(`${field} must be an integer of at least 1`);
486
+ }
487
+ }
488
+ exports.BucketLifecycleService = class BucketLifecycleService {
489
+ constructor(options, s3Provider, keyResolver) {
490
+ this.options = options;
491
+ this.s3Provider = s3Provider;
492
+ this.keyResolver = keyResolver;
493
+ }
494
+ options;
495
+ s3Provider;
496
+ keyResolver;
497
+ /**
498
+ * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
499
+ * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
500
+ * relative to it, as `list()` returns keys, so a prefix read here can be passed
501
+ * straight to `upsert()` without being prefixed twice. A rule that is not confined
502
+ * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
503
+ * everything else about a rule is returned as the provider stores it.
504
+ *
505
+ * @param options - Optional per-call bucket override.
506
+ * @returns Every rule in the bucket.
507
+ * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
508
+ */
509
+ async get(options) {
510
+ this.assertConfigured();
511
+ const bucket = this.resolveBucket(options?.bucket);
512
+ return (await this.read(bucket)).rules.map((rule) => this.toView(rule));
513
+ }
514
+ /**
515
+ * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
516
+ * the full set back. Rules with other ids are sent exactly as they were read.
517
+ *
518
+ * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
519
+ * @param options - Optional per-call bucket override.
520
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
521
+ * that names a rule outside `keyPrefix`;
522
+ * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
523
+ * @example
524
+ * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
525
+ */
526
+ async upsert(rule, options) {
527
+ this.assertConfigured();
528
+ const owned = this.toRule(rule);
529
+ const bucket = this.resolveBucket(options?.bucket);
530
+ const snapshot = await this.read(bucket);
531
+ const index = snapshot.rules.findIndex((existing) => existing.ID === owned.ID);
532
+ this.assertOwnable(snapshot.rules[index]);
533
+ const rules = [...snapshot.rules];
534
+ if (index === -1) {
535
+ rules.push(owned);
536
+ } else {
537
+ rules[index] = owned;
538
+ }
539
+ await this.write(bucket, rules, snapshot, "upsert");
540
+ }
541
+ /**
542
+ * Removes the rule with this id. When it was the last rule the configuration is
543
+ * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
544
+ *
545
+ * @param id - The rule id.
546
+ * @param options - Optional per-call bucket override.
547
+ * @returns `true` when a rule was removed, `false` when no rule had that id.
548
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
549
+ * outside `keyPrefix`; a provider failure otherwise.
550
+ */
551
+ async remove(id, options) {
552
+ this.assertConfigured();
553
+ this.assertRuleId(id);
554
+ const bucket = this.resolveBucket(options?.bucket);
555
+ const snapshot = await this.read(bucket);
556
+ const target = snapshot.rules.find((existing) => existing.ID === id);
557
+ if (target === void 0) {
558
+ return false;
559
+ }
560
+ this.assertOwnable(target);
561
+ const rules = snapshot.rules.filter((existing) => existing.ID !== id);
562
+ await this.write(bucket, rules, snapshot, "remove");
563
+ return true;
564
+ }
565
+ /**
566
+ * Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
567
+ * with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
568
+ * (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
569
+ */
570
+ isWithinKeyPrefix(rule) {
571
+ const keyPrefix = this.keyResolver.getPrefix();
572
+ if (keyPrefix === "") {
573
+ return true;
574
+ }
575
+ const prefix = rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? legacyPrefix(rule);
576
+ return prefix?.startsWith(keyPrefix) === true;
577
+ }
578
+ /** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
579
+ toView(rule) {
580
+ if (this.isWithinKeyPrefix(rule)) {
581
+ return this.stripRulePrefixes(rule);
582
+ }
583
+ return { ...rule, isOutsideKeyPrefix: true };
584
+ }
585
+ /** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
586
+ assertOwnable(existing) {
587
+ if (existing === void 0) {
588
+ return;
589
+ }
590
+ if (!this.isWithinKeyPrefix(existing)) {
591
+ throw ruleInvalid("A rule with this id exists outside the module keyPrefix and is not changed");
592
+ }
593
+ }
594
+ /**
595
+ * Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
596
+ * carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
597
+ * `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
598
+ */
599
+ stripRulePrefixes(rule) {
600
+ const strip = (prefix) => this.keyResolver.stripPrefix(prefix);
601
+ const { Filter: filter, ...rest } = rule;
602
+ const legacy = legacyPrefix(rule);
603
+ return {
604
+ ...rest,
605
+ ...legacy !== void 0 ? { [LEGACY_PREFIX_KEY]: strip(legacy) } : {},
606
+ ...filter !== void 0 ? {
607
+ Filter: {
608
+ ...filter,
609
+ ...filter.Prefix !== void 0 ? { Prefix: strip(filter.Prefix) } : {},
610
+ ...filter.And?.Prefix !== void 0 ? { And: { ...filter.And, Prefix: strip(filter.And.Prefix) } } : {}
611
+ }
612
+ } : {}
613
+ };
614
+ }
615
+ /** Reads the configuration; "none yet" is an empty snapshot. */
616
+ async read(bucket) {
617
+ try {
618
+ const response = await this.s3Provider.getClient().send(new clientS3.GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
619
+ return {
620
+ rules: response.Rules ?? [],
621
+ transitionDefaultMinimumObjectSize: response.TransitionDefaultMinimumObjectSize
622
+ };
623
+ } catch (err) {
624
+ if (isNoLifecycleConfiguration(err)) {
625
+ return { rules: [], transitionDefaultMinimumObjectSize: void 0 };
626
+ }
627
+ throw mapLifecycleError(err, { bucket, op: "lifecycle.get" });
628
+ }
629
+ }
630
+ /**
631
+ * Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
632
+ * requires at least one rule on a put. The default-minimum-object-size setting
633
+ * read earlier is sent back so a write does not silently change transition behaviour.
634
+ */
635
+ async write(bucket, rules, snapshot, op) {
636
+ const client = this.s3Provider.getClient();
637
+ try {
638
+ if (rules.length === 0) {
639
+ await client.send(new clientS3.DeleteBucketLifecycleCommand({ Bucket: bucket }));
640
+ return;
641
+ }
642
+ await client.send(
643
+ new clientS3.PutBucketLifecycleConfigurationCommand({
644
+ Bucket: bucket,
645
+ LifecycleConfiguration: { Rules: rules },
646
+ ...snapshot.transitionDefaultMinimumObjectSize !== void 0 ? { TransitionDefaultMinimumObjectSize: snapshot.transitionDefaultMinimumObjectSize } : {}
647
+ })
648
+ );
649
+ } catch (err) {
650
+ throw mapLifecycleError(err, { bucket, op: `lifecycle.${op}` });
651
+ }
652
+ }
653
+ /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
654
+ toRule(rule) {
655
+ this.assertRuleId(rule.id);
656
+ if (rule.abortIncompleteMultipartDays !== void 0) {
657
+ assertDays("abortIncompleteMultipartDays", rule.abortIncompleteMultipartDays);
658
+ if (rule.expirationDays !== void 0) {
659
+ throw ruleInvalid("Give exactly one of expirationDays and abortIncompleteMultipartDays");
660
+ }
661
+ if (typeof rule.prefix !== "string") {
662
+ throw ruleInvalid("Prefix must be a string");
663
+ }
664
+ const prefix = rule.prefix === "" ? this.keyResolver.getPrefix() : this.keyResolver.normalize(rule.prefix);
665
+ return {
666
+ ID: rule.id,
667
+ Status: "Enabled",
668
+ Filter: { Prefix: prefix },
669
+ AbortIncompleteMultipartUpload: { DaysAfterInitiation: rule.abortIncompleteMultipartDays }
670
+ };
671
+ }
672
+ if (typeof rule.prefix !== "string" || rule.prefix.length === 0) {
673
+ throw ruleInvalid("Prefix must be a non-empty string");
674
+ }
675
+ assertDays("expirationDays", rule.expirationDays);
676
+ return {
677
+ ID: rule.id,
678
+ Status: "Enabled",
679
+ Filter: { Prefix: this.keyResolver.normalize(rule.prefix) },
680
+ Expiration: { Days: rule.expirationDays }
681
+ };
682
+ }
683
+ assertRuleId(id) {
684
+ if (typeof id !== "string" || id.length === 0) {
685
+ throw ruleInvalid("Rule id must be a non-empty string");
686
+ }
687
+ if (id.length > MAX_RULE_ID_LENGTH) {
688
+ throw ruleInvalid(`Rule id must be at most ${String(MAX_RULE_ID_LENGTH)} characters`);
689
+ }
690
+ }
691
+ assertConfigured() {
692
+ if (!this.s3Provider.isConfigured()) {
693
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED);
694
+ }
695
+ }
696
+ resolveBucket(perCall) {
697
+ const bucket = perCall ?? this.options.bucket;
698
+ if (!bucket) {
699
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED);
700
+ }
701
+ return bucket;
702
+ }
703
+ };
704
+ exports.BucketLifecycleService = __decorateClass([
705
+ common.Injectable(),
706
+ __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
707
+ __decorateParam(1, common.Inject(S3ClientProvider)),
708
+ __decorateParam(2, common.Inject(KeyResolverService))
709
+ ], exports.BucketLifecycleService);
373
710
  function isBufferLike(body) {
374
711
  return body instanceof Uint8Array;
375
712
  }
@@ -386,6 +723,21 @@ async function peekFirstBytes(body, maxBytes) {
386
723
  }
387
724
  return teeAndPeek(body, maxBytes);
388
725
  }
726
+ function destroyStream(stream) {
727
+ const target = stream;
728
+ if (!target) {
729
+ return;
730
+ }
731
+ target.once?.("error", () => void 0);
732
+ target.destroy?.();
733
+ }
734
+ function releaseSourceOnEarlyClose(source, replacement, sourceEnded) {
735
+ replacement.once("close", () => {
736
+ if (!sourceEnded()) {
737
+ destroyStream(source);
738
+ }
739
+ });
740
+ }
389
741
  async function teeAndPeek(source, maxBytes) {
390
742
  const peekPT = new stream.PassThrough();
391
743
  const uploadPT = new stream.PassThrough();
@@ -413,12 +765,16 @@ async function teeAndPeek(source, maxBytes) {
413
765
  uploadPT.once("drain", () => source.resume());
414
766
  }
415
767
  });
768
+ let sourceEnded = false;
416
769
  source.on("end", () => {
770
+ sourceEnded = true;
417
771
  closePeek();
418
772
  uploadPT.end();
419
773
  });
774
+ releaseSourceOnEarlyClose(source, uploadPT, () => sourceEnded);
420
775
  source.on("error", (err) => {
421
776
  closePeek();
777
+ uploadPT.once("error", () => void 0);
422
778
  uploadPT.destroy(err);
423
779
  });
424
780
  const head = await collectStream(peekPT);
@@ -431,6 +787,19 @@ async function collectStream(stream) {
431
787
  }
432
788
  return Buffer.concat(chunks);
433
789
  }
790
+ async function readStreamUpTo(source, maxBytes) {
791
+ const chunks = [];
792
+ let total = 0;
793
+ for await (const chunk of source) {
794
+ const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
795
+ total += buf.byteLength;
796
+ if (total > maxBytes) {
797
+ return void 0;
798
+ }
799
+ chunks.push(buf);
800
+ }
801
+ return Buffer.concat(chunks);
802
+ }
434
803
 
435
804
  // src/server/utils/mime-match.ts
436
805
  function mimeMatches(mime, whitelist) {
@@ -626,34 +995,6 @@ FileScannerService = __decorateClass([
626
995
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
627
996
  __decorateParam(1, common.Inject(BYMAX_STORAGE_FILE_SCANNER))
628
997
  ], FileScannerService);
629
- function mapAwsError(err, context) {
630
- const e = err ?? {};
631
- const httpStatus = e.$metadata?.httpStatusCode;
632
- const awsCode = e.Code ?? e.name;
633
- const requestId = e.$metadata?.requestId;
634
- const details = {
635
- ...context ?? {},
636
- awsCode,
637
- httpStatus,
638
- requestId,
639
- awsMessage: e.message
640
- };
641
- if (e.name === "NotFound" || httpStatus === 404) {
642
- return new StorageException(
643
- STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND,
644
- common.HttpStatus.NOT_FOUND,
645
- details
646
- );
647
- }
648
- if (e.name === "TimeoutError") {
649
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, details);
650
- }
651
- return new StorageException(
652
- STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR,
653
- common.HttpStatus.BAD_GATEWAY,
654
- details
655
- );
656
- }
657
998
 
658
999
  // src/server/utils/header-utils.ts
659
1000
  function buildContentDisposition(perCall, defaultValue) {
@@ -716,11 +1057,26 @@ exports.StorageService = class StorageService {
716
1057
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
717
1058
  * window, the cached result is returned without re-uploading.
718
1059
  *
1060
+ * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
1061
+ * upload is rejected for any reason (configuration, validation, scan, provider failure)
1062
+ * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
1063
+ * that nothing listens to), which releases the file handle or socket behind it; a cache hit
1064
+ * destroys it unread. A stream consumed by a successful upload ends on its own.
1065
+ *
719
1066
  * @param options - The upload request.
720
1067
  * @returns The upload result.
721
1068
  * @throws StorageException for missing configuration, body, or content type.
722
1069
  */
723
1070
  async upload(options) {
1071
+ try {
1072
+ return await this.uploadOwningBody(options);
1073
+ } catch (err) {
1074
+ destroyStream(options.body);
1075
+ throw err;
1076
+ }
1077
+ }
1078
+ /** The upload itself; `upload()` destroys a stream body when this rejects. */
1079
+ async uploadOwningBody(options) {
724
1080
  this.assertConfigured();
725
1081
  const rawBody = options.body;
726
1082
  if (rawBody === void 0 || rawBody === null) {
@@ -735,6 +1091,7 @@ exports.StorageService = class StorageService {
735
1091
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
736
1092
  const cached = this.idempotencyCache.get(cacheKey);
737
1093
  if (cached) {
1094
+ destroyStream(options.body);
738
1095
  return { ...cached, fromIdempotencyCache: true };
739
1096
  }
740
1097
  }
@@ -745,8 +1102,9 @@ exports.StorageService = class StorageService {
745
1102
  ...options.size !== void 0 ? { size: options.size } : {},
746
1103
  ...options.metadata !== void 0 ? { metadata: options.metadata } : {}
747
1104
  });
748
- const validatedOptions = { ...options, body: validated.body };
749
- await this.runPreUploadScan(validated.body, finalKey, bucket, options);
1105
+ const body = await this.bufferForPreUploadScan(validated.body, finalKey);
1106
+ const validatedOptions = { ...options, body };
1107
+ await this.runPreUploadScan(body, finalKey, bucket, options);
750
1108
  const strategy = pickUploadStrategy(
751
1109
  validatedOptions.body,
752
1110
  validatedOptions.size,
@@ -762,6 +1120,35 @@ exports.StorageService = class StorageService {
762
1120
  }
763
1121
  return result;
764
1122
  }
1123
+ /**
1124
+ * In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
1125
+ * and the upload see the same bytes; a stream is single-use, and one the scanner
1126
+ * had consumed would leave the upload with nothing to send. The read is bounded by
1127
+ * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
1128
+ * buffered without limit. Other bodies and modes pass through unchanged.
1129
+ */
1130
+ async bufferForPreUploadScan(body, finalKey) {
1131
+ if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload" || isBufferLike(body)) {
1132
+ return body;
1133
+ }
1134
+ const maxSizeBytes = this.options.validation?.maxSizeBytes;
1135
+ if (maxSizeBytes === void 0) {
1136
+ destroyStream(body);
1137
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1138
+ key: finalKey,
1139
+ reason: "Pre-upload scanning of a stream needs validation.maxSizeBytes to bound the buffer; set it or use scanner mode post-upload"
1140
+ });
1141
+ }
1142
+ const buffered = await readStreamUpTo(body, maxSizeBytes);
1143
+ if (buffered === void 0) {
1144
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1145
+ key: finalKey,
1146
+ maxSizeBytes,
1147
+ reason: "The stream is longer than validation.maxSizeBytes, so it cannot be scanned before upload"
1148
+ });
1149
+ }
1150
+ return buffered;
1151
+ }
765
1152
  /** Runs a pre-upload scan when configured; throws on infected. */
766
1153
  async runPreUploadScan(body, finalKey, bucket, options) {
767
1154
  if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload") {
@@ -777,15 +1164,12 @@ exports.StorageService = class StorageService {
777
1164
  });
778
1165
  }
779
1166
  /**
780
- * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
781
- * the scanner always receives its declared contract type; streams pass through
782
- * unchanged.
1167
+ * Coerces the scan body to a `Buffer` so the scanner always receives its declared
1168
+ * contract type. In pre-upload mode a stream has already been buffered by
1169
+ * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
783
1170
  */
784
1171
  normalizeScanBody(body) {
785
- if (isBufferLike(body)) {
786
- return Buffer.isBuffer(body) ? body : Buffer.from(body);
787
- }
788
- return body;
1172
+ return Buffer.isBuffer(body) ? body : Buffer.from(body);
789
1173
  }
790
1174
  /**
791
1175
  * Runs a post-upload scan. On infection, deletes the just-uploaded object
@@ -974,7 +1358,7 @@ exports.StorageService = class StorageService {
974
1358
  /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
975
1359
  toObjectMetadata(response, finalKey, bucket) {
976
1360
  return {
977
- key: finalKey,
1361
+ key: this.keyResolver.stripPrefix(finalKey),
978
1362
  bucket,
979
1363
  size: response.ContentLength ?? 0,
980
1364
  contentType: response.ContentType ?? "application/octet-stream",
@@ -1085,7 +1469,7 @@ exports.StorageService = class StorageService {
1085
1469
  /** Assembles an `UploadResult`, omitting optional fields that are absent. */
1086
1470
  buildUploadResult(params) {
1087
1471
  return {
1088
- key: params.finalKey,
1472
+ key: this.keyResolver.stripPrefix(params.finalKey),
1089
1473
  bucket: params.bucket,
1090
1474
  etag: params.etag ?? "",
1091
1475
  contentType: params.contentType,
@@ -1271,6 +1655,7 @@ function clampTtl(ttlSeconds, defaultTtl, maxTtl) {
1271
1655
  }
1272
1656
 
1273
1657
  // src/server/services/signed-url.service.ts
1658
+ var MAX_MULTIPART_PARTS = 1e4;
1274
1659
  exports.SignedUrlService = class SignedUrlService {
1275
1660
  constructor(options, s3Provider, keyResolver) {
1276
1661
  this.options = options;
@@ -1396,14 +1781,15 @@ exports.SignedUrlService = class SignedUrlService {
1396
1781
  * @param options - The multipart URL options.
1397
1782
  * @returns `uploadId`, `partUrls`, and `completeUrl`.
1398
1783
  * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
1784
+ * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
1399
1785
  * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
1400
1786
  * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
1401
1787
  */
1402
1788
  async getMultipartUploadUrls(options) {
1403
1789
  this.assertConfigured();
1404
- if (options.parts <= 0) {
1790
+ if (!Number.isInteger(options.parts) || options.parts < 1 || options.parts > MAX_MULTIPART_PARTS) {
1405
1791
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT, void 0, {
1406
- reason: "parts must be a positive integer",
1792
+ reason: `parts must be an integer from 1 to ${String(MAX_MULTIPART_PARTS)}`,
1407
1793
  provided: options.parts
1408
1794
  });
1409
1795
  }
@@ -1559,7 +1945,14 @@ var IdempotencyCache = class {
1559
1945
  // src/server/bymax-storage.module.ts
1560
1946
  function resolveAsyncOptions(options) {
1561
1947
  validateOptions(options);
1562
- return applyDefaults(options);
1948
+ const resolved = applyDefaults(options);
1949
+ const configured = options.signedUrls?.maxTtlSeconds;
1950
+ if (configured !== void 0 && configured > resolved.signedUrls.maxTtlSeconds) {
1951
+ new common.Logger(exports.BymaxStorageModule.name).warn(
1952
+ `signedUrls.maxTtlSeconds=${String(configured)} exceeds the SigV4 presigned-URL limit; using ${String(resolved.signedUrls.maxTtlSeconds)} seconds (7 days) instead.`
1953
+ );
1954
+ }
1955
+ return resolved;
1563
1956
  }
1564
1957
  exports.BymaxStorageModule = class BymaxStorageModule {
1565
1958
  /**
@@ -1657,6 +2050,7 @@ exports.BymaxStorageModule = class BymaxStorageModule {
1657
2050
  },
1658
2051
  exports.StorageService,
1659
2052
  exports.SignedUrlService,
2053
+ exports.BucketLifecycleService,
1660
2054
  // ValidationService and FileScannerService are internal — consumed via
1661
2055
  // StorageService.upload() only, not exported from the module.
1662
2056
  ValidationService,
@@ -1679,6 +2073,7 @@ exports.BymaxStorageModule = class BymaxStorageModule {
1679
2073
  return [
1680
2074
  exports.StorageService,
1681
2075
  exports.SignedUrlService,
2076
+ exports.BucketLifecycleService,
1682
2077
  BYMAX_STORAGE_OPTIONS,
1683
2078
  BYMAX_STORAGE_S3_CLIENT,
1684
2079
  BYMAX_STORAGE_UPLOAD_VALIDATORS,
@@ -1842,8 +2237,6 @@ var providerRecipes = {
1842
2237
  };
1843
2238
 
1844
2239
  exports.BYMAX_STORAGE_FILE_SCANNER = BYMAX_STORAGE_FILE_SCANNER;
1845
- exports.BYMAX_STORAGE_IDEMPOTENCY_CACHE = BYMAX_STORAGE_IDEMPOTENCY_CACHE;
1846
- exports.BYMAX_STORAGE_LOGGER = BYMAX_STORAGE_LOGGER;
1847
2240
  exports.BYMAX_STORAGE_OPTIONS = BYMAX_STORAGE_OPTIONS;
1848
2241
  exports.BYMAX_STORAGE_S3_CLIENT = BYMAX_STORAGE_S3_CLIENT;
1849
2242
  exports.BYMAX_STORAGE_UPLOAD_VALIDATORS = BYMAX_STORAGE_UPLOAD_VALIDATORS;