@bymax-one/nest-storage 1.1.10 → 1.1.12
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 +160 -1
- package/README.md +321 -362
- package/dist/server/index.cjs +559 -182
- package/dist/server/index.d.cts +70 -36
- package/dist/server/index.d.ts +70 -36
- package/dist/server/index.mjs +560 -183
- package/dist/shared/index.cjs +2 -1
- package/dist/shared/index.d.cts +1 -0
- package/dist/shared/index.d.ts +1 -0
- package/dist/shared/index.mjs +2 -1
- package/package.json +1 -1
package/dist/server/index.d.cts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException
|
|
1
|
+
import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException } from '@nestjs/common';
|
|
2
2
|
import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
|
|
3
3
|
|
|
4
4
|
/**
|
|
@@ -139,7 +139,10 @@ interface BymaxStorageModuleOptions {
|
|
|
139
139
|
validation?: {
|
|
140
140
|
/** MIME whitelist — supports wildcards like `'image/*'`. */
|
|
141
141
|
mimeWhitelist?: readonly string[];
|
|
142
|
-
/**
|
|
142
|
+
/**
|
|
143
|
+
* Max upload size in bytes. A buffer is checked by its length and a stream is counted as it
|
|
144
|
+
* is read, so the limit holds whether or not the caller declares `size`.
|
|
145
|
+
*/
|
|
143
146
|
maxSizeBytes?: number;
|
|
144
147
|
/** Custom validators run in order; the first rejection short-circuits. */
|
|
145
148
|
customValidators?: readonly IUploadValidator[];
|
|
@@ -164,16 +167,24 @@ interface BymaxStorageModuleOptions {
|
|
|
164
167
|
requestChecksumCalculation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
165
168
|
/** S3Client `responseChecksumValidation` (checksum mode on GET). Same provider caveat. */
|
|
166
169
|
responseChecksumValidation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
167
|
-
/** Total attempts including the first try (maps to `maxAttempts`). Default: `3`. */
|
|
170
|
+
/** Total attempts including the first try (maps to `maxAttempts`). An integer of at least `1`. Default: `3`. */
|
|
168
171
|
maxAttempts?: number;
|
|
169
|
-
/** Per-
|
|
172
|
+
/** Per-attempt timeout until the response headers arrive. An integer from `1` to `2147483647` (the longest a timer holds). Default: `30000` ms. */
|
|
170
173
|
requestTimeoutMs?: number;
|
|
171
174
|
/**
|
|
172
175
|
* Longest silence, in milliseconds, tolerated from a stream body while a multipart upload
|
|
173
176
|
* waits for its next bytes; past it the upload is aborted and rejects `STORAGE_TIMEOUT`.
|
|
174
|
-
* An integer
|
|
177
|
+
* An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard off. Default: `requestTimeoutMs`.
|
|
175
178
|
*/
|
|
176
179
|
uploadIdleTimeoutMs?: number;
|
|
180
|
+
/**
|
|
181
|
+
* Longest silence, in milliseconds, tolerated from a download body while the caller is waiting
|
|
182
|
+
* for its next bytes; past it the stream fails with `STORAGE_TIMEOUT` (`details.phase` is
|
|
183
|
+
* `'body-idle'`) and the connection is released. The clock runs only while a read is pending, so
|
|
184
|
+
* a consumer that is slow to read never trips it. An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard
|
|
185
|
+
* off. Default: `requestTimeoutMs`.
|
|
186
|
+
*/
|
|
187
|
+
bodyIdleTimeoutMs?: number;
|
|
177
188
|
}
|
|
178
189
|
/**
|
|
179
190
|
* Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
|
|
@@ -303,6 +314,7 @@ interface ResolvedBymaxStorageOptions {
|
|
|
303
314
|
maxAttempts: number;
|
|
304
315
|
requestTimeoutMs: number;
|
|
305
316
|
uploadIdleTimeoutMs: number;
|
|
317
|
+
bodyIdleTimeoutMs: number;
|
|
306
318
|
/** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
|
|
307
319
|
hasCredentials: boolean;
|
|
308
320
|
}
|
|
@@ -335,6 +347,14 @@ interface UploadOptions {
|
|
|
335
347
|
* cached `UploadResult` is returned without re-uploading.
|
|
336
348
|
*/
|
|
337
349
|
idempotencyKey?: string;
|
|
350
|
+
/**
|
|
351
|
+
* Ends the upload when it aborts: the request is dropped, a multipart upload is aborted so no part
|
|
352
|
+
* stays stored, and the call rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the
|
|
353
|
+
* signal's reason name and, for multipart, `details.abort`. A signal that is already aborted makes
|
|
354
|
+
* no request. As for any rejected upload, a stream `body` is destroyed. The library keeps no
|
|
355
|
+
* listener on the signal after the call.
|
|
356
|
+
*/
|
|
357
|
+
abortSignal?: AbortSignal;
|
|
338
358
|
/** Progress callback fired after each multipart part (or once for single). */
|
|
339
359
|
onProgress?: (event: {
|
|
340
360
|
loaded: number;
|
|
@@ -344,7 +364,7 @@ interface UploadOptions {
|
|
|
344
364
|
}
|
|
345
365
|
|
|
346
366
|
/**
|
|
347
|
-
* @fileoverview Per-call options for `StorageService.download()`.
|
|
367
|
+
* @fileoverview Per-call options for `StorageService.download()` and `downloadBuffer()`.
|
|
348
368
|
* @layer server/interfaces
|
|
349
369
|
*/
|
|
350
370
|
/** Options for a single download call. */
|
|
@@ -357,6 +377,25 @@ interface DownloadOptions {
|
|
|
357
377
|
ifNoneMatch?: string;
|
|
358
378
|
/** Conditional GET — only return if the ETag matches. */
|
|
359
379
|
ifMatch?: string;
|
|
380
|
+
/**
|
|
381
|
+
* Ends the call when it aborts: the request is dropped and the call rejects
|
|
382
|
+
* `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal that is
|
|
383
|
+
* already aborted makes no request. A body stream already returned errors too: as
|
|
384
|
+
* `STORAGE_REQUEST_ABORTED` while the idle guard is on (the default `bodyIdleTimeoutMs`), as the
|
|
385
|
+
* raw `AbortError` when `bodyIdleTimeoutMs` is `0`. The library keeps no listener on the signal
|
|
386
|
+
* after the call.
|
|
387
|
+
*/
|
|
388
|
+
abortSignal?: AbortSignal;
|
|
389
|
+
}
|
|
390
|
+
/** Options for a single `downloadBuffer()` call. */
|
|
391
|
+
interface DownloadBufferOptions extends DownloadOptions {
|
|
392
|
+
/**
|
|
393
|
+
* The most bytes `downloadBuffer()` will hold. An object whose `Content-Length` is larger is
|
|
394
|
+
* refused before its body is read, and a body that turns out longer than this (a missing or
|
|
395
|
+
* wrong `Content-Length`) is cut off as it is counted; both reject `STORAGE_SIZE_EXCEEDED` and
|
|
396
|
+
* release the connection. An integer of at least `1`. Without it the whole object is buffered.
|
|
397
|
+
*/
|
|
398
|
+
maxBytes?: number;
|
|
360
399
|
}
|
|
361
400
|
|
|
362
401
|
/**
|
|
@@ -425,6 +464,12 @@ interface ListOptions {
|
|
|
425
464
|
* sub-prefixes are aggregated into `commonPrefixes`.
|
|
426
465
|
*/
|
|
427
466
|
delimiter?: string;
|
|
467
|
+
/**
|
|
468
|
+
* Ends the call when it aborts: the request is dropped, a multipart upload is aborted and the call
|
|
469
|
+
* rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal
|
|
470
|
+
* that is already aborted makes no request. The library keeps no listener on it after the call.
|
|
471
|
+
*/
|
|
472
|
+
abortSignal?: AbortSignal;
|
|
428
473
|
}
|
|
429
474
|
/** Result of a single list call. */
|
|
430
475
|
interface ListResult {
|
|
@@ -725,6 +770,8 @@ declare class IdempotencyCache {
|
|
|
725
770
|
/** Per-call options that only need to override the target bucket. */
|
|
726
771
|
interface BucketScopedOptions {
|
|
727
772
|
bucket?: string;
|
|
773
|
+
/** Ends the call when it aborts, rejecting `STORAGE_REQUEST_ABORTED`; an aborted signal makes no request. */
|
|
774
|
+
abortSignal?: AbortSignal;
|
|
728
775
|
}
|
|
729
776
|
declare class StorageService {
|
|
730
777
|
private readonly options;
|
|
@@ -763,12 +810,8 @@ declare class StorageService {
|
|
|
763
810
|
private bufferForPreUploadScan;
|
|
764
811
|
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
765
812
|
private runPreUploadScan;
|
|
766
|
-
/**
|
|
767
|
-
|
|
768
|
-
* contract type. In pre-upload mode a stream has already been buffered by
|
|
769
|
-
* {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
|
|
770
|
-
*/
|
|
771
|
-
private normalizeScanBody;
|
|
813
|
+
/** Remembers the result of an upload under its idempotency key, when it has one. */
|
|
814
|
+
private rememberUpload;
|
|
772
815
|
/**
|
|
773
816
|
* Runs a post-upload scan. On infection, deletes the just-uploaded object
|
|
774
817
|
* (logging delete failures as errors) and re-throws the scan exception.
|
|
@@ -815,13 +858,15 @@ declare class StorageService {
|
|
|
815
858
|
metadata: ObjectMetadata;
|
|
816
859
|
}>;
|
|
817
860
|
/**
|
|
818
|
-
*
|
|
819
|
-
*
|
|
861
|
+
* Reads an object fully into memory through the same idle-guarded stream as {@link download}.
|
|
862
|
+
* Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
|
|
820
863
|
*
|
|
821
|
-
* @param options - The download request.
|
|
864
|
+
* @param options - The download request; `maxBytes` is the most bytes to hold.
|
|
822
865
|
* @returns The object buffer and its metadata.
|
|
866
|
+
* @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
|
|
867
|
+
* bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
|
|
823
868
|
*/
|
|
824
|
-
downloadBuffer(options:
|
|
869
|
+
downloadBuffer(options: DownloadBufferOptions): Promise<{
|
|
825
870
|
buffer: Buffer;
|
|
826
871
|
metadata: ObjectMetadata;
|
|
827
872
|
}>;
|
|
@@ -849,15 +894,6 @@ declare class StorageService {
|
|
|
849
894
|
private assertConfigured;
|
|
850
895
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
851
896
|
private resolveBucket;
|
|
852
|
-
/** Builds a public URL, avoiding a duplicated bucket segment in the base. */
|
|
853
|
-
private buildPublicUrl;
|
|
854
|
-
/**
|
|
855
|
-
* Reports whether the base URL already carries the bucket as a real segment —
|
|
856
|
-
* the leading host label (virtual-hosted-style `bucket.host`) or a path segment
|
|
857
|
-
* (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
|
|
858
|
-
* so `bucket="test"` is not matched by a `latest` elsewhere in the base.
|
|
859
|
-
*/
|
|
860
|
-
private baseCarriesBucket;
|
|
861
897
|
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
862
898
|
private toObjectMetadata;
|
|
863
899
|
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
@@ -869,16 +905,13 @@ declare class StorageService {
|
|
|
869
905
|
* aborted. This method aborts the upload itself and reports the outcome in the error details.
|
|
870
906
|
*/
|
|
871
907
|
private uploadMultipart;
|
|
872
|
-
/**
|
|
873
|
-
|
|
874
|
-
|
|
908
|
+
/**
|
|
909
|
+
* Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
|
|
910
|
+
* the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
|
|
911
|
+
* real failure into one. An upload id the provider answered late is waited for, within the cleanup
|
|
912
|
+
* deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
|
|
913
|
+
*/
|
|
875
914
|
private failMultipart;
|
|
876
|
-
/** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
|
|
877
|
-
private normalizeSingleShotBody;
|
|
878
|
-
/** Assembles an `UploadResult`, omitting optional fields that are absent. */
|
|
879
|
-
private buildUploadResult;
|
|
880
|
-
/** Emits a progress event, omitting `total`/`part` when they are unknown. */
|
|
881
|
-
private emitProgress;
|
|
882
915
|
/**
|
|
883
916
|
* Lists objects in the bucket as a single page. Applies the global key prefix
|
|
884
917
|
* to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
|
|
@@ -1389,6 +1422,7 @@ declare const STORAGE_ERROR_CODES: {
|
|
|
1389
1422
|
readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
|
|
1390
1423
|
readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
|
|
1391
1424
|
readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
|
|
1425
|
+
readonly STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED";
|
|
1392
1426
|
};
|
|
1393
1427
|
/** Union of every stable storage error code. */
|
|
1394
1428
|
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
@@ -1411,10 +1445,10 @@ declare class StorageException extends HttpException {
|
|
|
1411
1445
|
readonly code: StorageErrorCode;
|
|
1412
1446
|
constructor(code: StorageErrorCode,
|
|
1413
1447
|
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1414
|
-
statusCode?:
|
|
1448
|
+
statusCode?: number, details?: Record<string, unknown>,
|
|
1415
1449
|
/** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
|
|
1416
1450
|
message?: string);
|
|
1417
1451
|
}
|
|
1418
1452
|
|
|
1419
1453
|
export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BucketLifecycleService, BymaxStorageModule, NoOpFileScanner, NoOpUploadValidator, STORAGE_ERROR_CODES, SignedUrlService, StorageException, StorageService, providerRecipes };
|
|
1420
|
-
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
|
|
1454
|
+
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
|
package/dist/server/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException
|
|
1
|
+
import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException } from '@nestjs/common';
|
|
2
2
|
import { S3Client, LifecycleRule } from '@aws-sdk/client-s3';
|
|
3
3
|
|
|
4
4
|
/**
|
|
@@ -139,7 +139,10 @@ interface BymaxStorageModuleOptions {
|
|
|
139
139
|
validation?: {
|
|
140
140
|
/** MIME whitelist — supports wildcards like `'image/*'`. */
|
|
141
141
|
mimeWhitelist?: readonly string[];
|
|
142
|
-
/**
|
|
142
|
+
/**
|
|
143
|
+
* Max upload size in bytes. A buffer is checked by its length and a stream is counted as it
|
|
144
|
+
* is read, so the limit holds whether or not the caller declares `size`.
|
|
145
|
+
*/
|
|
143
146
|
maxSizeBytes?: number;
|
|
144
147
|
/** Custom validators run in order; the first rejection short-circuits. */
|
|
145
148
|
customValidators?: readonly IUploadValidator[];
|
|
@@ -164,16 +167,24 @@ interface BymaxStorageModuleOptions {
|
|
|
164
167
|
requestChecksumCalculation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
165
168
|
/** S3Client `responseChecksumValidation` (checksum mode on GET). Same provider caveat. */
|
|
166
169
|
responseChecksumValidation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
167
|
-
/** Total attempts including the first try (maps to `maxAttempts`). Default: `3`. */
|
|
170
|
+
/** Total attempts including the first try (maps to `maxAttempts`). An integer of at least `1`. Default: `3`. */
|
|
168
171
|
maxAttempts?: number;
|
|
169
|
-
/** Per-
|
|
172
|
+
/** Per-attempt timeout until the response headers arrive. An integer from `1` to `2147483647` (the longest a timer holds). Default: `30000` ms. */
|
|
170
173
|
requestTimeoutMs?: number;
|
|
171
174
|
/**
|
|
172
175
|
* Longest silence, in milliseconds, tolerated from a stream body while a multipart upload
|
|
173
176
|
* waits for its next bytes; past it the upload is aborted and rejects `STORAGE_TIMEOUT`.
|
|
174
|
-
* An integer
|
|
177
|
+
* An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard off. Default: `requestTimeoutMs`.
|
|
175
178
|
*/
|
|
176
179
|
uploadIdleTimeoutMs?: number;
|
|
180
|
+
/**
|
|
181
|
+
* Longest silence, in milliseconds, tolerated from a download body while the caller is waiting
|
|
182
|
+
* for its next bytes; past it the stream fails with `STORAGE_TIMEOUT` (`details.phase` is
|
|
183
|
+
* `'body-idle'`) and the connection is released. The clock runs only while a read is pending, so
|
|
184
|
+
* a consumer that is slow to read never trips it. An integer from `0` to `2147483647` (the longest a timer holds); `0` turns the guard
|
|
185
|
+
* off. Default: `requestTimeoutMs`.
|
|
186
|
+
*/
|
|
187
|
+
bodyIdleTimeoutMs?: number;
|
|
177
188
|
}
|
|
178
189
|
/**
|
|
179
190
|
* Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
|
|
@@ -303,6 +314,7 @@ interface ResolvedBymaxStorageOptions {
|
|
|
303
314
|
maxAttempts: number;
|
|
304
315
|
requestTimeoutMs: number;
|
|
305
316
|
uploadIdleTimeoutMs: number;
|
|
317
|
+
bodyIdleTimeoutMs: number;
|
|
306
318
|
/** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
|
|
307
319
|
hasCredentials: boolean;
|
|
308
320
|
}
|
|
@@ -335,6 +347,14 @@ interface UploadOptions {
|
|
|
335
347
|
* cached `UploadResult` is returned without re-uploading.
|
|
336
348
|
*/
|
|
337
349
|
idempotencyKey?: string;
|
|
350
|
+
/**
|
|
351
|
+
* Ends the upload when it aborts: the request is dropped, a multipart upload is aborted so no part
|
|
352
|
+
* stays stored, and the call rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the
|
|
353
|
+
* signal's reason name and, for multipart, `details.abort`. A signal that is already aborted makes
|
|
354
|
+
* no request. As for any rejected upload, a stream `body` is destroyed. The library keeps no
|
|
355
|
+
* listener on the signal after the call.
|
|
356
|
+
*/
|
|
357
|
+
abortSignal?: AbortSignal;
|
|
338
358
|
/** Progress callback fired after each multipart part (or once for single). */
|
|
339
359
|
onProgress?: (event: {
|
|
340
360
|
loaded: number;
|
|
@@ -344,7 +364,7 @@ interface UploadOptions {
|
|
|
344
364
|
}
|
|
345
365
|
|
|
346
366
|
/**
|
|
347
|
-
* @fileoverview Per-call options for `StorageService.download()`.
|
|
367
|
+
* @fileoverview Per-call options for `StorageService.download()` and `downloadBuffer()`.
|
|
348
368
|
* @layer server/interfaces
|
|
349
369
|
*/
|
|
350
370
|
/** Options for a single download call. */
|
|
@@ -357,6 +377,25 @@ interface DownloadOptions {
|
|
|
357
377
|
ifNoneMatch?: string;
|
|
358
378
|
/** Conditional GET — only return if the ETag matches. */
|
|
359
379
|
ifMatch?: string;
|
|
380
|
+
/**
|
|
381
|
+
* Ends the call when it aborts: the request is dropped and the call rejects
|
|
382
|
+
* `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal that is
|
|
383
|
+
* already aborted makes no request. A body stream already returned errors too: as
|
|
384
|
+
* `STORAGE_REQUEST_ABORTED` while the idle guard is on (the default `bodyIdleTimeoutMs`), as the
|
|
385
|
+
* raw `AbortError` when `bodyIdleTimeoutMs` is `0`. The library keeps no listener on the signal
|
|
386
|
+
* after the call.
|
|
387
|
+
*/
|
|
388
|
+
abortSignal?: AbortSignal;
|
|
389
|
+
}
|
|
390
|
+
/** Options for a single `downloadBuffer()` call. */
|
|
391
|
+
interface DownloadBufferOptions extends DownloadOptions {
|
|
392
|
+
/**
|
|
393
|
+
* The most bytes `downloadBuffer()` will hold. An object whose `Content-Length` is larger is
|
|
394
|
+
* refused before its body is read, and a body that turns out longer than this (a missing or
|
|
395
|
+
* wrong `Content-Length`) is cut off as it is counted; both reject `STORAGE_SIZE_EXCEEDED` and
|
|
396
|
+
* release the connection. An integer of at least `1`. Without it the whole object is buffered.
|
|
397
|
+
*/
|
|
398
|
+
maxBytes?: number;
|
|
360
399
|
}
|
|
361
400
|
|
|
362
401
|
/**
|
|
@@ -425,6 +464,12 @@ interface ListOptions {
|
|
|
425
464
|
* sub-prefixes are aggregated into `commonPrefixes`.
|
|
426
465
|
*/
|
|
427
466
|
delimiter?: string;
|
|
467
|
+
/**
|
|
468
|
+
* Ends the call when it aborts: the request is dropped, a multipart upload is aborted and the call
|
|
469
|
+
* rejects `STORAGE_REQUEST_ABORTED` with `details.reason` set to the signal's reason name. A signal
|
|
470
|
+
* that is already aborted makes no request. The library keeps no listener on it after the call.
|
|
471
|
+
*/
|
|
472
|
+
abortSignal?: AbortSignal;
|
|
428
473
|
}
|
|
429
474
|
/** Result of a single list call. */
|
|
430
475
|
interface ListResult {
|
|
@@ -725,6 +770,8 @@ declare class IdempotencyCache {
|
|
|
725
770
|
/** Per-call options that only need to override the target bucket. */
|
|
726
771
|
interface BucketScopedOptions {
|
|
727
772
|
bucket?: string;
|
|
773
|
+
/** Ends the call when it aborts, rejecting `STORAGE_REQUEST_ABORTED`; an aborted signal makes no request. */
|
|
774
|
+
abortSignal?: AbortSignal;
|
|
728
775
|
}
|
|
729
776
|
declare class StorageService {
|
|
730
777
|
private readonly options;
|
|
@@ -763,12 +810,8 @@ declare class StorageService {
|
|
|
763
810
|
private bufferForPreUploadScan;
|
|
764
811
|
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
765
812
|
private runPreUploadScan;
|
|
766
|
-
/**
|
|
767
|
-
|
|
768
|
-
* contract type. In pre-upload mode a stream has already been buffered by
|
|
769
|
-
* {@link bufferForPreUploadScan}, so only `Buffer` and `Uint8Array` arrive here.
|
|
770
|
-
*/
|
|
771
|
-
private normalizeScanBody;
|
|
813
|
+
/** Remembers the result of an upload under its idempotency key, when it has one. */
|
|
814
|
+
private rememberUpload;
|
|
772
815
|
/**
|
|
773
816
|
* Runs a post-upload scan. On infection, deletes the just-uploaded object
|
|
774
817
|
* (logging delete failures as errors) and re-throws the scan exception.
|
|
@@ -815,13 +858,15 @@ declare class StorageService {
|
|
|
815
858
|
metadata: ObjectMetadata;
|
|
816
859
|
}>;
|
|
817
860
|
/**
|
|
818
|
-
*
|
|
819
|
-
*
|
|
861
|
+
* Reads an object fully into memory through the same idle-guarded stream as {@link download}.
|
|
862
|
+
* Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
|
|
820
863
|
*
|
|
821
|
-
* @param options - The download request.
|
|
864
|
+
* @param options - The download request; `maxBytes` is the most bytes to hold.
|
|
822
865
|
* @returns The object buffer and its metadata.
|
|
866
|
+
* @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
|
|
867
|
+
* bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
|
|
823
868
|
*/
|
|
824
|
-
downloadBuffer(options:
|
|
869
|
+
downloadBuffer(options: DownloadBufferOptions): Promise<{
|
|
825
870
|
buffer: Buffer;
|
|
826
871
|
metadata: ObjectMetadata;
|
|
827
872
|
}>;
|
|
@@ -849,15 +894,6 @@ declare class StorageService {
|
|
|
849
894
|
private assertConfigured;
|
|
850
895
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
851
896
|
private resolveBucket;
|
|
852
|
-
/** Builds a public URL, avoiding a duplicated bucket segment in the base. */
|
|
853
|
-
private buildPublicUrl;
|
|
854
|
-
/**
|
|
855
|
-
* Reports whether the base URL already carries the bucket as a real segment —
|
|
856
|
-
* the leading host label (virtual-hosted-style `bucket.host`) or a path segment
|
|
857
|
-
* (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
|
|
858
|
-
* so `bucket="test"` is not matched by a `latest` elsewhere in the base.
|
|
859
|
-
*/
|
|
860
|
-
private baseCarriesBucket;
|
|
861
897
|
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
862
898
|
private toObjectMetadata;
|
|
863
899
|
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
@@ -869,16 +905,13 @@ declare class StorageService {
|
|
|
869
905
|
* aborted. This method aborts the upload itself and reports the outcome in the error details.
|
|
870
906
|
*/
|
|
871
907
|
private uploadMultipart;
|
|
872
|
-
/**
|
|
873
|
-
|
|
874
|
-
|
|
908
|
+
/**
|
|
909
|
+
* Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
|
|
910
|
+
* the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
|
|
911
|
+
* real failure into one. An upload id the provider answered late is waited for, within the cleanup
|
|
912
|
+
* deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
|
|
913
|
+
*/
|
|
875
914
|
private failMultipart;
|
|
876
|
-
/** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
|
|
877
|
-
private normalizeSingleShotBody;
|
|
878
|
-
/** Assembles an `UploadResult`, omitting optional fields that are absent. */
|
|
879
|
-
private buildUploadResult;
|
|
880
|
-
/** Emits a progress event, omitting `total`/`part` when they are unknown. */
|
|
881
|
-
private emitProgress;
|
|
882
915
|
/**
|
|
883
916
|
* Lists objects in the bucket as a single page. Applies the global key prefix
|
|
884
917
|
* to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
|
|
@@ -1389,6 +1422,7 @@ declare const STORAGE_ERROR_CODES: {
|
|
|
1389
1422
|
readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
|
|
1390
1423
|
readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
|
|
1391
1424
|
readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
|
|
1425
|
+
readonly STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED";
|
|
1392
1426
|
};
|
|
1393
1427
|
/** Union of every stable storage error code. */
|
|
1394
1428
|
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
@@ -1411,10 +1445,10 @@ declare class StorageException extends HttpException {
|
|
|
1411
1445
|
readonly code: StorageErrorCode;
|
|
1412
1446
|
constructor(code: StorageErrorCode,
|
|
1413
1447
|
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1414
|
-
statusCode?:
|
|
1448
|
+
statusCode?: number, details?: Record<string, unknown>,
|
|
1415
1449
|
/** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
|
|
1416
1450
|
message?: string);
|
|
1417
1451
|
}
|
|
1418
1452
|
|
|
1419
1453
|
export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BucketLifecycleService, BymaxStorageModule, NoOpFileScanner, NoOpUploadValidator, STORAGE_ERROR_CODES, SignedUrlService, StorageException, StorageService, providerRecipes };
|
|
1420
|
-
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
|
|
1454
|
+
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
|