@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,5 +1,5 @@
1
1
  import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
2
- import { S3Client } from '@aws-sdk/client-s3';
2
+ import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
3
3
 
4
4
  /**
5
5
  * @fileoverview Pluggable upload-validator contract. Implementations run in order
@@ -168,6 +168,12 @@ interface BymaxStorageModuleOptions {
168
168
  maxAttempts?: number;
169
169
  /** Per-request timeout. Default: `30000` ms. */
170
170
  requestTimeoutMs?: number;
171
+ /**
172
+ * Longest silence, in milliseconds, tolerated from a stream body while a multipart upload
173
+ * waits for its next bytes; past it the upload is aborted and rejects `STORAGE_TIMEOUT`.
174
+ * An integer of at least `0`; `0` turns the guard off. Default: `requestTimeoutMs`.
175
+ */
176
+ uploadIdleTimeoutMs?: number;
171
177
  }
172
178
  /**
173
179
  * Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
@@ -296,6 +302,7 @@ interface ResolvedBymaxStorageOptions {
296
302
  responseChecksumValidation: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
297
303
  maxAttempts: number;
298
304
  requestTimeoutMs: number;
305
+ uploadIdleTimeoutMs: number;
299
306
  /** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
300
307
  hasCredentials: boolean;
301
308
  }
@@ -360,7 +367,7 @@ interface DownloadOptions {
360
367
  */
361
368
  /** Outcome of an upload — returned to the caller. */
362
369
  interface UploadResult {
363
- /** Final key after normalization and the global key prefix. */
370
+ /** The object key relative to `keyPrefix`: pass it back to any method as is. */
364
371
  key: string;
365
372
  bucket: string;
366
373
  etag: string;
@@ -712,17 +719,33 @@ declare class StorageService {
712
719
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
713
720
  * window, the cached result is returned without re-uploading.
714
721
  *
722
+ * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
723
+ * upload is rejected for any reason (configuration, validation, scan, provider failure)
724
+ * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
725
+ * that nothing listens to), which releases the file handle or socket behind it; a cache hit
726
+ * destroys it unread. A stream consumed by a successful upload ends on its own.
727
+ *
715
728
  * @param options - The upload request.
716
729
  * @returns The upload result.
717
730
  * @throws StorageException for missing configuration, body, or content type.
718
731
  */
719
732
  upload(options: UploadOptions): Promise<UploadResult>;
733
+ /** The upload itself; `upload()` destroys a stream body when this rejects. */
734
+ private uploadOwningBody;
735
+ /**
736
+ * In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
737
+ * and the upload see the same bytes; a stream is single-use, and one the scanner
738
+ * had consumed would leave the upload with nothing to send. The read is bounded by
739
+ * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
740
+ * buffered without limit. Other bodies and modes pass through unchanged.
741
+ */
742
+ private bufferForPreUploadScan;
720
743
  /** Runs a pre-upload scan when configured; throws on infected. */
721
744
  private runPreUploadScan;
722
745
  /**
723
- * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
724
- * the scanner always receives its declared contract type; streams pass through
725
- * unchanged.
746
+ * Coerces the scan body to a `Buffer` so the scanner always receives its declared
747
+ * contract type. In pre-upload mode a stream has already been buffered by
748
+ * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
726
749
  */
727
750
  private normalizeScanBody;
728
751
  /**
@@ -987,6 +1010,7 @@ declare class SignedUrlService {
987
1010
  * @param options - The multipart URL options.
988
1011
  * @returns `uploadId`, `partUrls`, and `completeUrl`.
989
1012
  * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
1013
+ * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
990
1014
  * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
991
1015
  * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
992
1016
  */
@@ -999,6 +1023,146 @@ declare class SignedUrlService {
999
1023
  private resolveBucket;
1000
1024
  }
1001
1025
 
1026
+ /**
1027
+ * @fileoverview Public contracts for `BucketLifecycleService`: the rule shape
1028
+ * the library owns, the per-call bucket override, and the provider rule type.
1029
+ * @layer server/interfaces
1030
+ */
1031
+
1032
+ /**
1033
+ * A lifecycle rule exactly as the provider stores it. Reads return every rule in
1034
+ * the bucket, including ones this library did not write (transitions, tag
1035
+ * filters, multipart aborts), and writes send them back unchanged.
1036
+ */
1037
+ type BucketLifecycleRule = LifecycleRule;
1038
+ /**
1039
+ * A rule as `get()` returns it. `isOutsideKeyPrefix` is set (to `true`) only on a rule
1040
+ * that is not confined to the module's `keyPrefix` — written by another application, or
1041
+ * by hand — and `upsert()` / `remove()` refuse to change such a rule.
1042
+ */
1043
+ type BucketLifecycleRuleView = BucketLifecycleRule & {
1044
+ isOutsideKeyPrefix?: true;
1045
+ };
1046
+ /** Per-call override of the target bucket. */
1047
+ interface LifecycleBucketOptions {
1048
+ /** Defaults to the module's configured bucket. */
1049
+ bucket?: string;
1050
+ }
1051
+ /** A rule `BucketLifecycleService.upsert()` writes: expire a prefix after N days. */
1052
+ interface ExpirationRuleInput {
1053
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1054
+ id: string;
1055
+ /** Key prefix the rule applies to. Relative to the module's `keyPrefix`, like every other key. */
1056
+ prefix: string;
1057
+ /** Days after creation until an object under the prefix expires. A positive integer. */
1058
+ expirationDays: number;
1059
+ /** A rule is an expiration or an abort rule, never both. */
1060
+ abortIncompleteMultipartDays?: never;
1061
+ }
1062
+ /**
1063
+ * A rule `BucketLifecycleService.upsert()` writes: abort multipart uploads that were not completed
1064
+ * within N days of starting, which frees the parts they hold.
1065
+ */
1066
+ interface AbortMultipartRuleInput {
1067
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1068
+ id: string;
1069
+ /**
1070
+ * Key prefix the rule applies to, relative to the module's `keyPrefix`. May be empty, which means
1071
+ * every upload in the module's namespace: unlike expiration, aborting a stale upload deletes no object.
1072
+ */
1073
+ prefix: string;
1074
+ /** Days after an upload starts until it is aborted. A positive integer. */
1075
+ abortIncompleteMultipartDays: number;
1076
+ /** A rule is an expiration or an abort rule, never both. */
1077
+ expirationDays?: never;
1078
+ }
1079
+ /** Either rule shape `BucketLifecycleService.upsert()` accepts. */
1080
+ type LifecycleRuleInput = ExpirationRuleInput | AbortMultipartRuleInput;
1081
+
1082
+ /**
1083
+ * Manages the bucket's lifecycle configuration without disturbing rules it did
1084
+ * not write.
1085
+ *
1086
+ * Concurrency: `upsert` and `remove` read the configuration, change it in memory
1087
+ * and write all of it back. S3 has no conditional write for lifecycle
1088
+ * configuration, so another writer that changes the bucket between the read and
1089
+ * the write is overwritten. Serialize lifecycle changes in the caller (one
1090
+ * operator command, or a single deployment step) rather than relying on this
1091
+ * service to lock.
1092
+ */
1093
+ declare class BucketLifecycleService {
1094
+ private readonly options;
1095
+ private readonly s3Provider;
1096
+ private readonly keyResolver;
1097
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1098
+ /**
1099
+ * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
1100
+ * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
1101
+ * relative to it, as `list()` returns keys, so a prefix read here can be passed
1102
+ * straight to `upsert()` without being prefixed twice. A rule that is not confined
1103
+ * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
1104
+ * everything else about a rule is returned as the provider stores it.
1105
+ *
1106
+ * @param options - Optional per-call bucket override.
1107
+ * @returns Every rule in the bucket.
1108
+ * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
1109
+ */
1110
+ get(options?: LifecycleBucketOptions): Promise<BucketLifecycleRuleView[]>;
1111
+ /**
1112
+ * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
1113
+ * the full set back. Rules with other ids are sent exactly as they were read.
1114
+ *
1115
+ * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
1116
+ * @param options - Optional per-call bucket override.
1117
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
1118
+ * that names a rule outside `keyPrefix`;
1119
+ * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
1120
+ * @example
1121
+ * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
1122
+ */
1123
+ upsert(rule: LifecycleRuleInput, options?: LifecycleBucketOptions): Promise<void>;
1124
+ /**
1125
+ * Removes the rule with this id. When it was the last rule the configuration is
1126
+ * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
1127
+ *
1128
+ * @param id - The rule id.
1129
+ * @param options - Optional per-call bucket override.
1130
+ * @returns `true` when a rule was removed, `false` when no rule had that id.
1131
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
1132
+ * outside `keyPrefix`; a provider failure otherwise.
1133
+ */
1134
+ remove(id: string, options?: LifecycleBucketOptions): Promise<boolean>;
1135
+ /**
1136
+ * Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
1137
+ * with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
1138
+ * (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
1139
+ */
1140
+ private isWithinKeyPrefix;
1141
+ /** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
1142
+ private toView;
1143
+ /** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
1144
+ private assertOwnable;
1145
+ /**
1146
+ * Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
1147
+ * carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
1148
+ * `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
1149
+ */
1150
+ private stripRulePrefixes;
1151
+ /** Reads the configuration; "none yet" is an empty snapshot. */
1152
+ private read;
1153
+ /**
1154
+ * Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
1155
+ * requires at least one rule on a put. The default-minimum-object-size setting
1156
+ * read earlier is sent back so a write does not silently change transition behaviour.
1157
+ */
1158
+ private write;
1159
+ /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
1160
+ private toRule;
1161
+ private assertRuleId;
1162
+ private assertConfigured;
1163
+ private resolveBucket;
1164
+ }
1165
+
1002
1166
  /**
1003
1167
  * @fileoverview No-operation upload validator — always passes. Use as the
1004
1168
  * default when no custom validation logic is needed.
@@ -1180,6 +1344,11 @@ declare const STORAGE_ERROR_CODES: {
1180
1344
  readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
1181
1345
  readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
1182
1346
  readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
1347
+ readonly STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID";
1348
+ readonly STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED";
1349
+ readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
1350
+ readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
1351
+ readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
1183
1352
  };
1184
1353
  /** Union of every stable storage error code. */
1185
1354
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1205,4 +1374,4 @@ declare class StorageException extends HttpException {
1205
1374
  statusCode?: HttpStatus, details?: Record<string, unknown>);
1206
1375
  }
1207
1376
 
1208
- export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
1377
+ export { type AbortMultipartRuleInput, BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, type BucketLifecycleRule, type BucketLifecycleRuleView, BucketLifecycleService, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type ExpirationRuleInput, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type LifecycleBucketOptions, type LifecycleRuleInput, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
@@ -1,5 +1,5 @@
1
1
  import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
2
- import { S3Client } from '@aws-sdk/client-s3';
2
+ import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
3
3
 
4
4
  /**
5
5
  * @fileoverview Pluggable upload-validator contract. Implementations run in order
@@ -168,6 +168,12 @@ interface BymaxStorageModuleOptions {
168
168
  maxAttempts?: number;
169
169
  /** Per-request timeout. Default: `30000` ms. */
170
170
  requestTimeoutMs?: number;
171
+ /**
172
+ * Longest silence, in milliseconds, tolerated from a stream body while a multipart upload
173
+ * waits for its next bytes; past it the upload is aborted and rejects `STORAGE_TIMEOUT`.
174
+ * An integer of at least `0`; `0` turns the guard off. Default: `requestTimeoutMs`.
175
+ */
176
+ uploadIdleTimeoutMs?: number;
171
177
  }
172
178
  /**
173
179
  * Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
@@ -296,6 +302,7 @@ interface ResolvedBymaxStorageOptions {
296
302
  responseChecksumValidation: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
297
303
  maxAttempts: number;
298
304
  requestTimeoutMs: number;
305
+ uploadIdleTimeoutMs: number;
299
306
  /** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
300
307
  hasCredentials: boolean;
301
308
  }
@@ -360,7 +367,7 @@ interface DownloadOptions {
360
367
  */
361
368
  /** Outcome of an upload — returned to the caller. */
362
369
  interface UploadResult {
363
- /** Final key after normalization and the global key prefix. */
370
+ /** The object key relative to `keyPrefix`: pass it back to any method as is. */
364
371
  key: string;
365
372
  bucket: string;
366
373
  etag: string;
@@ -712,17 +719,33 @@ declare class StorageService {
712
719
  * `idempotencyKey` is supplied and a matching result is cached within the TTL
713
720
  * window, the cached result is returned without re-uploading.
714
721
  *
722
+ * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
723
+ * upload is rejected for any reason (configuration, validation, scan, provider failure)
724
+ * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
725
+ * that nothing listens to), which releases the file handle or socket behind it; a cache hit
726
+ * destroys it unread. A stream consumed by a successful upload ends on its own.
727
+ *
715
728
  * @param options - The upload request.
716
729
  * @returns The upload result.
717
730
  * @throws StorageException for missing configuration, body, or content type.
718
731
  */
719
732
  upload(options: UploadOptions): Promise<UploadResult>;
733
+ /** The upload itself; `upload()` destroys a stream body when this rejects. */
734
+ private uploadOwningBody;
735
+ /**
736
+ * In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
737
+ * and the upload see the same bytes; a stream is single-use, and one the scanner
738
+ * had consumed would leave the upload with nothing to send. The read is bounded by
739
+ * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
740
+ * buffered without limit. Other bodies and modes pass through unchanged.
741
+ */
742
+ private bufferForPreUploadScan;
720
743
  /** Runs a pre-upload scan when configured; throws on infected. */
721
744
  private runPreUploadScan;
722
745
  /**
723
- * Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
724
- * the scanner always receives its declared contract type; streams pass through
725
- * unchanged.
746
+ * Coerces the scan body to a `Buffer` so the scanner always receives its declared
747
+ * contract type. In pre-upload mode a stream has already been buffered by
748
+ * {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
726
749
  */
727
750
  private normalizeScanBody;
728
751
  /**
@@ -987,6 +1010,7 @@ declare class SignedUrlService {
987
1010
  * @param options - The multipart URL options.
988
1011
  * @returns `uploadId`, `partUrls`, and `completeUrl`.
989
1012
  * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
1013
+ * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
990
1014
  * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
991
1015
  * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
992
1016
  */
@@ -999,6 +1023,146 @@ declare class SignedUrlService {
999
1023
  private resolveBucket;
1000
1024
  }
1001
1025
 
1026
+ /**
1027
+ * @fileoverview Public contracts for `BucketLifecycleService`: the rule shape
1028
+ * the library owns, the per-call bucket override, and the provider rule type.
1029
+ * @layer server/interfaces
1030
+ */
1031
+
1032
+ /**
1033
+ * A lifecycle rule exactly as the provider stores it. Reads return every rule in
1034
+ * the bucket, including ones this library did not write (transitions, tag
1035
+ * filters, multipart aborts), and writes send them back unchanged.
1036
+ */
1037
+ type BucketLifecycleRule = LifecycleRule;
1038
+ /**
1039
+ * A rule as `get()` returns it. `isOutsideKeyPrefix` is set (to `true`) only on a rule
1040
+ * that is not confined to the module's `keyPrefix` — written by another application, or
1041
+ * by hand — and `upsert()` / `remove()` refuse to change such a rule.
1042
+ */
1043
+ type BucketLifecycleRuleView = BucketLifecycleRule & {
1044
+ isOutsideKeyPrefix?: true;
1045
+ };
1046
+ /** Per-call override of the target bucket. */
1047
+ interface LifecycleBucketOptions {
1048
+ /** Defaults to the module's configured bucket. */
1049
+ bucket?: string;
1050
+ }
1051
+ /** A rule `BucketLifecycleService.upsert()` writes: expire a prefix after N days. */
1052
+ interface ExpirationRuleInput {
1053
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1054
+ id: string;
1055
+ /** Key prefix the rule applies to. Relative to the module's `keyPrefix`, like every other key. */
1056
+ prefix: string;
1057
+ /** Days after creation until an object under the prefix expires. A positive integer. */
1058
+ expirationDays: number;
1059
+ /** A rule is an expiration or an abort rule, never both. */
1060
+ abortIncompleteMultipartDays?: never;
1061
+ }
1062
+ /**
1063
+ * A rule `BucketLifecycleService.upsert()` writes: abort multipart uploads that were not completed
1064
+ * within N days of starting, which frees the parts they hold.
1065
+ */
1066
+ interface AbortMultipartRuleInput {
1067
+ /** Unique rule id, 1 to 255 characters (the AWS limit). */
1068
+ id: string;
1069
+ /**
1070
+ * Key prefix the rule applies to, relative to the module's `keyPrefix`. May be empty, which means
1071
+ * every upload in the module's namespace: unlike expiration, aborting a stale upload deletes no object.
1072
+ */
1073
+ prefix: string;
1074
+ /** Days after an upload starts until it is aborted. A positive integer. */
1075
+ abortIncompleteMultipartDays: number;
1076
+ /** A rule is an expiration or an abort rule, never both. */
1077
+ expirationDays?: never;
1078
+ }
1079
+ /** Either rule shape `BucketLifecycleService.upsert()` accepts. */
1080
+ type LifecycleRuleInput = ExpirationRuleInput | AbortMultipartRuleInput;
1081
+
1082
+ /**
1083
+ * Manages the bucket's lifecycle configuration without disturbing rules it did
1084
+ * not write.
1085
+ *
1086
+ * Concurrency: `upsert` and `remove` read the configuration, change it in memory
1087
+ * and write all of it back. S3 has no conditional write for lifecycle
1088
+ * configuration, so another writer that changes the bucket between the read and
1089
+ * the write is overwritten. Serialize lifecycle changes in the caller (one
1090
+ * operator command, or a single deployment step) rather than relying on this
1091
+ * service to lock.
1092
+ */
1093
+ declare class BucketLifecycleService {
1094
+ private readonly options;
1095
+ private readonly s3Provider;
1096
+ private readonly keyResolver;
1097
+ constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
1098
+ /**
1099
+ * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
1100
+ * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
1101
+ * relative to it, as `list()` returns keys, so a prefix read here can be passed
1102
+ * straight to `upsert()` without being prefixed twice. A rule that is not confined
1103
+ * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
1104
+ * everything else about a rule is returned as the provider stores it.
1105
+ *
1106
+ * @param options - Optional per-call bucket override.
1107
+ * @returns Every rule in the bucket.
1108
+ * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
1109
+ */
1110
+ get(options?: LifecycleBucketOptions): Promise<BucketLifecycleRuleView[]>;
1111
+ /**
1112
+ * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
1113
+ * the full set back. Rules with other ids are sent exactly as they were read.
1114
+ *
1115
+ * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
1116
+ * @param options - Optional per-call bucket override.
1117
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
1118
+ * that names a rule outside `keyPrefix`;
1119
+ * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
1120
+ * @example
1121
+ * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
1122
+ */
1123
+ upsert(rule: LifecycleRuleInput, options?: LifecycleBucketOptions): Promise<void>;
1124
+ /**
1125
+ * Removes the rule with this id. When it was the last rule the configuration is
1126
+ * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
1127
+ *
1128
+ * @param id - The rule id.
1129
+ * @param options - Optional per-call bucket override.
1130
+ * @returns `true` when a rule was removed, `false` when no rule had that id.
1131
+ * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
1132
+ * outside `keyPrefix`; a provider failure otherwise.
1133
+ */
1134
+ remove(id: string, options?: LifecycleBucketOptions): Promise<boolean>;
1135
+ /**
1136
+ * Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
1137
+ * with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
1138
+ * (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
1139
+ */
1140
+ private isWithinKeyPrefix;
1141
+ /** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
1142
+ private toView;
1143
+ /** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
1144
+ private assertOwnable;
1145
+ /**
1146
+ * Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
1147
+ * carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
1148
+ * `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
1149
+ */
1150
+ private stripRulePrefixes;
1151
+ /** Reads the configuration; "none yet" is an empty snapshot. */
1152
+ private read;
1153
+ /**
1154
+ * Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
1155
+ * requires at least one rule on a put. The default-minimum-object-size setting
1156
+ * read earlier is sent back so a write does not silently change transition behaviour.
1157
+ */
1158
+ private write;
1159
+ /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
1160
+ private toRule;
1161
+ private assertRuleId;
1162
+ private assertConfigured;
1163
+ private resolveBucket;
1164
+ }
1165
+
1002
1166
  /**
1003
1167
  * @fileoverview No-operation upload validator — always passes. Use as the
1004
1168
  * default when no custom validation logic is needed.
@@ -1180,6 +1344,11 @@ declare const STORAGE_ERROR_CODES: {
1180
1344
  readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
1181
1345
  readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
1182
1346
  readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
1347
+ readonly STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID";
1348
+ readonly STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED";
1349
+ readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
1350
+ readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
1351
+ readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
1183
1352
  };
1184
1353
  /** Union of every stable storage error code. */
1185
1354
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1205,4 +1374,4 @@ declare class StorageException extends HttpException {
1205
1374
  statusCode?: HttpStatus, details?: Record<string, unknown>);
1206
1375
  }
1207
1376
 
1208
- export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
1377
+ export { type AbortMultipartRuleInput, BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, type BucketLifecycleRule, type BucketLifecycleRuleView, BucketLifecycleService, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type ExpirationRuleInput, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type LifecycleBucketOptions, type LifecycleRuleInput, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };