@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.
@@ -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: 5 MB). Default: 5 MB. */
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. Default: `1000` (S3 hard max). */
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`, so the scanner
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.
@@ -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: 5 MB). Default: 5 MB. */
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. Default: `1000` (S3 hard max). */
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`, so the scanner
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.