@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.
- package/CHANGELOG.md +182 -2
- package/README.md +246 -57
- package/dist/server/index.cjs +443 -50
- package/dist/server/index.d.cts +168 -8
- package/dist/server/index.d.ts +168 -8
- package/dist/server/index.mjs +445 -50
- package/dist/shared/index.cjs +8 -1
- package/dist/shared/index.d.cts +6 -1
- package/dist/shared/index.d.ts +6 -1
- package/dist/shared/index.mjs +8 -1
- package/package.json +3 -3
package/dist/server/index.d.cts
CHANGED
|
@@ -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
|
|
@@ -360,7 +360,7 @@ interface DownloadOptions {
|
|
|
360
360
|
*/
|
|
361
361
|
/** Outcome of an upload — returned to the caller. */
|
|
362
362
|
interface UploadResult {
|
|
363
|
-
/**
|
|
363
|
+
/** The object key relative to `keyPrefix`: pass it back to any method as is. */
|
|
364
364
|
key: string;
|
|
365
365
|
bucket: string;
|
|
366
366
|
etag: string;
|
|
@@ -712,17 +712,33 @@ declare class StorageService {
|
|
|
712
712
|
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
713
713
|
* window, the cached result is returned without re-uploading.
|
|
714
714
|
*
|
|
715
|
+
* The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
|
|
716
|
+
* upload is rejected for any reason (configuration, validation, scan, provider failure)
|
|
717
|
+
* the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
|
|
718
|
+
* that nothing listens to), which releases the file handle or socket behind it; a cache hit
|
|
719
|
+
* destroys it unread. A stream consumed by a successful upload ends on its own.
|
|
720
|
+
*
|
|
715
721
|
* @param options - The upload request.
|
|
716
722
|
* @returns The upload result.
|
|
717
723
|
* @throws StorageException for missing configuration, body, or content type.
|
|
718
724
|
*/
|
|
719
725
|
upload(options: UploadOptions): Promise<UploadResult>;
|
|
726
|
+
/** The upload itself; `upload()` destroys a stream body when this rejects. */
|
|
727
|
+
private uploadOwningBody;
|
|
728
|
+
/**
|
|
729
|
+
* In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
|
|
730
|
+
* and the upload see the same bytes; a stream is single-use, and one the scanner
|
|
731
|
+
* had consumed would leave the upload with nothing to send. The read is bounded by
|
|
732
|
+
* `validation.maxSizeBytes`, and a stream with no bound is refused rather than
|
|
733
|
+
* buffered without limit. Other bodies and modes pass through unchanged.
|
|
734
|
+
*/
|
|
735
|
+
private bufferForPreUploadScan;
|
|
720
736
|
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
721
737
|
private runPreUploadScan;
|
|
722
738
|
/**
|
|
723
|
-
* Coerces
|
|
724
|
-
*
|
|
725
|
-
*
|
|
739
|
+
* Coerces the scan body to a `Buffer` so the scanner always receives its declared
|
|
740
|
+
* contract type. In pre-upload mode a stream has already been buffered by
|
|
741
|
+
* {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
|
|
726
742
|
*/
|
|
727
743
|
private normalizeScanBody;
|
|
728
744
|
/**
|
|
@@ -987,6 +1003,7 @@ declare class SignedUrlService {
|
|
|
987
1003
|
* @param options - The multipart URL options.
|
|
988
1004
|
* @returns `uploadId`, `partUrls`, and `completeUrl`.
|
|
989
1005
|
* @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
|
|
1006
|
+
* @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
|
|
990
1007
|
* @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
|
|
991
1008
|
* @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
|
|
992
1009
|
*/
|
|
@@ -999,6 +1016,146 @@ declare class SignedUrlService {
|
|
|
999
1016
|
private resolveBucket;
|
|
1000
1017
|
}
|
|
1001
1018
|
|
|
1019
|
+
/**
|
|
1020
|
+
* @fileoverview Public contracts for `BucketLifecycleService`: the rule shape
|
|
1021
|
+
* the library owns, the per-call bucket override, and the provider rule type.
|
|
1022
|
+
* @layer server/interfaces
|
|
1023
|
+
*/
|
|
1024
|
+
|
|
1025
|
+
/**
|
|
1026
|
+
* A lifecycle rule exactly as the provider stores it. Reads return every rule in
|
|
1027
|
+
* the bucket, including ones this library did not write (transitions, tag
|
|
1028
|
+
* filters, multipart aborts), and writes send them back unchanged.
|
|
1029
|
+
*/
|
|
1030
|
+
type BucketLifecycleRule = LifecycleRule;
|
|
1031
|
+
/**
|
|
1032
|
+
* A rule as `get()` returns it. `isOutsideKeyPrefix` is set (to `true`) only on a rule
|
|
1033
|
+
* that is not confined to the module's `keyPrefix` — written by another application, or
|
|
1034
|
+
* by hand — and `upsert()` / `remove()` refuse to change such a rule.
|
|
1035
|
+
*/
|
|
1036
|
+
type BucketLifecycleRuleView = BucketLifecycleRule & {
|
|
1037
|
+
isOutsideKeyPrefix?: true;
|
|
1038
|
+
};
|
|
1039
|
+
/** Per-call override of the target bucket. */
|
|
1040
|
+
interface LifecycleBucketOptions {
|
|
1041
|
+
/** Defaults to the module's configured bucket. */
|
|
1042
|
+
bucket?: string;
|
|
1043
|
+
}
|
|
1044
|
+
/** A rule `BucketLifecycleService.upsert()` writes: expire a prefix after N days. */
|
|
1045
|
+
interface ExpirationRuleInput {
|
|
1046
|
+
/** Unique rule id, 1 to 255 characters (the AWS limit). */
|
|
1047
|
+
id: string;
|
|
1048
|
+
/** Key prefix the rule applies to. Relative to the module's `keyPrefix`, like every other key. */
|
|
1049
|
+
prefix: string;
|
|
1050
|
+
/** Days after creation until an object under the prefix expires. A positive integer. */
|
|
1051
|
+
expirationDays: number;
|
|
1052
|
+
/** A rule is an expiration or an abort rule, never both. */
|
|
1053
|
+
abortIncompleteMultipartDays?: never;
|
|
1054
|
+
}
|
|
1055
|
+
/**
|
|
1056
|
+
* A rule `BucketLifecycleService.upsert()` writes: abort multipart uploads that were not completed
|
|
1057
|
+
* within N days of starting, which frees the parts they hold.
|
|
1058
|
+
*/
|
|
1059
|
+
interface AbortMultipartRuleInput {
|
|
1060
|
+
/** Unique rule id, 1 to 255 characters (the AWS limit). */
|
|
1061
|
+
id: string;
|
|
1062
|
+
/**
|
|
1063
|
+
* Key prefix the rule applies to, relative to the module's `keyPrefix`. May be empty, which means
|
|
1064
|
+
* every upload in the module's namespace: unlike expiration, aborting a stale upload deletes no object.
|
|
1065
|
+
*/
|
|
1066
|
+
prefix: string;
|
|
1067
|
+
/** Days after an upload starts until it is aborted. A positive integer. */
|
|
1068
|
+
abortIncompleteMultipartDays: number;
|
|
1069
|
+
/** A rule is an expiration or an abort rule, never both. */
|
|
1070
|
+
expirationDays?: never;
|
|
1071
|
+
}
|
|
1072
|
+
/** Either rule shape `BucketLifecycleService.upsert()` accepts. */
|
|
1073
|
+
type LifecycleRuleInput = ExpirationRuleInput | AbortMultipartRuleInput;
|
|
1074
|
+
|
|
1075
|
+
/**
|
|
1076
|
+
* Manages the bucket's lifecycle configuration without disturbing rules it did
|
|
1077
|
+
* not write.
|
|
1078
|
+
*
|
|
1079
|
+
* Concurrency: `upsert` and `remove` read the configuration, change it in memory
|
|
1080
|
+
* and write all of it back. S3 has no conditional write for lifecycle
|
|
1081
|
+
* configuration, so another writer that changes the bucket between the read and
|
|
1082
|
+
* the write is overwritten. Serialize lifecycle changes in the caller (one
|
|
1083
|
+
* operator command, or a single deployment step) rather than relying on this
|
|
1084
|
+
* service to lock.
|
|
1085
|
+
*/
|
|
1086
|
+
declare class BucketLifecycleService {
|
|
1087
|
+
private readonly options;
|
|
1088
|
+
private readonly s3Provider;
|
|
1089
|
+
private readonly keyResolver;
|
|
1090
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
|
|
1091
|
+
/**
|
|
1092
|
+
* Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
|
|
1093
|
+
* yields an empty array. Key prefixes inside the module's `keyPrefix` come back
|
|
1094
|
+
* relative to it, as `list()` returns keys, so a prefix read here can be passed
|
|
1095
|
+
* straight to `upsert()` without being prefixed twice. A rule that is not confined
|
|
1096
|
+
* to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
|
|
1097
|
+
* everything else about a rule is returned as the provider stores it.
|
|
1098
|
+
*
|
|
1099
|
+
* @param options - Optional per-call bucket override.
|
|
1100
|
+
* @returns Every rule in the bucket.
|
|
1101
|
+
* @throws StorageException for missing configuration, an unsupported provider, or a provider error.
|
|
1102
|
+
*/
|
|
1103
|
+
get(options?: LifecycleBucketOptions): Promise<BucketLifecycleRuleView[]>;
|
|
1104
|
+
/**
|
|
1105
|
+
* Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
|
|
1106
|
+
* the full set back. Rules with other ids are sent exactly as they were read.
|
|
1107
|
+
*
|
|
1108
|
+
* @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
|
|
1109
|
+
* @param options - Optional per-call bucket override.
|
|
1110
|
+
* @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
|
|
1111
|
+
* that names a rule outside `keyPrefix`;
|
|
1112
|
+
* `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
|
|
1113
|
+
* @example
|
|
1114
|
+
* await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
|
|
1115
|
+
*/
|
|
1116
|
+
upsert(rule: LifecycleRuleInput, options?: LifecycleBucketOptions): Promise<void>;
|
|
1117
|
+
/**
|
|
1118
|
+
* Removes the rule with this id. When it was the last rule the configuration is
|
|
1119
|
+
* deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
|
|
1120
|
+
*
|
|
1121
|
+
* @param id - The rule id.
|
|
1122
|
+
* @param options - Optional per-call bucket override.
|
|
1123
|
+
* @returns `true` when a rule was removed, `false` when no rule had that id.
|
|
1124
|
+
* @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
|
|
1125
|
+
* outside `keyPrefix`; a provider failure otherwise.
|
|
1126
|
+
*/
|
|
1127
|
+
remove(id: string, options?: LifecycleBucketOptions): Promise<boolean>;
|
|
1128
|
+
/**
|
|
1129
|
+
* Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
|
|
1130
|
+
* with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
|
|
1131
|
+
* (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
|
|
1132
|
+
*/
|
|
1133
|
+
private isWithinKeyPrefix;
|
|
1134
|
+
/** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
|
|
1135
|
+
private toView;
|
|
1136
|
+
/** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
|
|
1137
|
+
private assertOwnable;
|
|
1138
|
+
/**
|
|
1139
|
+
* Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
|
|
1140
|
+
* carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
|
|
1141
|
+
* `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
|
|
1142
|
+
*/
|
|
1143
|
+
private stripRulePrefixes;
|
|
1144
|
+
/** Reads the configuration; "none yet" is an empty snapshot. */
|
|
1145
|
+
private read;
|
|
1146
|
+
/**
|
|
1147
|
+
* Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
|
|
1148
|
+
* requires at least one rule on a put. The default-minimum-object-size setting
|
|
1149
|
+
* read earlier is sent back so a write does not silently change transition behaviour.
|
|
1150
|
+
*/
|
|
1151
|
+
private write;
|
|
1152
|
+
/** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
|
|
1153
|
+
private toRule;
|
|
1154
|
+
private assertRuleId;
|
|
1155
|
+
private assertConfigured;
|
|
1156
|
+
private resolveBucket;
|
|
1157
|
+
}
|
|
1158
|
+
|
|
1002
1159
|
/**
|
|
1003
1160
|
* @fileoverview No-operation upload validator — always passes. Use as the
|
|
1004
1161
|
* default when no custom validation logic is needed.
|
|
@@ -1142,8 +1299,6 @@ declare const BYMAX_STORAGE_OPTIONS: unique symbol;
|
|
|
1142
1299
|
declare const BYMAX_STORAGE_S3_CLIENT: unique symbol;
|
|
1143
1300
|
declare const BYMAX_STORAGE_UPLOAD_VALIDATORS: unique symbol;
|
|
1144
1301
|
declare const BYMAX_STORAGE_FILE_SCANNER: unique symbol;
|
|
1145
|
-
declare const BYMAX_STORAGE_LOGGER: unique symbol;
|
|
1146
|
-
declare const BYMAX_STORAGE_IDEMPOTENCY_CACHE: unique symbol;
|
|
1147
1302
|
|
|
1148
1303
|
/**
|
|
1149
1304
|
* @fileoverview Provider-recipe contract — a factory that produces
|
|
@@ -1182,6 +1337,11 @@ declare const STORAGE_ERROR_CODES: {
|
|
|
1182
1337
|
readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
|
|
1183
1338
|
readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
|
|
1184
1339
|
readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
|
|
1340
|
+
readonly STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID";
|
|
1341
|
+
readonly STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED";
|
|
1342
|
+
readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
|
|
1343
|
+
readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
|
|
1344
|
+
readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
|
|
1185
1345
|
};
|
|
1186
1346
|
/** Union of every stable storage error code. */
|
|
1187
1347
|
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
@@ -1207,4 +1367,4 @@ declare class StorageException extends HttpException {
|
|
|
1207
1367
|
statusCode?: HttpStatus, details?: Record<string, unknown>);
|
|
1208
1368
|
}
|
|
1209
1369
|
|
|
1210
|
-
export {
|
|
1370
|
+
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 };
|
package/dist/server/index.d.ts
CHANGED
|
@@ -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
|
|
@@ -360,7 +360,7 @@ interface DownloadOptions {
|
|
|
360
360
|
*/
|
|
361
361
|
/** Outcome of an upload — returned to the caller. */
|
|
362
362
|
interface UploadResult {
|
|
363
|
-
/**
|
|
363
|
+
/** The object key relative to `keyPrefix`: pass it back to any method as is. */
|
|
364
364
|
key: string;
|
|
365
365
|
bucket: string;
|
|
366
366
|
etag: string;
|
|
@@ -712,17 +712,33 @@ declare class StorageService {
|
|
|
712
712
|
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
713
713
|
* window, the cached result is returned without re-uploading.
|
|
714
714
|
*
|
|
715
|
+
* The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
|
|
716
|
+
* upload is rejected for any reason (configuration, validation, scan, provider failure)
|
|
717
|
+
* the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
|
|
718
|
+
* that nothing listens to), which releases the file handle or socket behind it; a cache hit
|
|
719
|
+
* destroys it unread. A stream consumed by a successful upload ends on its own.
|
|
720
|
+
*
|
|
715
721
|
* @param options - The upload request.
|
|
716
722
|
* @returns The upload result.
|
|
717
723
|
* @throws StorageException for missing configuration, body, or content type.
|
|
718
724
|
*/
|
|
719
725
|
upload(options: UploadOptions): Promise<UploadResult>;
|
|
726
|
+
/** The upload itself; `upload()` destroys a stream body when this rejects. */
|
|
727
|
+
private uploadOwningBody;
|
|
728
|
+
/**
|
|
729
|
+
* In pre-upload scan mode a stream body is read into one `Buffer`, so the scanner
|
|
730
|
+
* and the upload see the same bytes; a stream is single-use, and one the scanner
|
|
731
|
+
* had consumed would leave the upload with nothing to send. The read is bounded by
|
|
732
|
+
* `validation.maxSizeBytes`, and a stream with no bound is refused rather than
|
|
733
|
+
* buffered without limit. Other bodies and modes pass through unchanged.
|
|
734
|
+
*/
|
|
735
|
+
private bufferForPreUploadScan;
|
|
720
736
|
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
721
737
|
private runPreUploadScan;
|
|
722
738
|
/**
|
|
723
|
-
* Coerces
|
|
724
|
-
*
|
|
725
|
-
*
|
|
739
|
+
* Coerces the scan body to a `Buffer` so the scanner always receives its declared
|
|
740
|
+
* contract type. In pre-upload mode a stream has already been buffered by
|
|
741
|
+
* {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
|
|
726
742
|
*/
|
|
727
743
|
private normalizeScanBody;
|
|
728
744
|
/**
|
|
@@ -987,6 +1003,7 @@ declare class SignedUrlService {
|
|
|
987
1003
|
* @param options - The multipart URL options.
|
|
988
1004
|
* @returns `uploadId`, `partUrls`, and `completeUrl`.
|
|
989
1005
|
* @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
|
|
1006
|
+
* @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
|
|
990
1007
|
* @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
|
|
991
1008
|
* @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
|
|
992
1009
|
*/
|
|
@@ -999,6 +1016,146 @@ declare class SignedUrlService {
|
|
|
999
1016
|
private resolveBucket;
|
|
1000
1017
|
}
|
|
1001
1018
|
|
|
1019
|
+
/**
|
|
1020
|
+
* @fileoverview Public contracts for `BucketLifecycleService`: the rule shape
|
|
1021
|
+
* the library owns, the per-call bucket override, and the provider rule type.
|
|
1022
|
+
* @layer server/interfaces
|
|
1023
|
+
*/
|
|
1024
|
+
|
|
1025
|
+
/**
|
|
1026
|
+
* A lifecycle rule exactly as the provider stores it. Reads return every rule in
|
|
1027
|
+
* the bucket, including ones this library did not write (transitions, tag
|
|
1028
|
+
* filters, multipart aborts), and writes send them back unchanged.
|
|
1029
|
+
*/
|
|
1030
|
+
type BucketLifecycleRule = LifecycleRule;
|
|
1031
|
+
/**
|
|
1032
|
+
* A rule as `get()` returns it. `isOutsideKeyPrefix` is set (to `true`) only on a rule
|
|
1033
|
+
* that is not confined to the module's `keyPrefix` — written by another application, or
|
|
1034
|
+
* by hand — and `upsert()` / `remove()` refuse to change such a rule.
|
|
1035
|
+
*/
|
|
1036
|
+
type BucketLifecycleRuleView = BucketLifecycleRule & {
|
|
1037
|
+
isOutsideKeyPrefix?: true;
|
|
1038
|
+
};
|
|
1039
|
+
/** Per-call override of the target bucket. */
|
|
1040
|
+
interface LifecycleBucketOptions {
|
|
1041
|
+
/** Defaults to the module's configured bucket. */
|
|
1042
|
+
bucket?: string;
|
|
1043
|
+
}
|
|
1044
|
+
/** A rule `BucketLifecycleService.upsert()` writes: expire a prefix after N days. */
|
|
1045
|
+
interface ExpirationRuleInput {
|
|
1046
|
+
/** Unique rule id, 1 to 255 characters (the AWS limit). */
|
|
1047
|
+
id: string;
|
|
1048
|
+
/** Key prefix the rule applies to. Relative to the module's `keyPrefix`, like every other key. */
|
|
1049
|
+
prefix: string;
|
|
1050
|
+
/** Days after creation until an object under the prefix expires. A positive integer. */
|
|
1051
|
+
expirationDays: number;
|
|
1052
|
+
/** A rule is an expiration or an abort rule, never both. */
|
|
1053
|
+
abortIncompleteMultipartDays?: never;
|
|
1054
|
+
}
|
|
1055
|
+
/**
|
|
1056
|
+
* A rule `BucketLifecycleService.upsert()` writes: abort multipart uploads that were not completed
|
|
1057
|
+
* within N days of starting, which frees the parts they hold.
|
|
1058
|
+
*/
|
|
1059
|
+
interface AbortMultipartRuleInput {
|
|
1060
|
+
/** Unique rule id, 1 to 255 characters (the AWS limit). */
|
|
1061
|
+
id: string;
|
|
1062
|
+
/**
|
|
1063
|
+
* Key prefix the rule applies to, relative to the module's `keyPrefix`. May be empty, which means
|
|
1064
|
+
* every upload in the module's namespace: unlike expiration, aborting a stale upload deletes no object.
|
|
1065
|
+
*/
|
|
1066
|
+
prefix: string;
|
|
1067
|
+
/** Days after an upload starts until it is aborted. A positive integer. */
|
|
1068
|
+
abortIncompleteMultipartDays: number;
|
|
1069
|
+
/** A rule is an expiration or an abort rule, never both. */
|
|
1070
|
+
expirationDays?: never;
|
|
1071
|
+
}
|
|
1072
|
+
/** Either rule shape `BucketLifecycleService.upsert()` accepts. */
|
|
1073
|
+
type LifecycleRuleInput = ExpirationRuleInput | AbortMultipartRuleInput;
|
|
1074
|
+
|
|
1075
|
+
/**
|
|
1076
|
+
* Manages the bucket's lifecycle configuration without disturbing rules it did
|
|
1077
|
+
* not write.
|
|
1078
|
+
*
|
|
1079
|
+
* Concurrency: `upsert` and `remove` read the configuration, change it in memory
|
|
1080
|
+
* and write all of it back. S3 has no conditional write for lifecycle
|
|
1081
|
+
* configuration, so another writer that changes the bucket between the read and
|
|
1082
|
+
* the write is overwritten. Serialize lifecycle changes in the caller (one
|
|
1083
|
+
* operator command, or a single deployment step) rather than relying on this
|
|
1084
|
+
* service to lock.
|
|
1085
|
+
*/
|
|
1086
|
+
declare class BucketLifecycleService {
|
|
1087
|
+
private readonly options;
|
|
1088
|
+
private readonly s3Provider;
|
|
1089
|
+
private readonly keyResolver;
|
|
1090
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
|
|
1091
|
+
/**
|
|
1092
|
+
* Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
|
|
1093
|
+
* yields an empty array. Key prefixes inside the module's `keyPrefix` come back
|
|
1094
|
+
* relative to it, as `list()` returns keys, so a prefix read here can be passed
|
|
1095
|
+
* straight to `upsert()` without being prefixed twice. A rule that is not confined
|
|
1096
|
+
* to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
|
|
1097
|
+
* everything else about a rule is returned as the provider stores it.
|
|
1098
|
+
*
|
|
1099
|
+
* @param options - Optional per-call bucket override.
|
|
1100
|
+
* @returns Every rule in the bucket.
|
|
1101
|
+
* @throws StorageException for missing configuration, an unsupported provider, or a provider error.
|
|
1102
|
+
*/
|
|
1103
|
+
get(options?: LifecycleBucketOptions): Promise<BucketLifecycleRuleView[]>;
|
|
1104
|
+
/**
|
|
1105
|
+
* Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
|
|
1106
|
+
* the full set back. Rules with other ids are sent exactly as they were read.
|
|
1107
|
+
*
|
|
1108
|
+
* @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
|
|
1109
|
+
* @param options - Optional per-call bucket override.
|
|
1110
|
+
* @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
|
|
1111
|
+
* that names a rule outside `keyPrefix`;
|
|
1112
|
+
* `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
|
|
1113
|
+
* @example
|
|
1114
|
+
* await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
|
|
1115
|
+
*/
|
|
1116
|
+
upsert(rule: LifecycleRuleInput, options?: LifecycleBucketOptions): Promise<void>;
|
|
1117
|
+
/**
|
|
1118
|
+
* Removes the rule with this id. When it was the last rule the configuration is
|
|
1119
|
+
* deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
|
|
1120
|
+
*
|
|
1121
|
+
* @param id - The rule id.
|
|
1122
|
+
* @param options - Optional per-call bucket override.
|
|
1123
|
+
* @returns `true` when a rule was removed, `false` when no rule had that id.
|
|
1124
|
+
* @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
|
|
1125
|
+
* outside `keyPrefix`; a provider failure otherwise.
|
|
1126
|
+
*/
|
|
1127
|
+
remove(id: string, options?: LifecycleBucketOptions): Promise<boolean>;
|
|
1128
|
+
/**
|
|
1129
|
+
* Whether the rule is confined to this module's `keyPrefix`: its filter prefix starts
|
|
1130
|
+
* with it. Without a `keyPrefix` every rule is in scope. A rule with no prefix at all
|
|
1131
|
+
* (tag-only, or the whole bucket) reaches beyond the namespace, so it is not confined.
|
|
1132
|
+
*/
|
|
1133
|
+
private isWithinKeyPrefix;
|
|
1134
|
+
/** The caller's view of a rule: prefixes relative to `keyPrefix`, or as stored and flagged when outside it. */
|
|
1135
|
+
private toView;
|
|
1136
|
+
/** Refuses to replace or remove a rule this module's `keyPrefix` does not confine. */
|
|
1137
|
+
private assertOwnable;
|
|
1138
|
+
/**
|
|
1139
|
+
* Returns a copy of the rule with `keyPrefix` removed from each filter prefix that
|
|
1140
|
+
* carries it (`Filter.Prefix`, `Filter.And.Prefix` and the deprecated rule-level
|
|
1141
|
+
* `Prefix`). Prefixes outside the namespace are left alone. The stored rule is never touched.
|
|
1142
|
+
*/
|
|
1143
|
+
private stripRulePrefixes;
|
|
1144
|
+
/** Reads the configuration; "none yet" is an empty snapshot. */
|
|
1145
|
+
private read;
|
|
1146
|
+
/**
|
|
1147
|
+
* Writes the rule set. An empty set is a `DeleteBucketLifecycle`, since S3
|
|
1148
|
+
* requires at least one rule on a put. The default-minimum-object-size setting
|
|
1149
|
+
* read earlier is sent back so a write does not silently change transition behaviour.
|
|
1150
|
+
*/
|
|
1151
|
+
private write;
|
|
1152
|
+
/** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
|
|
1153
|
+
private toRule;
|
|
1154
|
+
private assertRuleId;
|
|
1155
|
+
private assertConfigured;
|
|
1156
|
+
private resolveBucket;
|
|
1157
|
+
}
|
|
1158
|
+
|
|
1002
1159
|
/**
|
|
1003
1160
|
* @fileoverview No-operation upload validator — always passes. Use as the
|
|
1004
1161
|
* default when no custom validation logic is needed.
|
|
@@ -1142,8 +1299,6 @@ declare const BYMAX_STORAGE_OPTIONS: unique symbol;
|
|
|
1142
1299
|
declare const BYMAX_STORAGE_S3_CLIENT: unique symbol;
|
|
1143
1300
|
declare const BYMAX_STORAGE_UPLOAD_VALIDATORS: unique symbol;
|
|
1144
1301
|
declare const BYMAX_STORAGE_FILE_SCANNER: unique symbol;
|
|
1145
|
-
declare const BYMAX_STORAGE_LOGGER: unique symbol;
|
|
1146
|
-
declare const BYMAX_STORAGE_IDEMPOTENCY_CACHE: unique symbol;
|
|
1147
1302
|
|
|
1148
1303
|
/**
|
|
1149
1304
|
* @fileoverview Provider-recipe contract — a factory that produces
|
|
@@ -1182,6 +1337,11 @@ declare const STORAGE_ERROR_CODES: {
|
|
|
1182
1337
|
readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
|
|
1183
1338
|
readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
|
|
1184
1339
|
readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
|
|
1340
|
+
readonly STORAGE_LIFECYCLE_RULE_INVALID: "STORAGE_LIFECYCLE_RULE_INVALID";
|
|
1341
|
+
readonly STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED";
|
|
1342
|
+
readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
|
|
1343
|
+
readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
|
|
1344
|
+
readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
|
|
1185
1345
|
};
|
|
1186
1346
|
/** Union of every stable storage error code. */
|
|
1187
1347
|
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
@@ -1207,4 +1367,4 @@ declare class StorageException extends HttpException {
|
|
|
1207
1367
|
statusCode?: HttpStatus, details?: Record<string, unknown>);
|
|
1208
1368
|
}
|
|
1209
1369
|
|
|
1210
|
-
export {
|
|
1370
|
+
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 };
|