@bymax-one/nest-storage 1.1.11 → 1.1.13
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 +167 -1
- package/README.md +66 -16
- package/dist/server/index.cjs +686 -207
- package/dist/server/index.d.cts +76 -37
- package/dist/server/index.d.ts +76 -37
- package/dist/server/index.mjs +688 -209
- 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 {
|
|
@@ -457,9 +502,14 @@ interface CopyOptions {
|
|
|
457
502
|
interface DeleteManyOptions {
|
|
458
503
|
bucket?: string;
|
|
459
504
|
}
|
|
460
|
-
/** A single failed key from a batch delete
|
|
505
|
+
/** A single failed key from a batch delete. */
|
|
461
506
|
interface FailedDeletion {
|
|
462
507
|
key: string;
|
|
508
|
+
/**
|
|
509
|
+
* The provider's error code for this key (for example `AccessDenied`), or, when the whole request
|
|
510
|
+
* failed, a fixed reason: `unreachable`, `timeout`, `provider-error`, `credentials-refused` or
|
|
511
|
+
* `rejected`. Never the text of the driver or of the provider.
|
|
512
|
+
*/
|
|
463
513
|
error: string;
|
|
464
514
|
}
|
|
465
515
|
/** Aggregated outcome of a batch delete: succeeded keys and per-key failures. */
|
|
@@ -725,6 +775,8 @@ declare class IdempotencyCache {
|
|
|
725
775
|
/** Per-call options that only need to override the target bucket. */
|
|
726
776
|
interface BucketScopedOptions {
|
|
727
777
|
bucket?: string;
|
|
778
|
+
/** Ends the call when it aborts, rejecting `STORAGE_REQUEST_ABORTED`; an aborted signal makes no request. */
|
|
779
|
+
abortSignal?: AbortSignal;
|
|
728
780
|
}
|
|
729
781
|
declare class StorageService {
|
|
730
782
|
private readonly options;
|
|
@@ -763,12 +815,8 @@ declare class StorageService {
|
|
|
763
815
|
private bufferForPreUploadScan;
|
|
764
816
|
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
765
817
|
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;
|
|
818
|
+
/** Remembers the result of an upload under its idempotency key, when it has one. */
|
|
819
|
+
private rememberUpload;
|
|
772
820
|
/**
|
|
773
821
|
* Runs a post-upload scan. On infection, deletes the just-uploaded object
|
|
774
822
|
* (logging delete failures as errors) and re-throws the scan exception.
|
|
@@ -815,13 +863,15 @@ declare class StorageService {
|
|
|
815
863
|
metadata: ObjectMetadata;
|
|
816
864
|
}>;
|
|
817
865
|
/**
|
|
818
|
-
*
|
|
819
|
-
*
|
|
866
|
+
* Reads an object fully into memory through the same idle-guarded stream as {@link download}.
|
|
867
|
+
* Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
|
|
820
868
|
*
|
|
821
|
-
* @param options - The download request.
|
|
869
|
+
* @param options - The download request; `maxBytes` is the most bytes to hold.
|
|
822
870
|
* @returns The object buffer and its metadata.
|
|
871
|
+
* @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
|
|
872
|
+
* bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
|
|
823
873
|
*/
|
|
824
|
-
downloadBuffer(options:
|
|
874
|
+
downloadBuffer(options: DownloadBufferOptions): Promise<{
|
|
825
875
|
buffer: Buffer;
|
|
826
876
|
metadata: ObjectMetadata;
|
|
827
877
|
}>;
|
|
@@ -849,15 +899,6 @@ declare class StorageService {
|
|
|
849
899
|
private assertConfigured;
|
|
850
900
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
851
901
|
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
902
|
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
862
903
|
private toObjectMetadata;
|
|
863
904
|
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
@@ -869,16 +910,13 @@ declare class StorageService {
|
|
|
869
910
|
* aborted. This method aborts the upload itself and reports the outcome in the error details.
|
|
870
911
|
*/
|
|
871
912
|
private uploadMultipart;
|
|
872
|
-
/**
|
|
873
|
-
|
|
874
|
-
|
|
913
|
+
/**
|
|
914
|
+
* Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
|
|
915
|
+
* the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
|
|
916
|
+
* real failure into one. An upload id the provider answered late is waited for, within the cleanup
|
|
917
|
+
* deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
|
|
918
|
+
*/
|
|
875
919
|
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
920
|
/**
|
|
883
921
|
* Lists objects in the bucket as a single page. Applies the global key prefix
|
|
884
922
|
* to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
|
|
@@ -1389,6 +1427,7 @@ declare const STORAGE_ERROR_CODES: {
|
|
|
1389
1427
|
readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
|
|
1390
1428
|
readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
|
|
1391
1429
|
readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
|
|
1430
|
+
readonly STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED";
|
|
1392
1431
|
};
|
|
1393
1432
|
/** Union of every stable storage error code. */
|
|
1394
1433
|
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
@@ -1411,10 +1450,10 @@ declare class StorageException extends HttpException {
|
|
|
1411
1450
|
readonly code: StorageErrorCode;
|
|
1412
1451
|
constructor(code: StorageErrorCode,
|
|
1413
1452
|
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1414
|
-
statusCode?:
|
|
1453
|
+
statusCode?: number, details?: Record<string, unknown>,
|
|
1415
1454
|
/** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
|
|
1416
1455
|
message?: string);
|
|
1417
1456
|
}
|
|
1418
1457
|
|
|
1419
1458
|
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 };
|
|
1459
|
+
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 {
|
|
@@ -457,9 +502,14 @@ interface CopyOptions {
|
|
|
457
502
|
interface DeleteManyOptions {
|
|
458
503
|
bucket?: string;
|
|
459
504
|
}
|
|
460
|
-
/** A single failed key from a batch delete
|
|
505
|
+
/** A single failed key from a batch delete. */
|
|
461
506
|
interface FailedDeletion {
|
|
462
507
|
key: string;
|
|
508
|
+
/**
|
|
509
|
+
* The provider's error code for this key (for example `AccessDenied`), or, when the whole request
|
|
510
|
+
* failed, a fixed reason: `unreachable`, `timeout`, `provider-error`, `credentials-refused` or
|
|
511
|
+
* `rejected`. Never the text of the driver or of the provider.
|
|
512
|
+
*/
|
|
463
513
|
error: string;
|
|
464
514
|
}
|
|
465
515
|
/** Aggregated outcome of a batch delete: succeeded keys and per-key failures. */
|
|
@@ -725,6 +775,8 @@ declare class IdempotencyCache {
|
|
|
725
775
|
/** Per-call options that only need to override the target bucket. */
|
|
726
776
|
interface BucketScopedOptions {
|
|
727
777
|
bucket?: string;
|
|
778
|
+
/** Ends the call when it aborts, rejecting `STORAGE_REQUEST_ABORTED`; an aborted signal makes no request. */
|
|
779
|
+
abortSignal?: AbortSignal;
|
|
728
780
|
}
|
|
729
781
|
declare class StorageService {
|
|
730
782
|
private readonly options;
|
|
@@ -763,12 +815,8 @@ declare class StorageService {
|
|
|
763
815
|
private bufferForPreUploadScan;
|
|
764
816
|
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
765
817
|
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;
|
|
818
|
+
/** Remembers the result of an upload under its idempotency key, when it has one. */
|
|
819
|
+
private rememberUpload;
|
|
772
820
|
/**
|
|
773
821
|
* Runs a post-upload scan. On infection, deletes the just-uploaded object
|
|
774
822
|
* (logging delete failures as errors) and re-throws the scan exception.
|
|
@@ -815,13 +863,15 @@ declare class StorageService {
|
|
|
815
863
|
metadata: ObjectMetadata;
|
|
816
864
|
}>;
|
|
817
865
|
/**
|
|
818
|
-
*
|
|
819
|
-
*
|
|
866
|
+
* Reads an object fully into memory through the same idle-guarded stream as {@link download}.
|
|
867
|
+
* Without `maxBytes` the whole object is held, however large; use {@link download} for large ones.
|
|
820
868
|
*
|
|
821
|
-
* @param options - The download request.
|
|
869
|
+
* @param options - The download request; `maxBytes` is the most bytes to hold.
|
|
822
870
|
* @returns The object buffer and its metadata.
|
|
871
|
+
* @throws StorageException `STORAGE_SIZE_EXCEEDED` past `maxBytes`, by `Content-Length` or by
|
|
872
|
+
* bytes; `STORAGE_VALIDATION_FAILED` for a `maxBytes` that is not an integer of at least 1.
|
|
823
873
|
*/
|
|
824
|
-
downloadBuffer(options:
|
|
874
|
+
downloadBuffer(options: DownloadBufferOptions): Promise<{
|
|
825
875
|
buffer: Buffer;
|
|
826
876
|
metadata: ObjectMetadata;
|
|
827
877
|
}>;
|
|
@@ -849,15 +899,6 @@ declare class StorageService {
|
|
|
849
899
|
private assertConfigured;
|
|
850
900
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
851
901
|
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
902
|
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
862
903
|
private toObjectMetadata;
|
|
863
904
|
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
@@ -869,16 +910,13 @@ declare class StorageService {
|
|
|
869
910
|
* aborted. This method aborts the upload itself and reports the outcome in the error details.
|
|
870
911
|
*/
|
|
871
912
|
private uploadMultipart;
|
|
872
|
-
/**
|
|
873
|
-
|
|
874
|
-
|
|
913
|
+
/**
|
|
914
|
+
* Aborts the multipart upload that failed, then throws the original failure with the outcome. Whether
|
|
915
|
+
* the failure is an abort is decided first: a signal that fires during the cleanup does not turn a
|
|
916
|
+
* real failure into one. An upload id the provider answered late is waited for, within the cleanup
|
|
917
|
+
* deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
|
|
918
|
+
*/
|
|
875
919
|
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
920
|
/**
|
|
883
921
|
* Lists objects in the bucket as a single page. Applies the global key prefix
|
|
884
922
|
* to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
|
|
@@ -1389,6 +1427,7 @@ declare const STORAGE_ERROR_CODES: {
|
|
|
1389
1427
|
readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
|
|
1390
1428
|
readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
|
|
1391
1429
|
readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
|
|
1430
|
+
readonly STORAGE_REQUEST_ABORTED: "STORAGE_REQUEST_ABORTED";
|
|
1392
1431
|
};
|
|
1393
1432
|
/** Union of every stable storage error code. */
|
|
1394
1433
|
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
@@ -1411,10 +1450,10 @@ declare class StorageException extends HttpException {
|
|
|
1411
1450
|
readonly code: StorageErrorCode;
|
|
1412
1451
|
constructor(code: StorageErrorCode,
|
|
1413
1452
|
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1414
|
-
statusCode?:
|
|
1453
|
+
statusCode?: number, details?: Record<string, unknown>,
|
|
1415
1454
|
/** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
|
|
1416
1455
|
message?: string);
|
|
1417
1456
|
}
|
|
1418
1457
|
|
|
1419
1458
|
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 };
|
|
1459
|
+
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 };
|