@bymax-one/nest-storage 1.1.11 → 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 CHANGED
@@ -13,6 +13,147 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.12] - 2026-11-14
17
+
18
+ ### Added
19
+
20
+ - **`abortSignal` ends a call.** `upload`, `download`, `downloadBuffer`, `list`, `head`, `exists`,
21
+ `delete` and `checkBucket` take an optional `abortSignal`. When it aborts the call rejects the new
22
+ `STORAGE_REQUEST_ABORTED` (HTTP 499), with `details.reason` set to the name of the signal's
23
+ reason, never its message; a signal that is already aborted makes no request. A multipart upload
24
+ is aborted on the provider, with a deadline of its own and not the caller's signal
25
+ (`details.abort` reports the outcome); a download body being read errors as the same
26
+ code while the idle guard is on, and as the raw `AbortError` with `bodyIdleTimeoutMs: 0`. The
27
+ library adds no listener to the signal that outlives the call, so one signal can be reused.
28
+ `exists` rejects an aborted call instead of answering `false`. An abort during a post-upload scan
29
+ ends the call with `details.stored: true` (the object is stored; the scan carries on and still
30
+ deletes an infected one).
31
+
32
+ **Apply to a derived backend:** nothing changes unless you pass a signal. The new code is part of
33
+ the shared `STORAGE_ERROR_CODES` table: a host that maps every code exhaustively needs a case for
34
+ it, and an HTTP layer should not answer 5xx for it, since the caller ended the call.
35
+
36
+ - **`downloadBuffer({ maxBytes })` bounds what a buffered download holds.** `downloadBuffer` read the
37
+ whole object into memory whatever its size, so one large or hostile object could exhaust the
38
+ process. With `maxBytes`, an object whose `Content-Length` is larger is refused before its body is
39
+ read, and a body that is longer than it said, or has no length, is cut off as it is counted; both
40
+ reject `STORAGE_SIZE_EXCEEDED` (`details.maxSize`, and `details.contentLength` for the first) and
41
+ release the connection. A value that is not an integer of at least `1` rejects
42
+ `STORAGE_VALIDATION_FAILED` before any request. There is no default: without `maxBytes` the call
43
+ behaves as before. The new `DownloadBufferOptions` type is exported.
44
+
45
+ **Apply to a derived backend:** nothing changes until you pass `maxBytes`. Set it wherever a
46
+ backend calls `downloadBuffer` on an object it does not control, to what the process can hold.
47
+
48
+ - **`bodyIdleTimeoutMs` bounds a download body that stops delivering.** `requestTimeoutMs` ends when
49
+ the response headers arrive, so a provider that stalled mid-body left the stream, its connection
50
+ and the caller waiting for as long as the provider chose. After `bodyIdleTimeoutMs` of silence
51
+ while the caller is reading, `download` and `downloadBuffer` now fail with `STORAGE_TIMEOUT`
52
+ (`details.phase: 'body-idle'`) and the connection is released. The clock runs only while a read
53
+ is pending, so a slow consumer never trips it. It defaults to `requestTimeoutMs`; `0` turns it off.
54
+
55
+ **Apply to a derived backend:** a download that went quiet for longer than `requestTimeoutMs`
56
+ (30 s by default) used to wait on; it now fails `STORAGE_TIMEOUT`. If you serve very large
57
+ objects through a source that can pause that long, raise `bodyIdleTimeoutMs` or set it to `0`;
58
+ while the guard is on the stream returned by `download` is a wrapper, so code that read SDK-only
59
+ members from it (such as `transformToByteArray`) must read it as a stream instead.
60
+
61
+ ### Changed
62
+
63
+ - **An unavailable provider answers 503, not 502, 504 or 500.** `STORAGE_TIMEOUT` was HTTP 504 and is
64
+ now **503**. `STORAGE_PROVIDER_ERROR` keeps its code and stays 502 for a request the provider
65
+ rejected, but is **503** when the provider could not be reached (connection refused or reset, DNS
66
+ failure) or answered with a server error (`SlowDown`, 500, 502, 504; not 501), and **500** when it
67
+ refused the credentials (`InvalidAccessKeyId`, `SignatureDoesNotMatch`: a deployment fault a retry
68
+ does not fix; the `HEAD` calls carry no error body, so for them the credentials case is not told
69
+ apart). `STORAGE_MULTIPART_ABORTED` is **503** when the cause is an outage and stays 500 otherwise.
70
+ A client then has one status, 503, to treat as "retry later" whichever library answered.
71
+
72
+ **Apply to a derived backend:** the codes are unchanged; only the HTTP status of the cases above
73
+ moves. A host that matches `504` or `502` to retry must match `503`, and one that maps
74
+ `STORAGE_PROVIDER_ERROR` to a fixed status by code must read `error.getStatus()` instead.
75
+
76
+ - **Development and CI tooling updated; the published code does not change by it.** The release
77
+ workflow follows the organisation's template: the build job installs, runs the gates and packs the
78
+ tarball once without a credential, and the publish job, which holds the token and runs no code
79
+ from the package, publishes only that tarball after checking its digest. `glob` and `minimatch`
80
+ are raised above their advisory floors, so their OSV ignores are gone, the timing assertions of
81
+ the test suite no longer depend on how loaded the machine is, and the pull request check now
82
+ compiles the README snippets against the built package, as the release already did.
83
+
84
+ **Apply to a derived backend:** nothing to change.
85
+
86
+ ### Fixed
87
+
88
+ - **`requestTimeoutMs`, `uploadIdleTimeoutMs` and `bodyIdleTimeoutMs` are refused above 2147483647.**
89
+ Each feeds a timer, and Node clamps a timer above 2**31 - 1 milliseconds to 1 ms, so a larger value
90
+ made every request or read fail at once instead of waiting longer. `validateOptions` now throws
91
+ `STORAGE_INVALID_CONFIG` naming the option for a value above the ceiling (about 24.8 days); the
92
+ ceiling itself is accepted.
93
+
94
+ **Apply to a derived backend:** if you set one of these three above `2147483647` (to mean "very
95
+ long"), lower it, or for the two idle guards use `0` to turn the guard off; the module now refuses
96
+ to start with such a value.
97
+
98
+ - **`publicBaseUrl` and `cdnBaseUrl` are refused when they carry credentials.** Either is returned to
99
+ callers as the base of every `publicUrl`, so a user or password in either, including one given
100
+ through a provider recipe's `customDomain`, reached clients and anything that stores or logs those
101
+ URLs. `validateOptions` now throws `STORAGE_INVALID_CONFIG` naming the option and repeating neither
102
+ the user nor the password, from `forRoot` and `forRootAsync` alike. The same check now applies to
103
+ `endpoint`, `publicBaseUrl` and `cdnBaseUrl`: an `@` in the host part (the text after an optional
104
+ scheme and slashes, up to the first `/`, `?` or `#`) is refused, with or without a password.
105
+
106
+ **Apply to a derived backend:** if one of these URLs embeds `user@` or `user:password@`, remove it before upgrading;
107
+ the module now refuses to start with such a value.
108
+
109
+ - **A key or a provider message in a log line is written as one escaped token.** The scanner warnings
110
+ (`Infected file detected`, `Inconclusive scan result accepted`), the idempotent-delete warning, the
111
+ `exists` warning and the `STORAGE_SCAN_CLEANUP_FAILED` error repeated the object key, the scanner's
112
+ engine and threat names, or the provider's message as they were. S3 accepts a key with a newline, a
113
+ carriage return or an escape sequence, so such a key could end its log line and forge the next, or
114
+ colour or hide what followed. Each of those values is now a quoted token in which control
115
+ characters, and the invisible or bidirectional characters JSON leaves literal, show as `\n`, `\r`,
116
+ `\uNNNN` or `\u{...}`.
117
+
118
+ **Apply to a derived backend:** nothing changes in behaviour or in an error response. If a log
119
+ parser matches `key=<value>` in these lines, the value is now enclosed in double quotes.
120
+
121
+ - **An endpoint that carries credentials is refused, and the boot log no longer prints the endpoint
122
+ whole.** The `S3Client initialized` line repeated `endpoint` as configured, so an endpoint such as
123
+ `https://KEY:SECRET@host` wrote the secret to the log, and the same string is the base of every
124
+ `publicUrl` the library returns when no `publicBaseUrl` is set. `validateOptions` now throws
125
+ `STORAGE_INVALID_CONFIG` for an endpoint with a user or password, without repeating it, and the log
126
+ line shows only protocol, host and port.
127
+
128
+ **Apply to a derived backend:** if your `endpoint` embeds `user:password@`, move the keys to
129
+ `credentials` before upgrading; the module now refuses to start with such a value.
130
+
131
+ - **`requestTimeoutMs` and `maxAttempts` are now checked at boot.** A value of `0`, a negative or
132
+ fractional number, `NaN` or `Infinity`, or a non-number reached the S3 client unchecked, and the
133
+ request handler treats a `0` or `NaN` timeout as no timeout, so a typo could switch the bound off
134
+ without a sign. Both options must now be integers of at least `1`; anything else throws
135
+ `STORAGE_INVALID_CONFIG` naming the option.
136
+
137
+ **Apply to a derived backend:** if your configuration passes `0` for either option, or computes
138
+ one that can be fractional, change it to a positive integer before upgrading; a module that booted
139
+ with such a value now refuses to start.
140
+
141
+ - **`validation.maxSizeBytes` now bounds every upload body, not only a declared `size`.** The limit
142
+ was compared with the `size` option alone, so a stream with no `size`, a stream longer than the
143
+ `size` it declared, and a `Buffer` or `Uint8Array` with no `size` were all stored whatever their
144
+ length. A multipart upload is now counted as it is read: past the limit (or past the declared
145
+ `size`, if that is lower) the multipart upload is aborted, the source is destroyed, and `upload()` rejects `STORAGE_SIZE_EXCEEDED` with `details.maxSize` or
146
+ `details.declaredSize` and the abort outcome. A buffer is checked by its own length. A string or
147
+ `ArrayBuffer` body, which the types forbid but untyped callers can pass, is now sent as its bytes
148
+ (a string as UTF-8) and measured in bytes. A single-shot stream is still sent as `size` bytes, as
149
+ before.
150
+
151
+ **Apply to a derived backend:** if you set `validation.maxSizeBytes`, an upload that used to pass
152
+ because it carried no `size` is now refused when it is longer than the limit; expect
153
+ `STORAGE_SIZE_EXCEEDED` from a stream or buffer over it, and pass `size` only when it is true. A
154
+ buffer's declared `size` is ignored in favour of its length, so a small buffer declared as large
155
+ is no longer refused or sent as multipart.
156
+
16
157
  ## [1.1.11] - 2026-11-13
17
158
 
18
159
  ### Changed
@@ -684,4 +825,5 @@ have regressed from. They are kept because the reasoning is worth having.
684
825
  [1.1.9]: https://github.com/bymaxone/nest-storage/compare/v1.1.8...v1.1.9
685
826
  [1.1.10]: https://github.com/bymaxone/nest-storage/compare/v1.1.9...v1.1.10
686
827
  [1.1.11]: https://github.com/bymaxone/nest-storage/compare/v1.1.10...v1.1.11
687
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.11...HEAD
828
+ [1.1.12]: https://github.com/bymaxone/nest-storage/compare/v1.1.11...v1.1.12
829
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.12...HEAD
package/README.md CHANGED
@@ -208,23 +208,24 @@ Options accepted by `forRoot` and `forRootAsync`:
208
208
 
209
209
  | Option | Type | Default | Notes |
210
210
  | ------------------------------ | ------------------------------------------------- | ----------------- | ---------------------------------------------- |
211
- | `endpoint` | `string` | — | Required. S3-compatible endpoint URL |
211
+ | `endpoint` | `string` | — | Required. S3-compatible endpoint URL; it must not carry credentials (`https://user:pass@host` is refused), pass them in `credentials` |
212
212
  | `region` | `string` | — | Required. Provider region or `'auto'` (R2) |
213
213
  | `bucket` | `string` | — | Default bucket (can be overridden per-call) |
214
214
  | `credentials` | `{ accessKeyId, secretAccessKey, sessionToken? }` | — | Load from env / Secrets Manager |
215
215
  | `forcePathStyle` | `boolean` | `false` | Set to `true` for MinIO and self-hosted |
216
- | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results |
217
- | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`) |
216
+ | `publicBaseUrl` | `string` | — | Base URL for public `getPublicUrl()` results; it must not carry credentials (a user or password is refused) |
217
+ | `cdnBaseUrl` | `string` | — | CDN edge URL (preferred over `publicBaseUrl`); it must not carry credentials either |
218
218
  | `keyPrefix` | `string` | — | Prepended to every key before it reaches the provider; fixed per module instance |
219
- | `maxAttempts` | `number` | `3` | SDK v3 retry count |
219
+ | `maxAttempts` | `number` | `3` | SDK v3 retry count; an integer of at least `1` |
220
220
  | `serverSideEncryption` | `'AES256' \| 'aws:kms'` | — | Global SSE policy; `aws:kms` needs `kmsKeyId`. `'NONE'` is accepted per upload only |
221
221
  | `requestChecksumCalculation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
222
222
  | `responseChecksumValidation` | `'WHEN_SUPPORTED' \| 'WHEN_REQUIRED'` | SDK default | Set to `'WHEN_REQUIRED'` for non-AWS providers |
223
223
  | `defaultPublicRead` | `boolean` | `false` | ACL `public-read` on uploads; see Public Access / ACLs |
224
224
  | `defaultCacheControl` | `string` | `public, max-age=31536000, immutable` | Default `Cache-Control` on uploads |
225
225
  | `defaultContentDisposition` | `'inline' \| 'attachment'` | `inline` | Default `Content-Disposition` on uploads |
226
- | `requestTimeoutMs` | `number` | `30000` | Per attempt, until the response headers arrive; see below the table |
227
- | `uploadIdleTimeoutMs` | `number` | `30000` | Longest silence from a stream body during a multipart upload; follows `requestTimeoutMs` unless set, `0` disables; see below the table |
226
+ | `requestTimeoutMs` | `number` | `30000` | Per attempt, until the response headers arrive; an integer from `1` to `2147483647`; see below the table |
227
+ | `uploadIdleTimeoutMs` | `number` | `30000` | Longest silence from a stream body during a multipart upload; follows `requestTimeoutMs` unless set, `0` disables, at most `2147483647`; see below the table |
228
+ | `bodyIdleTimeoutMs` | `number` | `30000` | Longest silence from a download body while the caller is reading it; follows `requestTimeoutMs` unless set, `0` disables, at most `2147483647`; see below the table |
228
229
  | `signedUrls.defaultGetTtlSeconds` | `number` | `300` | Default TTL for `getDownloadUrl` |
229
230
  | `signedUrls.defaultPutTtlSeconds` | `number` | `300` | Default TTL for `getUploadUrl` |
230
231
  | `signedUrls.maxTtlSeconds` | `number` | `604800` | Per-request TTLs above this are clamped; a larger value is reduced to 604800 (the 7-day SigV4 limit) at init |
@@ -232,14 +233,16 @@ Options accepted by `forRoot` and `forRootAsync`:
232
233
  | `multipart.partSizeBytes` | `number` | `5 MiB` | Part size (S3 minimum: 5 MiB) |
233
234
  | `multipart.queueSize` | `number` | `4` | Concurrent parts |
234
235
  | `validation.mimeWhitelist` | `string[]` | — | No MIME check when absent. Wildcards: `'image/*'`. A value that lists several types never matches |
235
- | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes |
236
+ | `validation.maxSizeBytes` | `number` | — | Maximum upload size in bytes; counted as a stream is read, so it holds with or without `size` |
236
237
 
237
238
  > **Do not use `maxRetries` or `signatureVersion`** — these are AWS SDK v2 options that do not exist in v3. The v3 SDK is SigV4-only. Use `maxAttempts` (default `3`) for retry configuration.
238
239
 
239
- **`requestTimeoutMs`** is passed to the S3 client's request handler as `requestTimeout` with `throwOnRequestTimeout` ([AWS SDK for JavaScript v3: `requestHandler: { requestTimeout: 3_000, ... }`][sdk-request-timeout]). It bounds one attempt, from sending the request until the response headers arrive, and an upload body counts toward it, so a large single-shot upload on a slow link needs a larger value. It does not limit reading a download stream. With `maxAttempts` above 1 a stalled request is retried, so the total wait is the timeout times the attempts.
240
+ **`requestTimeoutMs`** is passed to the S3 client's request handler as `requestTimeout` with `throwOnRequestTimeout` ([AWS SDK for JavaScript v3: `requestHandler: { requestTimeout: 3_000, ... }`][sdk-request-timeout]). It bounds one attempt, from sending the request until the response headers arrive, and an upload body counts toward it, so a large single-shot upload on a slow link needs a larger value. It does not limit reading a download stream; `bodyIdleTimeoutMs` does. With `maxAttempts` above 1 a stalled request is retried, so the total wait is the timeout times the attempts.
240
241
 
241
242
  **`uploadIdleTimeoutMs`** covers what `requestTimeoutMs` cannot: a multipart upload waiting for the next bytes of a stream has no request in flight, so a source that stops delivering would hold the upload open on the provider indefinitely. After this much silence the upload is aborted (the provider is sent `AbortMultipartUpload`), your stream is destroyed and `upload()` rejects with `STORAGE_TIMEOUT` and `details.phase` set to `'source-idle'`. The clock restarts on every chunk and runs only while the library is waiting for data, so a slow but live source succeeds and a slow provider does not trip it. It defaults to the value of `requestTimeoutMs`; `0` turns it off. It applies only to a stream on the multipart path: a single-shot upload is bounded by `requestTimeoutMs`, and a `Buffer` cannot stall.
242
243
 
244
+ **`bodyIdleTimeoutMs`** covers the other direction: `requestTimeoutMs` ends when the response headers arrive, so a provider that stops sending in the middle of a download would leave the stream, its connection and the caller waiting without limit. After this much silence while a read is pending, the stream fails with `STORAGE_TIMEOUT` and `details.phase` set to `'body-idle'`, and the connection is released. The clock runs only while the caller is waiting for data, so a consumer that is slow to read, for example a response piped to a slow client, never trips it, and every chunk restarts it. It defaults to the value of `requestTimeoutMs`; `0` turns it off. It applies to `download` and `downloadBuffer`.
245
+
243
246
 
244
247
  [aws-presigned-expiry]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
245
248
  [aws-get-object]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html
@@ -383,10 +386,18 @@ async download(@Param('key') key: string, @Res() res: Response) {
383
386
  ### As a Buffer
384
387
 
385
388
  ```typescript
386
- // Use only for files < 10 MB — loads the entire object into memory.
387
- const { buffer, metadata } = await this.storage.downloadBuffer({ key: 'docs/report.pdf' })
389
+ // Always pass `maxBytes`: without it the whole object is held in memory, however large it is.
390
+ const { buffer, metadata } = await this.storage.downloadBuffer({
391
+ key: 'docs/report.pdf',
392
+ maxBytes: 10 * 1024 * 1024,
393
+ })
388
394
  ```
389
395
 
396
+ `maxBytes` is an integer of at least `1`. An object whose `Content-Length` is larger is refused before its
397
+ body is read, and a body that turns out longer (a missing or wrong `Content-Length`) is cut off as it is
398
+ counted; both reject `STORAGE_SIZE_EXCEEDED` with `details.maxSize` and release the connection. The limit
399
+ is per call and has no default, so a backend that buffers should set it from what it can hold.
400
+
390
401
  ### Conditional and ranged reads
391
402
 
392
403
  `download` and `downloadBuffer` accept `range`, `ifNoneMatch` and `ifMatch`. S3 answers a matching
@@ -401,6 +412,44 @@ and a failing `If-Match` with 412, and the library turns them into typed errors:
401
412
  A 304 is therefore thrown, not returned: catch `StorageException` and branch on `code`. A `range`
402
413
  (`'bytes=0-99'`) returns the requested bytes, and the metadata describes the whole object.
403
414
 
415
+ ### Cancelling a call (`abortSignal`)
416
+
417
+ `upload`, `download`, `downloadBuffer`, `list`, `head`, `exists`, `delete` and `checkBucket` accept an
418
+ `abortSignal`. When it aborts, the call rejects `STORAGE_REQUEST_ABORTED` (HTTP 499) with
419
+ `details.reason` set to the **name** of the signal's reason (`AbortError`, `TimeoutError`), never its
420
+ message, so a host can tell its own timeout from a client disconnect. `exists` rejects too, rather
421
+ than answering `false`.
422
+
423
+ ```typescript
424
+ const controller = new AbortController()
425
+ req.on('close', () => controller.abort())
426
+ await this.storage.upload({
427
+ key: `${folder}/report.pdf`,
428
+ body: buf,
429
+ contentType,
430
+ abortSignal: controller.signal,
431
+ })
432
+ ```
433
+
434
+ - A signal that is **already aborted** makes no request at all, not even `CreateMultipartUpload`.
435
+ - An **upload** that is aborted mid-flight drops its request. For a multipart upload the library
436
+ aborts it on the provider (`AbortMultipartUpload`), and `details.abort` says whether that
437
+ worked. That cleanup runs with a deadline of its own, never the
438
+ caller's signal, which would cancel it. A signal that fires while `CreateMultipartUpload` is in flight does not cancel that request, so the upload id it returns can still be aborted: the library waits for it within the same deadline, and aborts an id that arrives later without keeping the caller waiting.
439
+ As with any rejected upload, **a stream you passed as `body` is destroyed**.
440
+ - **Preparing an upload body is watched too**: while a validator reads the head of a stream, or the
441
+ pre-upload scan buffers it, an abort ends the call at once with the same error and destroys the
442
+ stream, even if the stream never delivers another byte.
443
+ - A **post-upload scan** that is still running when the signal aborts ends the call too, with the
444
+ same error and `details.stored: true`: the object is already stored. The scan carries on, and an
445
+ object it finds infected is still deleted.
446
+ - A **download** body that is being read when the signal aborts errors as `STORAGE_REQUEST_ABORTED`
447
+ while the idle guard is on (the default `bodyIdleTimeoutMs`); with `bodyIdleTimeoutMs: 0` it
448
+ errors as the raw `AbortError`.
449
+ - The library keeps no listener on your signal after a call, so one signal can be reused across many
450
+ calls.
451
+ - `copy`, `deleteMany` and the signed-URL methods take no `abortSignal`.
452
+
404
453
  ---
405
454
 
406
455
  ## 🔗 Signed URLs (GET / PUT / Multipart)
@@ -711,14 +760,14 @@ All errors are thrown as `StorageException extends HttpException`. The response
711
760
  | `STORAGE_SCAN_INFECTED` | 422 | Scanner returned `'infected'` (`details.threat`); `details.cleanup: 'failed'` means the object is still stored |
712
761
  | `STORAGE_SCAN_INCONCLUSIVE` | 422 | Scanner returned `'unknown'` and `rejectOnUnknown: true` |
713
762
  | `STORAGE_OBJECT_NOT_FOUND` | 404 | `head()`, `download()`, or `copy()` on a nonexistent key |
714
- | `STORAGE_PROVIDER_ERROR` | 502 | AWS SDK error (network, 5xx, throttling, `AccessControlListNotSupported`); `details` carries `awsCode`, `awsMessage`, `httpStatus`, `requestId` plus the operation context (`op`, `bucket`, and `key` or `prefix`) |
763
+ | `STORAGE_PROVIDER_ERROR` | 502 | The provider rejected the request (`AccessControlListNotSupported`, an `AccessDenied` on an object, any other rejection). **503** when it could not be reached (connection refused or reset, DNS failure) or answered with a server error (`SlowDown`, 500, 502, 504; not 501), which is worth retrying; **500** when it refused the credentials (`InvalidAccessKeyId`, `SignatureDoesNotMatch`), a deployment fault that a retry does not fix. `details` carries `awsCode`, `awsMessage`, `httpStatus`, `requestId` plus the operation context (`op`, `bucket`, and `key` or `prefix`) |
715
764
  | `STORAGE_SIGNED_URL_TTL_INVALID` | 400 | Per-request `ttlSeconds` ≤ 0 |
716
765
  | `STORAGE_PART_TOO_SMALL` | 400 | Never thrown: a `multipart.partSizeBytes` below 5 MiB fails at init as `STORAGE_INVALID_CONFIG` |
717
766
  | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts` not an integer from 1 to 10 000 (`details.provided`, `details.reason`) |
718
767
  | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
719
- | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed. `details.abort` is `'completed'` when the library aborted it, `'failed'` (with `abortError`) when the abort itself failed: that upload then stays open on the provider until a lifecycle rule removes it |
768
+ | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed (**503** when the cause is an outage, as for `STORAGE_PROVIDER_ERROR`). `details.abort` is `'completed'` when the library aborted it, `'failed'` (with `abortError`) when the abort itself failed: that upload then stays open on the provider until a lifecycle rule removes it |
720
769
  | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
721
- | `STORAGE_TIMEOUT` | 504 | An attempt got no response headers within `requestTimeoutMs`, or a multipart source stayed silent for `uploadIdleTimeoutMs` (`details.phase: 'source-idle'`) |
770
+ | `STORAGE_TIMEOUT` | 503 | An attempt got no response headers within `requestTimeoutMs`, a multipart source stayed silent for `uploadIdleTimeoutMs` (`details.phase: 'source-idle'`), or a download body stayed silent for `bodyIdleTimeoutMs` (`details.phase: 'body-idle'`) |
722
771
  | `STORAGE_LIFECYCLE_RULE_INVALID` | 400 | `BucketLifecycleService` input rejected: bad `id`, day count or `prefix`, or an id naming a rule outside `keyPrefix` (`details.reason`) |
723
772
  | `STORAGE_LIFECYCLE_UNSUPPORTED` | 501 | The provider does not implement the lifecycle API |
724
773
  | `STORAGE_LIFECYCLE_REJECTED` | 422 | The provider refused the lifecycle configuration |
@@ -727,6 +776,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
727
776
  | `STORAGE_BUCKET_REGION_MISMATCH` | 500 | `checkBucket()` got a 301 or `PermanentRedirect`: the bucket lives in another region than the configured one |
728
777
  | `STORAGE_NOT_MODIFIED` | 304 | `download()` with `ifNoneMatch` equal to the current ETag |
729
778
  | `STORAGE_PRECONDITION_FAILED` | 412 | `download()` with `ifMatch` different from the current ETag |
779
+ | `STORAGE_REQUEST_ABORTED` | 499 | The call's `abortSignal` aborted, before or during the call (`details.reason` is the name of the signal's reason: `AbortError`, `TimeoutError`, ...; for a multipart upload `details.abort` says whether the upload was aborted on the provider) |
730
780
 
731
781
  ```typescript
732
782
  import { StorageException, STORAGE_ERROR_CODES } from '@bymax-one/nest-storage'
@@ -913,7 +963,7 @@ This is the index.
913
963
  | ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
914
964
  | `upload` | `(options: UploadOptions) => Promise<UploadResult>` | Multipart via `@aws-sdk/lib-storage`; aborts on failure |
915
965
  | `download` | `(options: DownloadOptions) => Promise<{ stream, metadata }>` | Streaming; the body is never buffered |
916
- | `downloadBuffer` | `(options: DownloadOptions) => Promise<{ buffer, metadata }>` | Buffers — bounded by the caller's own memory |
966
+ | `downloadBuffer` | `(options: DownloadBufferOptions) => Promise<{ buffer, metadata }>` | Buffers — set `maxBytes` to bound it; without it the whole object is held |
917
967
  | `head` | `(key, options?) => Promise<ObjectMetadata>` | Metadata without transferring the body |
918
968
  | `exists` | `(key, options?) => Promise<boolean>` | `head` reduced to a boolean; any non-404 failure is logged and returns `false` |
919
969
  | `getPublicUrl` | `(key, options?) => string` | Composed, not signed — for buckets that are public by policy |