@bymax-one/nest-storage 1.1.10 → 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 +160 -1
- package/README.md +321 -362
- 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,163 @@ 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
|
+
|
|
157
|
+
## [1.1.11] - 2026-11-13
|
|
158
|
+
|
|
159
|
+
### Changed
|
|
160
|
+
|
|
161
|
+
- **Development and CI tooling updated; the published code does not change.** The AWS SDK
|
|
162
|
+
development dependencies and the pinned GitHub Actions are bumped to newer patch releases.
|
|
163
|
+
No file under `src/` changed.
|
|
164
|
+
|
|
165
|
+
### Documentation
|
|
166
|
+
|
|
167
|
+
- **The README is shorter and corrected.** The API table and the export list now match the
|
|
168
|
+
published surface, text that repeated itself or did not belong is removed, and the security
|
|
169
|
+
controls are restored as one compact table with a row per control.
|
|
170
|
+
|
|
171
|
+
**Apply to a derived backend:** nothing to change; this release carries no runtime change.
|
|
172
|
+
|
|
16
173
|
## [1.1.10] - 2026-11-09
|
|
17
174
|
|
|
18
175
|
### Fixed
|
|
@@ -667,4 +824,6 @@ have regressed from. They are kept because the reasoning is worth having.
|
|
|
667
824
|
[1.1.8]: https://github.com/bymaxone/nest-storage/compare/v1.1.7...v1.1.8
|
|
668
825
|
[1.1.9]: https://github.com/bymaxone/nest-storage/compare/v1.1.8...v1.1.9
|
|
669
826
|
[1.1.10]: https://github.com/bymaxone/nest-storage/compare/v1.1.9...v1.1.10
|
|
670
|
-
[
|
|
827
|
+
[1.1.11]: https://github.com/bymaxone/nest-storage/compare/v1.1.10...v1.1.11
|
|
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
|