@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.
- package/CHANGELOG.md +148 -1
- package/README.md +238 -53
- package/dist/server/index.cjs +538 -53
- package/dist/server/index.d.cts +175 -6
- package/dist/server/index.d.ts +175 -6
- package/dist/server/index.mjs +541 -56
- 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 +1 -1
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
|
|
@@ -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
|
-
/**
|
|
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
|
|
724
|
-
*
|
|
725
|
-
*
|
|
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 };
|
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
|
|
@@ -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
|
-
/**
|
|
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
|
|
724
|
-
*
|
|
725
|
-
*
|
|
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 };
|