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