@bymax-one/nest-storage 1.1.0 → 1.1.2

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
@@ -2,12 +2,190 @@
2
2
 
3
3
  All notable changes to `@bymax-one/nest-storage` are documented in this file.
4
4
 
5
- The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5
+ The format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
6
+
7
+ Versioning is **not** strict [SemVer](https://semver.org/spec/v2.0.0.html) while this API is
8
+ pre-stable: breaking changes ship in minor and patch releases by explicit `@bymax-one` policy,
9
+ so a version number carries no compatibility information. The **Apply to a derived backend**
10
+ note on each entry is the compatibility contract — read it, not the number.
6
11
 
7
12
  ---
8
13
 
9
14
  ## [Unreleased]
10
15
 
16
+ ## [1.1.2] - 2026-10-31
17
+
18
+ ### Changed
19
+
20
+ - **Keys the library returns are relative to `keyPrefix`, so every one can be passed back.**
21
+ `UploadResult.key` and `ObjectMetadata.key` (from `head`, `download`, `downloadBuffer`) carried
22
+ the `keyPrefix`, while every method prepends it again, so with a prefix set `head(r.key)`,
23
+ `exists`, `download`, `delete` and a signed-URL call addressed `prefix/prefix/key`. `delete`
24
+ was the quiet one: it removed nothing and reported success. `list()` and `deleteMany()` already
25
+ returned relative keys. `UploadResult.publicUrl` is unchanged and still carries the prefix.
26
+
27
+ **Apply to a derived backend:** only a deployment with a non-empty `keyPrefix` is affected. In
28
+ 1.0.0 to 1.1.1 the returned key is `prefix/name` and cannot be passed back; from this release it is
29
+ `name`. A `.key` value you stored from an earlier version carries the prefix: strip it once (for
30
+ example `stored.slice(prefix.length + 1)`, where `prefix` is the normalized `keyPrefix` without
31
+ surrounding slashes) before passing it to the library, and when you read keys from your database
32
+ stop adding or removing the prefix yourself.
33
+ - **`upload()` destroys a `Readable` body it rejects.** A rejected upload (invalid key or content
34
+ type, a validation or scan failure, a provider error) used to leave the caller's stream open, so the
35
+ file handle or the connection behind it stayed held. The library now takes ownership of the stream, as
36
+ `stream.pipeline` does, and destroys it; a cache hit destroys it unread. The stream is destroyed
37
+ without an error, because the AWS SDK (under its default checksum setting) wraps a stream body in its
38
+ own Readable and forwards the source's error to it, and nothing listens to that wrapper once the
39
+ request has failed; the failure is the rejection of `upload()`, and a listener on the stream sees
40
+ `'close'`. Destroying can still emit `'error'` when the stream's own cleanup fails, so the library
41
+ attaches a no-op listener first.
42
+
43
+ **Apply to a derived backend:** do not reuse a stream you passed to `upload()`. A caller that
44
+ fixed a validation error and retried with the same, still unread, stream must open a new one.
45
+
46
+ ### Added
47
+
48
+ - **`STORAGE_NOT_MODIFIED` (304) and `STORAGE_PRECONDITION_FAILED` (412).** `download()` with
49
+ `ifNoneMatch` equal to the current ETag, or `ifMatch` that differs, used to surface as a generic
50
+ `STORAGE_PROVIDER_ERROR` (502); they now have their own codes, so a caller can branch on them.
51
+ A 304 is thrown, not returned.
52
+ - **`BucketLifecycleService.upsert` writes multipart-abort rules.** An input with
53
+ `abortIncompleteMultipartDays` instead of `expirationDays` adds or replaces an
54
+ `AbortIncompleteMultipartUpload` rule, so abandoned multipart uploads stop holding storage. The
55
+ read-modify-write, the preservation of other rules and the `keyPrefix` rules are the same; an empty
56
+ prefix is allowed for this rule only (it means the module's whole namespace, and aborting deletes no
57
+ object). Types `AbortMultipartRuleInput` and `LifecycleRuleInput`. MinIO does not accept this rule
58
+ through the S3 API (the end-to-end suite shows the typed `STORAGE_LIFECYCLE_REJECTED`); AWS and R2
59
+ document it.
60
+ - **`BucketLifecycleService`: bucket lifecycle rules.** `get()` returns the rules (an empty array when
61
+ the bucket has no configuration), `upsert({ id, prefix, expirationDays })` adds or replaces one
62
+ expiration rule by id, and `remove(id)` deletes one. Both writes read the configuration, change
63
+ only the rule with that id and write the full set back, so every other rule (transitions, tag
64
+ filters, multipart aborts) is sent back as the provider returned it. Removing the last rule calls
65
+ `DeleteBucketLifecycle`, because S3 rejects a put with no rules. The read-modify-write is not
66
+ atomic: S3 has no conditional lifecycle write, so a concurrent writer can be overwritten.
67
+ The service is exported from the package and from the module.
68
+ - **Error codes:** `STORAGE_LIFECYCLE_RULE_INVALID` (400), `STORAGE_LIFECYCLE_UNSUPPORTED`
69
+ (501) and `STORAGE_LIFECYCLE_REJECTED` (422).
70
+ - Types `BucketLifecycleRule`, `BucketLifecycleRuleView`, `LifecycleBucketOptions` and
71
+ `ExpirationRuleInput`.
72
+
73
+ **Apply to a derived backend:** additive; nothing existing changes. A consumer that applies
74
+ lifecycle rules through the raw `S3Client` can switch to this service. Rule prefixes are relative
75
+ to `keyPrefix`; with a `keyPrefix` set, rules outside it are returned flagged and are not changed.
76
+ Providers other than MinIO (tested) and Cloudflare R2 (documented) are unverified; see the README.
77
+
78
+ ### Fixed
79
+
80
+ - **`requestTimeoutMs` now takes effect.** It was resolved and defaulted to 30 000 ms but never
81
+ passed to the S3 client, so a request to an endpoint that stopped answering waited forever. It is
82
+ now the client's `requestTimeout` with `throwOnRequestTimeout`, and an attempt that gets no
83
+ response headers in time fails as `STORAGE_TIMEOUT` (504). A failure inside a multipart upload
84
+ still surfaces as `STORAGE_MULTIPART_ABORTED`.
85
+
86
+ **Apply to a derived backend:** a behaviour change. The 30 s default now applies to every
87
+ attempt, and an upload body counts toward it: a single-shot upload that needs longer than 30 s
88
+ (a slow link, a body near `multipart.thresholdBytes`) now fails. Raise `requestTimeoutMs` for
89
+ such workloads before upgrading. It does not limit reading a download stream.
90
+ - **A stream body under a pre-upload scanner no longer hangs the upload.** The scanner and the upload
91
+ were handed the same stream object; a scanner that read it left the upload with nothing to send, and
92
+ `upload()` never returned (nothing was stored). In `pre-upload` mode a stream is now read into one
93
+ buffer, bounded by `validation.maxSizeBytes`, and the scanner and the upload share that buffer. A
94
+ stream longer than the limit, or any stream when `maxSizeBytes` is unset, is refused with
95
+ `STORAGE_VALIDATION_FAILED`.
96
+
97
+ **Apply to a derived backend:** if you scan streams before upload, set `validation.maxSizeBytes`
98
+ (or switch the scanner to `post-upload`), and expect the stream to be held in memory up to that size.
99
+ With `requestTimeoutMs` an upload whose stream was consumed fails as `STORAGE_TIMEOUT` instead of
100
+ hanging.
101
+ - **`getMultipartUploadUrls` validates `parts`.** Only `parts <= 0` was refused, so a fraction, `NaN`
102
+ or a count above S3's 10 000 part numbers was accepted. `parts` must now be an integer from 1 to
103
+ 10 000, or the call throws `STORAGE_INVALID_PART_COUNT`. The README documents the 5 MiB minimum for
104
+ every part but the last, the absence of an abort URL, and the `AbortIncompleteMultipartUpload`
105
+ lifecycle rule recommended against orphaned uploads.
106
+ - **`signedUrls.maxTtlSeconds` above 604 800 is reduced at init.** The SigV4 signer rejects any
107
+ expiry over 7 days, so a larger configured ceiling made every request above 7 days fail with a
108
+ provider error while shorter requests worked. The ceiling is now capped at 604 800 s when the
109
+ module starts, with one warning naming both values. A boot that worked before still boots.
110
+ - **`STORAGE_PART_TOO_SMALL` is documented as reserved.** Nothing throws it: a part size under the
111
+ S3 minimum is rejected at init as `STORAGE_INVALID_CONFIG`. The code stays in the contract.
112
+ - **The published-surface gate now fails on a wrong option, method or field in a README snippet.**
113
+ `check:published` ran `tsc` on the snippets, which stops after syntax errors and so never reported
114
+ the semantic ones once any snippet had a parse error; it compiled only snippets that import the
115
+ package; and it ignored every undeclared name, so a call through one resolved to `any`. Every
116
+ snippet is now compiled with the syntactic and semantic diagnostics together, public names are
117
+ imported for it, and the names a snippet takes from the surrounding prose are typed in
118
+ `scripts/readme-prelude.ts`. A diagnostic about a missing property is excused as an abbreviated
119
+ example only when the type is a plain identifier the snippet declares itself, searched outside its
120
+ imports, so a wrong method on an imported or union type fails.
121
+ The prelude is compiled as a `.ts` file, so a type in it that stops resolving is an error rather than
122
+ an `any`, and any syntax error in a snippet fails the gate.
123
+ - **README option defaults and examples now match the code.** The configuration table listed
124
+ `signedUrls.defaultTtlSeconds` (no such option; the options are `defaultGetTtlSeconds` and
125
+ `defaultPutTtlSeconds`, both 300 s, not 3600), a 10 MiB multipart threshold and an 8 MiB part size
126
+ (both are 5 MiB), a `'NONE'` module-level encryption value (accepted per upload only) and a "sensible
127
+ default" MIME whitelist (there is none). The validator, scanner-mode and multipart-URL examples used
128
+ names that do not exist (`validators`, `'both'`, `partCount`, `valid`). The error-code table now
129
+ matches the key guard (it rejects an empty key and a null byte, not "empty after normalization"),
130
+ and the `STORAGE_PART_TOO_SMALL` note says what the code does.
131
+ A new spec parses the README option-default table and the error-code table and fails when either
132
+ drifts from the code.
133
+
134
+ **Apply to a derived backend:** documentation only; no behaviour changed.
135
+
136
+ ## [1.1.1] - 2026-10-30
137
+
138
+ Apart from the removal below, nothing here changes the published bundle: the remaining entries are
139
+ development, test and CI tooling.
140
+
141
+ ### Removed
142
+
143
+ - **`BYMAX_STORAGE_LOGGER` and `BYMAX_STORAGE_IDEMPOTENCY_CACHE` are no longer exported.**
144
+ Both were re-exported from the package barrel while being absent from the module's
145
+ `exports`: no provider ever registered `BYMAX_STORAGE_LOGGER`, and the idempotency cache is
146
+ registered but deliberately not exported. Injecting either raised
147
+ `UnknownDependenciesException` and the application failed to boot, so neither has ever been
148
+ usable as an injectable token from this library.
149
+
150
+ **Apply to a derived backend:** delete every *import* of these two names, not only the
151
+ injections. The reliable signal is the TypeScript error `TS2305: Module … has no exported
152
+ member '…'`, which fires in both module systems. At runtime the two differ, and only one is
153
+ loud: an ESM consumer fails at module-link time with `SyntaxError: The requested module does
154
+ not provide an export named '…'` before Nest bootstraps, while a CommonJS consumer — the
155
+ common case for a compiled NestJS application — silently receives `undefined` and fails later
156
+ with a confusing resolution error. Do not wait for a crash to find these; grep for the names.
157
+
158
+ One shape did work and is the one to migrate deliberately: registering the exported symbol as
159
+ **your own** provider (`{ provide: BYMAX_STORAGE_LOGGER, useValue: myLogger }`) and injecting
160
+ it in your own service. That never involved this library's DI container. Replace the symbol
161
+ with a token you own — `Symbol('MY_STORAGE_LOGGER')` — and nothing else changes.
162
+
163
+ For logging specifically: services here use `new Logger(ClassName)` from `@nestjs/common`, so
164
+ `app.useLogger(...)` redirects them all, which is what this token pretended to offer.
165
+
166
+ ### Security
167
+
168
+ - Raised the floors of vulnerable transitive dev dependencies through `pnpm.overrides` in
169
+ `pnpm-workspace.yaml`: `browserslist`, `fast-uri`, `qs`, `undici`, `multer`, `brace-expansion`,
170
+ `handlebars`, `js-yaml`, `@grpc/grpc-js`, `body-parser`, `proxy-addr` and `zod`. Every one is
171
+ reached only through test, lint or mutation tooling; `dependencies` is empty, so none ships.
172
+ - `osv-scanner.toml` ignores `GHSA-gcqx-w48m-w2h4` (`deepmerge`, reached only through
173
+ `jest-config`) until 2027-01-27, because no patched release exists.
174
+
175
+ ### Changed
176
+
177
+ - Moved the development toolchain to ESLint 10 and bumped the `dev-dependencies` groups.
178
+ - The E2E suite starts its S3 server from one image, pinned by digest, held in
179
+ `test/e2e/fixtures/minio-container.ts`; the CI workflow pre-pulls the reference it reads from
180
+ that file.
181
+ - Bumped the pinned CI actions (`actions/setup-node`, `actions/upload-artifact`,
182
+ `step-security/harden-runner`, `pnpm/action-setup`, `github/codeql-action/upload-sarif`) and moved
183
+ the OSV scan and the shared review-rules sync to their shared workflows.
184
+
185
+ ### Tests
186
+
187
+ - `mapAwsError` is now asserted never to attach the caught error, on every branch.
188
+
11
189
  ## [1.1.0] - 2026-08-11
12
190
 
13
191
  Coordinated ecosystem release aligning every `@bymax-one/*` package after the ioredis 6 /
@@ -275,4 +453,6 @@ have regressed from. They are kept because the reasoning is worth having.
275
453
  [1.0.5]: https://github.com/bymaxone/nest-storage/compare/v1.0.4...v1.0.5
276
454
  [1.0.6]: https://github.com/bymaxone/nest-storage/compare/v1.0.5...v1.0.6
277
455
  [1.1.0]: https://github.com/bymaxone/nest-storage/compare/v1.0.6...v1.1.0
278
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.0...HEAD
456
+ [1.1.1]: https://github.com/bymaxone/nest-storage/compare/v1.1.0...v1.1.1
457
+ [1.1.2]: https://github.com/bymaxone/nest-storage/compare/v1.1.1...v1.1.2
458
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.2...HEAD