@bymax-one/nest-storage 1.1.16 → 1.1.18
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 +201 -1
- package/README.md +30 -13
- package/dist/server/index.cjs +443 -59
- package/dist/server/index.d.cts +39 -13
- package/dist/server/index.d.ts +39 -13
- package/dist/server/index.mjs +443 -59
- package/package.json +2 -2
package/dist/server/index.d.cts
CHANGED
|
@@ -61,6 +61,11 @@ interface IFileScanner {
|
|
|
61
61
|
bucket: string;
|
|
62
62
|
contentType: string;
|
|
63
63
|
size?: number;
|
|
64
|
+
/**
|
|
65
|
+
* Aborts when `scanner.timeoutMs` passes. A scanner that ignores it keeps running after the
|
|
66
|
+
* upload is refused, so repeated timeouts pile up scanner work.
|
|
67
|
+
*/
|
|
68
|
+
signal?: AbortSignal;
|
|
64
69
|
}): Promise<FileScanResult>;
|
|
65
70
|
}
|
|
66
71
|
/** Outcome of a file scan. */
|
|
@@ -120,20 +125,22 @@ interface BymaxStorageModuleOptions {
|
|
|
120
125
|
defaultCacheControl?: string;
|
|
121
126
|
/** Default `Content-Disposition`. */
|
|
122
127
|
defaultContentDisposition?: 'inline' | 'attachment';
|
|
128
|
+
/** Signed-URL options. A key set to `undefined` or `null` means its default. */
|
|
123
129
|
signedUrls?: {
|
|
124
|
-
/** Default GET TTL (seconds). Default: `300`. */
|
|
130
|
+
/** Default GET TTL (seconds): a whole number of at least 1. Default: `300`. */
|
|
125
131
|
defaultGetTtlSeconds?: number;
|
|
126
|
-
/** Default PUT TTL (seconds). Default: `300`. */
|
|
132
|
+
/** Default PUT TTL (seconds): a whole number of at least 1. Default: `300`. */
|
|
127
133
|
defaultPutTtlSeconds?: number;
|
|
128
|
-
/** Hard cap — higher TTLs are silently clamped. Default: `604800` (7 days). */
|
|
134
|
+
/** Hard cap, a whole number of at least 1 — higher TTLs are silently clamped. Default: `604800` (7 days). */
|
|
129
135
|
maxTtlSeconds?: number;
|
|
130
136
|
};
|
|
137
|
+
/** Multipart options. A key set to `undefined` or `null` means its default. */
|
|
131
138
|
multipart?: {
|
|
132
|
-
/** Bytes threshold to switch to multipart. Default: `5242880` (5 MB). */
|
|
139
|
+
/** Bytes threshold to switch to multipart, a whole number of at least 1. Default: `5242880` (5 MB). */
|
|
133
140
|
thresholdBytes?: number;
|
|
134
|
-
/** Size per part (S3 minimum
|
|
141
|
+
/** Size per part, a whole number from 5 MB (S3 minimum) to 5 GB (S3 maximum). Default: 5 MB. */
|
|
135
142
|
partSizeBytes?: number;
|
|
136
|
-
/** Concurrent parts. Default: `4`. */
|
|
143
|
+
/** Concurrent parts, a whole number from 1 to 1000. Default: `4`. */
|
|
137
144
|
queueSize?: number;
|
|
138
145
|
};
|
|
139
146
|
/** Enables the validation pipeline when present. */
|
|
@@ -141,7 +148,7 @@ interface BymaxStorageModuleOptions {
|
|
|
141
148
|
/** MIME whitelist — supports wildcards like `'image/*'`. */
|
|
142
149
|
mimeWhitelist?: readonly string[];
|
|
143
150
|
/**
|
|
144
|
-
* Max upload size in bytes. A buffer is checked by its length and a stream is counted as it
|
|
151
|
+
* Max upload size in bytes, a whole number of at least 1. A buffer is checked by its length and a stream is counted as it
|
|
145
152
|
* is read, so the limit holds whether or not the caller declares `size`.
|
|
146
153
|
*/
|
|
147
154
|
maxSizeBytes?: number;
|
|
@@ -155,6 +162,11 @@ interface BymaxStorageModuleOptions {
|
|
|
155
162
|
mode?: 'pre-upload' | 'post-upload';
|
|
156
163
|
/** Reject when the scanner returns `'unknown'`. Default: `false`. */
|
|
157
164
|
rejectOnUnknown?: boolean;
|
|
165
|
+
/**
|
|
166
|
+
* Longest a scan may run, in milliseconds, an integer from `1` to `2147483647`; past it the upload
|
|
167
|
+
* is refused with `STORAGE_TIMEOUT`. There is no setting that waits without limit. Default: `60000`.
|
|
168
|
+
*/
|
|
169
|
+
timeoutMs?: number;
|
|
158
170
|
};
|
|
159
171
|
/** Server-side encryption. */
|
|
160
172
|
serverSideEncryption?: 'AES256' | 'aws:kms';
|
|
@@ -331,7 +343,7 @@ interface UploadOptions {
|
|
|
331
343
|
body: Buffer | NodeJS.ReadableStream | Uint8Array;
|
|
332
344
|
contentType: string;
|
|
333
345
|
bucket?: string;
|
|
334
|
-
/** Required for validation and optimal multipart sizing. */
|
|
346
|
+
/** Required for validation and optimal multipart sizing: a whole number of bytes, `0` or more. */
|
|
335
347
|
size?: number;
|
|
336
348
|
cacheControl?: string;
|
|
337
349
|
/** `'inline'`, `'attachment'`, or a full `Content-Disposition` value. */
|
|
@@ -457,7 +469,7 @@ interface ListOptions {
|
|
|
457
469
|
/** Filter prefix (applied AFTER the global key prefix). */
|
|
458
470
|
prefix?: string;
|
|
459
471
|
bucket?: string;
|
|
460
|
-
/** Page size
|
|
472
|
+
/** Page size, a whole number of at least 1; above `1000` (the S3 hard max) it is lowered to it. Default: `1000`. */
|
|
461
473
|
maxKeys?: number;
|
|
462
474
|
/** Token from a previous page. */
|
|
463
475
|
continuationToken?: string;
|
|
@@ -691,15 +703,29 @@ declare class FileScannerService {
|
|
|
691
703
|
*
|
|
692
704
|
* Infected results throw `STORAGE_SCAN_INFECTED`. Inconclusive results throw
|
|
693
705
|
* `STORAGE_SCAN_INCONCLUSIVE` when `rejectOnUnknown` is set; otherwise they
|
|
694
|
-
* are returned with a warning log.
|
|
706
|
+
* are returned with a warning log. Anything else (no result, a status that is not exactly
|
|
707
|
+
* `'clean'`, `'infected'` or `'unknown'`) is rejected as inconclusive whatever `rejectOnUnknown`
|
|
708
|
+
* says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
|
|
695
709
|
*
|
|
696
710
|
* @param input - The scan input.
|
|
697
711
|
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
698
712
|
* @throws Error when called without a configured scanner.
|
|
699
713
|
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
700
|
-
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown
|
|
714
|
+
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
|
|
715
|
+
* @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
|
|
701
716
|
*/
|
|
702
717
|
scan(input: ScanInput): Promise<FileScanResult>;
|
|
718
|
+
/**
|
|
719
|
+
* Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
|
|
720
|
+
* line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
|
|
721
|
+
*/
|
|
722
|
+
private scanLogged;
|
|
723
|
+
/**
|
|
724
|
+
* Runs the scanner and gives up after `scanner.timeoutMs`: a scanner that never settles would hold
|
|
725
|
+
* the upload for good. The scanner is handed a signal that aborts then; one that ignores it keeps
|
|
726
|
+
* running.
|
|
727
|
+
*/
|
|
728
|
+
private scanWithinDeadline;
|
|
703
729
|
}
|
|
704
730
|
|
|
705
731
|
/**
|
|
@@ -814,8 +840,8 @@ declare class StorageService {
|
|
|
814
840
|
*/
|
|
815
841
|
private validateAndScan;
|
|
816
842
|
/**
|
|
817
|
-
* In pre-upload scan mode a stream body is read into one `Buffer`,
|
|
818
|
-
* and the upload see the same bytes; a stream is single-use, and one the scanner
|
|
843
|
+
* In pre-upload scan mode a stream body is read into one `Buffer`, and a buffer body is copied, so
|
|
844
|
+
* the scanner and the upload see the same bytes; a stream is single-use, and one the scanner
|
|
819
845
|
* had consumed would leave the upload with nothing to send. The read is bounded by
|
|
820
846
|
* `validation.maxSizeBytes`, and a stream with no bound is refused rather than
|
|
821
847
|
* buffered without limit. Other bodies and modes pass through unchanged.
|
package/dist/server/index.d.ts
CHANGED
|
@@ -61,6 +61,11 @@ interface IFileScanner {
|
|
|
61
61
|
bucket: string;
|
|
62
62
|
contentType: string;
|
|
63
63
|
size?: number;
|
|
64
|
+
/**
|
|
65
|
+
* Aborts when `scanner.timeoutMs` passes. A scanner that ignores it keeps running after the
|
|
66
|
+
* upload is refused, so repeated timeouts pile up scanner work.
|
|
67
|
+
*/
|
|
68
|
+
signal?: AbortSignal;
|
|
64
69
|
}): Promise<FileScanResult>;
|
|
65
70
|
}
|
|
66
71
|
/** Outcome of a file scan. */
|
|
@@ -120,20 +125,22 @@ interface BymaxStorageModuleOptions {
|
|
|
120
125
|
defaultCacheControl?: string;
|
|
121
126
|
/** Default `Content-Disposition`. */
|
|
122
127
|
defaultContentDisposition?: 'inline' | 'attachment';
|
|
128
|
+
/** Signed-URL options. A key set to `undefined` or `null` means its default. */
|
|
123
129
|
signedUrls?: {
|
|
124
|
-
/** Default GET TTL (seconds). Default: `300`. */
|
|
130
|
+
/** Default GET TTL (seconds): a whole number of at least 1. Default: `300`. */
|
|
125
131
|
defaultGetTtlSeconds?: number;
|
|
126
|
-
/** Default PUT TTL (seconds). Default: `300`. */
|
|
132
|
+
/** Default PUT TTL (seconds): a whole number of at least 1. Default: `300`. */
|
|
127
133
|
defaultPutTtlSeconds?: number;
|
|
128
|
-
/** Hard cap — higher TTLs are silently clamped. Default: `604800` (7 days). */
|
|
134
|
+
/** Hard cap, a whole number of at least 1 — higher TTLs are silently clamped. Default: `604800` (7 days). */
|
|
129
135
|
maxTtlSeconds?: number;
|
|
130
136
|
};
|
|
137
|
+
/** Multipart options. A key set to `undefined` or `null` means its default. */
|
|
131
138
|
multipart?: {
|
|
132
|
-
/** Bytes threshold to switch to multipart. Default: `5242880` (5 MB). */
|
|
139
|
+
/** Bytes threshold to switch to multipart, a whole number of at least 1. Default: `5242880` (5 MB). */
|
|
133
140
|
thresholdBytes?: number;
|
|
134
|
-
/** Size per part (S3 minimum
|
|
141
|
+
/** Size per part, a whole number from 5 MB (S3 minimum) to 5 GB (S3 maximum). Default: 5 MB. */
|
|
135
142
|
partSizeBytes?: number;
|
|
136
|
-
/** Concurrent parts. Default: `4`. */
|
|
143
|
+
/** Concurrent parts, a whole number from 1 to 1000. Default: `4`. */
|
|
137
144
|
queueSize?: number;
|
|
138
145
|
};
|
|
139
146
|
/** Enables the validation pipeline when present. */
|
|
@@ -141,7 +148,7 @@ interface BymaxStorageModuleOptions {
|
|
|
141
148
|
/** MIME whitelist — supports wildcards like `'image/*'`. */
|
|
142
149
|
mimeWhitelist?: readonly string[];
|
|
143
150
|
/**
|
|
144
|
-
* Max upload size in bytes. A buffer is checked by its length and a stream is counted as it
|
|
151
|
+
* Max upload size in bytes, a whole number of at least 1. A buffer is checked by its length and a stream is counted as it
|
|
145
152
|
* is read, so the limit holds whether or not the caller declares `size`.
|
|
146
153
|
*/
|
|
147
154
|
maxSizeBytes?: number;
|
|
@@ -155,6 +162,11 @@ interface BymaxStorageModuleOptions {
|
|
|
155
162
|
mode?: 'pre-upload' | 'post-upload';
|
|
156
163
|
/** Reject when the scanner returns `'unknown'`. Default: `false`. */
|
|
157
164
|
rejectOnUnknown?: boolean;
|
|
165
|
+
/**
|
|
166
|
+
* Longest a scan may run, in milliseconds, an integer from `1` to `2147483647`; past it the upload
|
|
167
|
+
* is refused with `STORAGE_TIMEOUT`. There is no setting that waits without limit. Default: `60000`.
|
|
168
|
+
*/
|
|
169
|
+
timeoutMs?: number;
|
|
158
170
|
};
|
|
159
171
|
/** Server-side encryption. */
|
|
160
172
|
serverSideEncryption?: 'AES256' | 'aws:kms';
|
|
@@ -331,7 +343,7 @@ interface UploadOptions {
|
|
|
331
343
|
body: Buffer | NodeJS.ReadableStream | Uint8Array;
|
|
332
344
|
contentType: string;
|
|
333
345
|
bucket?: string;
|
|
334
|
-
/** Required for validation and optimal multipart sizing. */
|
|
346
|
+
/** Required for validation and optimal multipart sizing: a whole number of bytes, `0` or more. */
|
|
335
347
|
size?: number;
|
|
336
348
|
cacheControl?: string;
|
|
337
349
|
/** `'inline'`, `'attachment'`, or a full `Content-Disposition` value. */
|
|
@@ -457,7 +469,7 @@ interface ListOptions {
|
|
|
457
469
|
/** Filter prefix (applied AFTER the global key prefix). */
|
|
458
470
|
prefix?: string;
|
|
459
471
|
bucket?: string;
|
|
460
|
-
/** Page size
|
|
472
|
+
/** Page size, a whole number of at least 1; above `1000` (the S3 hard max) it is lowered to it. Default: `1000`. */
|
|
461
473
|
maxKeys?: number;
|
|
462
474
|
/** Token from a previous page. */
|
|
463
475
|
continuationToken?: string;
|
|
@@ -691,15 +703,29 @@ declare class FileScannerService {
|
|
|
691
703
|
*
|
|
692
704
|
* Infected results throw `STORAGE_SCAN_INFECTED`. Inconclusive results throw
|
|
693
705
|
* `STORAGE_SCAN_INCONCLUSIVE` when `rejectOnUnknown` is set; otherwise they
|
|
694
|
-
* are returned with a warning log.
|
|
706
|
+
* are returned with a warning log. Anything else (no result, a status that is not exactly
|
|
707
|
+
* `'clean'`, `'infected'` or `'unknown'`) is rejected as inconclusive whatever `rejectOnUnknown`
|
|
708
|
+
* says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
|
|
695
709
|
*
|
|
696
710
|
* @param input - The scan input.
|
|
697
711
|
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
698
712
|
* @throws Error when called without a configured scanner.
|
|
699
713
|
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
700
|
-
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown
|
|
714
|
+
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
|
|
715
|
+
* @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
|
|
701
716
|
*/
|
|
702
717
|
scan(input: ScanInput): Promise<FileScanResult>;
|
|
718
|
+
/**
|
|
719
|
+
* Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
|
|
720
|
+
* line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
|
|
721
|
+
*/
|
|
722
|
+
private scanLogged;
|
|
723
|
+
/**
|
|
724
|
+
* Runs the scanner and gives up after `scanner.timeoutMs`: a scanner that never settles would hold
|
|
725
|
+
* the upload for good. The scanner is handed a signal that aborts then; one that ignores it keeps
|
|
726
|
+
* running.
|
|
727
|
+
*/
|
|
728
|
+
private scanWithinDeadline;
|
|
703
729
|
}
|
|
704
730
|
|
|
705
731
|
/**
|
|
@@ -814,8 +840,8 @@ declare class StorageService {
|
|
|
814
840
|
*/
|
|
815
841
|
private validateAndScan;
|
|
816
842
|
/**
|
|
817
|
-
* In pre-upload scan mode a stream body is read into one `Buffer`,
|
|
818
|
-
* and the upload see the same bytes; a stream is single-use, and one the scanner
|
|
843
|
+
* In pre-upload scan mode a stream body is read into one `Buffer`, and a buffer body is copied, so
|
|
844
|
+
* the scanner and the upload see the same bytes; a stream is single-use, and one the scanner
|
|
819
845
|
* had consumed would leave the upload with nothing to send. The read is bounded by
|
|
820
846
|
* `validation.maxSizeBytes`, and a stream with no bound is refused rather than
|
|
821
847
|
* buffered without limit. Other bodies and modes pass through unchanged.
|