@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 +143 -1
- package/README.md +64 -14
- package/dist/server/index.cjs +559 -182
- package/dist/server/index.d.cts +70 -36
- package/dist/server/index.d.ts +70 -36
- package/dist/server/index.mjs +560 -183
- 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/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
|
-
[
|
|
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
|
|
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
|
-
//
|
|
387
|
-
const { buffer, metadata } = await this.storage.downloadBuffer({
|
|
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 |
|
|
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` |
|
|
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:
|
|
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 |
|