@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 CHANGED
@@ -13,6 +13,170 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.13] - 2026-11-16
17
+
18
+ ### Security
19
+
20
+ - **A failed call no longer tells its client what the driver or the provider said.** The body of a
21
+ `StorageException` carried `details.awsMessage`, and for a failed multipart abort `abortError`, a
22
+ failed post-upload delete `cleanupError`, and `deleteMany` the text of each failure. For a provider
23
+ that could not be reached that text is the driver's own, such as `connect ECONNREFUSED 10.0.3.7:9000`,
24
+ and a host that returns `getResponse()` unchanged (Nest's default) handed a caller the address and
25
+ port of the storage service. The body now holds a fixed `details.reason` beside `awsCode`, `httpStatus`
26
+ and `requestId`, which stay. What the driver and the provider said is logged for a provider failure, as a warning
27
+ that starts `Provider call failed` (or `Multipart abort failed`), from named fields only: the error's
28
+ name, the provider's code, the status, the request id and the message, with a signature or an access
29
+ key id in it masked and its length bounded. The error object is not attached to the exception.
30
+ `deleteMany`'s `failed[].error` is the provider's error code for a key it refused, or the fixed reason
31
+ when the whole request failed.
32
+
33
+ **Apply to a derived backend:** a host that read `details.awsMessage`, `abortError` or the text in
34
+ `cleanupError` finds that text in the library's warn log instead; the exception no longer carries it,
35
+ so there is nothing to forward to a client by mistake. A host that matched on that text matches
36
+ `details.reason` (`unreachable`, `timeout`, `provider-error`, `credentials-refused` or `rejected`) or
37
+ `awsCode`.
38
+
39
+ ## [1.1.12] - 2026-11-14
40
+
41
+ ### Added
42
+
43
+ - **`abortSignal` ends a call.** `upload`, `download`, `downloadBuffer`, `list`, `head`, `exists`,
44
+ `delete` and `checkBucket` take an optional `abortSignal`. When it aborts the call rejects the new
45
+ `STORAGE_REQUEST_ABORTED` (HTTP 499), with `details.reason` set to the name of the signal's
46
+ reason, never its message; a signal that is already aborted makes no request. A multipart upload
47
+ is aborted on the provider, with a deadline of its own and not the caller's signal
48
+ (`details.abort` reports the outcome); a download body being read errors as the same
49
+ code while the idle guard is on, and as the raw `AbortError` with `bodyIdleTimeoutMs: 0`. The
50
+ library adds no listener to the signal that outlives the call, so one signal can be reused.
51
+ `exists` rejects an aborted call instead of answering `false`. An abort during a post-upload scan
52
+ ends the call with `details.stored: true` (the object is stored; the scan carries on and still
53
+ deletes an infected one).
54
+
55
+ **Apply to a derived backend:** nothing changes unless you pass a signal. The new code is part of
56
+ the shared `STORAGE_ERROR_CODES` table: a host that maps every code exhaustively needs a case for
57
+ it, and an HTTP layer should not answer 5xx for it, since the caller ended the call.
58
+
59
+ - **`downloadBuffer({ maxBytes })` bounds what a buffered download holds.** `downloadBuffer` read the
60
+ whole object into memory whatever its size, so one large or hostile object could exhaust the
61
+ process. With `maxBytes`, an object whose `Content-Length` is larger is refused before its body is
62
+ read, and a body that is longer than it said, or has no length, is cut off as it is counted; both
63
+ reject `STORAGE_SIZE_EXCEEDED` (`details.maxSize`, and `details.contentLength` for the first) and
64
+ release the connection. A value that is not an integer of at least `1` rejects
65
+ `STORAGE_VALIDATION_FAILED` before any request. There is no default: without `maxBytes` the call
66
+ behaves as before. The new `DownloadBufferOptions` type is exported.
67
+
68
+ **Apply to a derived backend:** nothing changes until you pass `maxBytes`. Set it wherever a
69
+ backend calls `downloadBuffer` on an object it does not control, to what the process can hold.
70
+
71
+ - **`bodyIdleTimeoutMs` bounds a download body that stops delivering.** `requestTimeoutMs` ends when
72
+ the response headers arrive, so a provider that stalled mid-body left the stream, its connection
73
+ and the caller waiting for as long as the provider chose. After `bodyIdleTimeoutMs` of silence
74
+ while the caller is reading, `download` and `downloadBuffer` now fail with `STORAGE_TIMEOUT`
75
+ (`details.phase: 'body-idle'`) and the connection is released. The clock runs only while a read
76
+ is pending, so a slow consumer never trips it. It defaults to `requestTimeoutMs`; `0` turns it off.
77
+
78
+ **Apply to a derived backend:** a download that went quiet for longer than `requestTimeoutMs`
79
+ (30 s by default) used to wait on; it now fails `STORAGE_TIMEOUT`. If you serve very large
80
+ objects through a source that can pause that long, raise `bodyIdleTimeoutMs` or set it to `0`;
81
+ while the guard is on the stream returned by `download` is a wrapper, so code that read SDK-only
82
+ members from it (such as `transformToByteArray`) must read it as a stream instead.
83
+
84
+ ### Changed
85
+
86
+ - **An unavailable provider answers 503, not 502, 504 or 500.** `STORAGE_TIMEOUT` was HTTP 504 and is
87
+ now **503**. `STORAGE_PROVIDER_ERROR` keeps its code and stays 502 for a request the provider
88
+ rejected, but is **503** when the provider could not be reached (connection refused or reset, DNS
89
+ failure) or answered with a server error (`SlowDown`, 500, 502, 504; not 501), and **500** when it
90
+ refused the credentials (`InvalidAccessKeyId`, `SignatureDoesNotMatch`: a deployment fault a retry
91
+ does not fix; the `HEAD` calls carry no error body, so for them the credentials case is not told
92
+ apart). `STORAGE_MULTIPART_ABORTED` is **503** when the cause is an outage and stays 500 otherwise.
93
+ A client then has one status, 503, to treat as "retry later" whichever library answered.
94
+
95
+ **Apply to a derived backend:** the codes are unchanged; only the HTTP status of the cases above
96
+ moves. A host that matches `504` or `502` to retry must match `503`, and one that maps
97
+ `STORAGE_PROVIDER_ERROR` to a fixed status by code must read `error.getStatus()` instead.
98
+
99
+ - **Development and CI tooling updated; the published code does not change by it.** The release
100
+ workflow follows the organisation's template: the build job installs, runs the gates and packs the
101
+ tarball once without a credential, and the publish job, which holds the token and runs no code
102
+ from the package, publishes only that tarball after checking its digest. `glob` and `minimatch`
103
+ are raised above their advisory floors, so their OSV ignores are gone, the timing assertions of
104
+ the test suite no longer depend on how loaded the machine is, and the pull request check now
105
+ compiles the README snippets against the built package, as the release already did.
106
+
107
+ **Apply to a derived backend:** nothing to change.
108
+
109
+ ### Fixed
110
+
111
+ - **`requestTimeoutMs`, `uploadIdleTimeoutMs` and `bodyIdleTimeoutMs` are refused above 2147483647.**
112
+ Each feeds a timer, and Node clamps a timer above 2**31 - 1 milliseconds to 1 ms, so a larger value
113
+ made every request or read fail at once instead of waiting longer. `validateOptions` now throws
114
+ `STORAGE_INVALID_CONFIG` naming the option for a value above the ceiling (about 24.8 days); the
115
+ ceiling itself is accepted.
116
+
117
+ **Apply to a derived backend:** if you set one of these three above `2147483647` (to mean "very
118
+ long"), lower it, or for the two idle guards use `0` to turn the guard off; the module now refuses
119
+ to start with such a value.
120
+
121
+ - **`publicBaseUrl` and `cdnBaseUrl` are refused when they carry credentials.** Either is returned to
122
+ callers as the base of every `publicUrl`, so a user or password in either, including one given
123
+ through a provider recipe's `customDomain`, reached clients and anything that stores or logs those
124
+ URLs. `validateOptions` now throws `STORAGE_INVALID_CONFIG` naming the option and repeating neither
125
+ the user nor the password, from `forRoot` and `forRootAsync` alike. The same check now applies to
126
+ `endpoint`, `publicBaseUrl` and `cdnBaseUrl`: an `@` in the host part (the text after an optional
127
+ scheme and slashes, up to the first `/`, `?` or `#`) is refused, with or without a password.
128
+
129
+ **Apply to a derived backend:** if one of these URLs embeds `user@` or `user:password@`, remove it before upgrading;
130
+ the module now refuses to start with such a value.
131
+
132
+ - **A key or a provider message in a log line is written as one escaped token.** The scanner warnings
133
+ (`Infected file detected`, `Inconclusive scan result accepted`), the idempotent-delete warning, the
134
+ `exists` warning and the `STORAGE_SCAN_CLEANUP_FAILED` error repeated the object key, the scanner's
135
+ engine and threat names, or the provider's message as they were. S3 accepts a key with a newline, a
136
+ carriage return or an escape sequence, so such a key could end its log line and forge the next, or
137
+ colour or hide what followed. Each of those values is now a quoted token in which control
138
+ characters, and the invisible or bidirectional characters JSON leaves literal, show as `\n`, `\r`,
139
+ `\uNNNN` or `\u{...}`.
140
+
141
+ **Apply to a derived backend:** nothing changes in behaviour or in an error response. If a log
142
+ parser matches `key=<value>` in these lines, the value is now enclosed in double quotes.
143
+
144
+ - **An endpoint that carries credentials is refused, and the boot log no longer prints the endpoint
145
+ whole.** The `S3Client initialized` line repeated `endpoint` as configured, so an endpoint such as
146
+ `https://KEY:SECRET@host` wrote the secret to the log, and the same string is the base of every
147
+ `publicUrl` the library returns when no `publicBaseUrl` is set. `validateOptions` now throws
148
+ `STORAGE_INVALID_CONFIG` for an endpoint with a user or password, without repeating it, and the log
149
+ line shows only protocol, host and port.
150
+
151
+ **Apply to a derived backend:** if your `endpoint` embeds `user:password@`, move the keys to
152
+ `credentials` before upgrading; the module now refuses to start with such a value.
153
+
154
+ - **`requestTimeoutMs` and `maxAttempts` are now checked at boot.** A value of `0`, a negative or
155
+ fractional number, `NaN` or `Infinity`, or a non-number reached the S3 client unchecked, and the
156
+ request handler treats a `0` or `NaN` timeout as no timeout, so a typo could switch the bound off
157
+ without a sign. Both options must now be integers of at least `1`; anything else throws
158
+ `STORAGE_INVALID_CONFIG` naming the option.
159
+
160
+ **Apply to a derived backend:** if your configuration passes `0` for either option, or computes
161
+ one that can be fractional, change it to a positive integer before upgrading; a module that booted
162
+ with such a value now refuses to start.
163
+
164
+ - **`validation.maxSizeBytes` now bounds every upload body, not only a declared `size`.** The limit
165
+ was compared with the `size` option alone, so a stream with no `size`, a stream longer than the
166
+ `size` it declared, and a `Buffer` or `Uint8Array` with no `size` were all stored whatever their
167
+ length. A multipart upload is now counted as it is read: past the limit (or past the declared
168
+ `size`, if that is lower) the multipart upload is aborted, the source is destroyed, and `upload()` rejects `STORAGE_SIZE_EXCEEDED` with `details.maxSize` or
169
+ `details.declaredSize` and the abort outcome. A buffer is checked by its own length. A string or
170
+ `ArrayBuffer` body, which the types forbid but untyped callers can pass, is now sent as its bytes
171
+ (a string as UTF-8) and measured in bytes. A single-shot stream is still sent as `size` bytes, as
172
+ before.
173
+
174
+ **Apply to a derived backend:** if you set `validation.maxSizeBytes`, an upload that used to pass
175
+ because it carried no `size` is now refused when it is longer than the limit; expect
176
+ `STORAGE_SIZE_EXCEEDED` from a stream or buffer over it, and pass `size` only when it is true. A
177
+ buffer's declared `size` is ignored in favour of its length, so a small buffer declared as large
178
+ is no longer refused or sent as multipart.
179
+
16
180
  ## [1.1.11] - 2026-11-13
17
181
 
18
182
  ### Changed
@@ -684,4 +848,6 @@ have regressed from. They are kept because the reasoning is worth having.
684
848
  [1.1.9]: https://github.com/bymaxone/nest-storage/compare/v1.1.8...v1.1.9
685
849
  [1.1.10]: https://github.com/bymaxone/nest-storage/compare/v1.1.9...v1.1.10
686
850
  [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
851
+ [1.1.12]: https://github.com/bymaxone/nest-storage/compare/v1.1.11...v1.1.12
852
+ [1.1.13]: https://github.com/bymaxone/nest-storage/compare/v1.1.12...v1.1.13
853
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.13...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)
@@ -549,8 +598,8 @@ bodies are not affected, and `post-upload` hands the scanner the key only, no bo
549
598
  when the scanner rejects it, so the library deletes it and rejects `upload()` with the verdict
550
599
  (`STORAGE_SCAN_INFECTED` or `STORAGE_SCAN_INCONCLUSIVE`). If that delete fails the verdict is still the
551
600
  error, and `details` carries `cleanup: 'failed'`, the `key` you passed, the `storedKey` (with any
552
- `keyPrefix`, as a bucket listing shows it) and the delete failure in `cleanupError`; the failure is
553
- also logged at error level as `STORAGE_SCAN_CLEANUP_FAILED`. With no `details.cleanup` the object was
601
+ `keyPrefix`, as a bucket listing shows it) and the code of the delete failure in `cleanupError`; the
602
+ failure, with what the provider said, is logged at error level as `STORAGE_SCAN_CLEANUP_FAILED`. With no `details.cleanup` the object was
554
603
  removed; with `cleanup: 'failed'` it is **still stored** and has to be removed by other means.
555
604
 
556
605
  ---
@@ -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`, `httpStatus`, `requestId` and a fixed `reason` (`unreachable`, `provider-error`, `credentials-refused` or `rejected`; never the text of the driver or of the provider) 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'` when the abort itself failed (logged as a warning, with what it threw): 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 |