@bymax-one/nest-storage 1.1.14 → 1.1.15

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,23 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.15] - 2026-11-17
17
+
18
+ ### Fixed
19
+
20
+ - **A download body that fails after its headers no longer reaches the caller as the SDK's raw error.** A
21
+ connection reset in the middle of a body (`ECONNRESET`, message `aborted`) passed through unmapped: a
22
+ caller that caught only `StorageException` missed it, and a Nest handler answered 500 for it. With the idle
23
+ guard on (the default), a failure of the body is now mapped as any other failure of the provider
24
+ (`STORAGE_PROVIDER_ERROR`, **503** for a cut connection, with its fixed `reason`), and `downloadBuffer()`
25
+ maps it in both modes, with `STORAGE_REQUEST_ABORTED` when the caller's signal aborted. Nothing a client
26
+ receives carries the driver's text.
27
+
28
+ **Apply to a derived backend:** a host that caught the raw `ECONNRESET` from `download()` or
29
+ `downloadBuffer()` must catch `StorageException` instead (the status is 503 for a reset). With
30
+ `bodyIdleTimeoutMs: 0`, the stream `download()` returns is still the SDK's own and still errors with the
31
+ SDK's error, as documented; only `downloadBuffer()` changes there.
32
+
16
33
  ## [1.1.14] - 2026-11-16
17
34
 
18
35
  ### Changed
@@ -865,4 +882,5 @@ have regressed from. They are kept because the reasoning is worth having.
865
882
  [1.1.12]: https://github.com/bymaxone/nest-storage/compare/v1.1.11...v1.1.12
866
883
  [1.1.13]: https://github.com/bymaxone/nest-storage/compare/v1.1.12...v1.1.13
867
884
  [1.1.14]: https://github.com/bymaxone/nest-storage/compare/v1.1.13...v1.1.14
868
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.14...HEAD
885
+ [1.1.15]: https://github.com/bymaxone/nest-storage/compare/v1.1.14...v1.1.15
886
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.15...HEAD
package/README.md CHANGED
@@ -241,7 +241,7 @@ Options accepted by `forRoot` and `forRootAsync`:
241
241
 
242
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.
243
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`.
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`. A body that fails after its headers arrived (a reset connection) ends as a `StorageException` like any other failure of the provider (`STORAGE_PROVIDER_ERROR`, **503** when the connection was cut); with the guard off only `download()` is the exception, its stream being the SDK's own and so erroring with the SDK's own error, while `downloadBuffer()` is mapped in both modes.
245
245
 
246
246
 
247
247
  [aws-presigned-expiry]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
@@ -444,8 +444,9 @@ await this.storage.upload({
444
444
  same error and `details.stored: true`: the object is already stored. The scan carries on, and an
445
445
  object it finds infected is still deleted.
446
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`.
447
+ while the idle guard is on (the default `bodyIdleTimeoutMs`), and `downloadBuffer()` rejects with it in
448
+ both modes. With `bodyIdleTimeoutMs: 0` the stream `download()` returns is the SDK's own and errors with
449
+ the SDK's own error, whichever it is where the abort lands.
449
450
  - The library keeps no listener on your signal after a call, so one signal can be reused across many
450
451
  calls.
451
452
  - `copy`, `deleteMany` and the signed-URL methods take no `abortSignal`.
@@ -1299,6 +1299,10 @@ var SourceIdleError = class extends Error {
1299
1299
  }
1300
1300
  idleMs;
1301
1301
  };
1302
+ function isError(value) {
1303
+ const candidate = value;
1304
+ return typeof candidate?.name === "string" && typeof candidate.message === "string";
1305
+ }
1302
1306
  function withinIdleTime(next, idleMs) {
1303
1307
  return new Promise((resolve, reject) => {
1304
1308
  const timer = setTimeout(() => {
@@ -1311,7 +1315,7 @@ function withinIdleTime(next, idleMs) {
1311
1315
  },
1312
1316
  (error) => {
1313
1317
  clearTimeout(timer);
1314
- reject(error instanceof Error ? error : new Error(describeError(error)));
1318
+ reject(isError(error) ? error : new Error(describeError(error)));
1315
1319
  }
1316
1320
  );
1317
1321
  });
@@ -1715,9 +1719,15 @@ function guardDownloadBody(body, idleMs, context, signal) {
1715
1719
  idleMs: error.idleMs
1716
1720
  });
1717
1721
  }
1718
- return signal?.aborted ? requestAborted(signal, context) : error;
1722
+ return signal?.aborted ? requestAborted(signal, context) : mapAwsError(error, context);
1719
1723
  });
1720
1724
  }
1725
+ function mapBodyReadFailure(err, signal, context) {
1726
+ if (err instanceof StorageException) {
1727
+ return err;
1728
+ }
1729
+ return signal?.aborted ? requestAborted(signal, context) : mapAwsError(err, context);
1730
+ }
1721
1731
 
1722
1732
  // src/server/utils/public-url.ts
1723
1733
  function buildPublicUrl(options, finalKey, bucket) {
@@ -1807,7 +1817,7 @@ function assertMaxBytes(maxBytes) {
1807
1817
  });
1808
1818
  }
1809
1819
  }
1810
- async function readDownloadBody(stream, metadata, maxBytes) {
1820
+ async function readBody(stream, metadata, maxBytes) {
1811
1821
  if (maxBytes === void 0) {
1812
1822
  return readStream(stream);
1813
1823
  }
@@ -1822,6 +1832,17 @@ async function readDownloadBody(stream, metadata, maxBytes) {
1822
1832
  }
1823
1833
  return buffer;
1824
1834
  }
1835
+ async function readDownloadBody(stream, metadata, maxBytes, signal) {
1836
+ try {
1837
+ return await readBody(stream, metadata, maxBytes);
1838
+ } catch (err) {
1839
+ throw mapBodyReadFailure(err, signal, {
1840
+ key: metadata.key,
1841
+ bucket: metadata.bucket,
1842
+ op: "downloadBuffer"
1843
+ });
1844
+ }
1845
+ }
1825
1846
 
1826
1847
  // src/server/services/storage.service.ts
1827
1848
  var MAX_LIST_KEYS = 1e3;
@@ -2095,7 +2116,7 @@ exports.StorageService = class StorageService {
2095
2116
  const stream = guardDownloadBody(
2096
2117
  response.Body,
2097
2118
  this.options.bodyIdleTimeoutMs,
2098
- { key: finalKey, bucket },
2119
+ context,
2099
2120
  options.abortSignal
2100
2121
  );
2101
2122
  return { stream, metadata: this.toObjectMetadata(response, finalKey, bucket) };
@@ -2118,7 +2139,8 @@ exports.StorageService = class StorageService {
2118
2139
  async downloadBuffer(options) {
2119
2140
  assertMaxBytes(options.maxBytes);
2120
2141
  const { stream, metadata } = await this.download(options);
2121
- return { buffer: await readDownloadBody(stream, metadata, options.maxBytes), metadata };
2142
+ const buffer = await readDownloadBody(stream, metadata, options.maxBytes, options.abortSignal);
2143
+ return { buffer, metadata };
2122
2144
  }
2123
2145
  /**
2124
2146
  * Deletes an object. Idempotent: a missing object is a no-op (logged as a
@@ -1297,6 +1297,10 @@ var SourceIdleError = class extends Error {
1297
1297
  }
1298
1298
  idleMs;
1299
1299
  };
1300
+ function isError(value) {
1301
+ const candidate = value;
1302
+ return typeof candidate?.name === "string" && typeof candidate.message === "string";
1303
+ }
1300
1304
  function withinIdleTime(next, idleMs) {
1301
1305
  return new Promise((resolve, reject) => {
1302
1306
  const timer = setTimeout(() => {
@@ -1309,7 +1313,7 @@ function withinIdleTime(next, idleMs) {
1309
1313
  },
1310
1314
  (error) => {
1311
1315
  clearTimeout(timer);
1312
- reject(error instanceof Error ? error : new Error(describeError(error)));
1316
+ reject(isError(error) ? error : new Error(describeError(error)));
1313
1317
  }
1314
1318
  );
1315
1319
  });
@@ -1713,9 +1717,15 @@ function guardDownloadBody(body, idleMs, context, signal) {
1713
1717
  idleMs: error.idleMs
1714
1718
  });
1715
1719
  }
1716
- return signal?.aborted ? requestAborted(signal, context) : error;
1720
+ return signal?.aborted ? requestAborted(signal, context) : mapAwsError(error, context);
1717
1721
  });
1718
1722
  }
1723
+ function mapBodyReadFailure(err, signal, context) {
1724
+ if (err instanceof StorageException) {
1725
+ return err;
1726
+ }
1727
+ return signal?.aborted ? requestAborted(signal, context) : mapAwsError(err, context);
1728
+ }
1719
1729
 
1720
1730
  // src/server/utils/public-url.ts
1721
1731
  function buildPublicUrl(options, finalKey, bucket) {
@@ -1805,7 +1815,7 @@ function assertMaxBytes(maxBytes) {
1805
1815
  });
1806
1816
  }
1807
1817
  }
1808
- async function readDownloadBody(stream, metadata, maxBytes) {
1818
+ async function readBody(stream, metadata, maxBytes) {
1809
1819
  if (maxBytes === void 0) {
1810
1820
  return readStream(stream);
1811
1821
  }
@@ -1820,6 +1830,17 @@ async function readDownloadBody(stream, metadata, maxBytes) {
1820
1830
  }
1821
1831
  return buffer;
1822
1832
  }
1833
+ async function readDownloadBody(stream, metadata, maxBytes, signal) {
1834
+ try {
1835
+ return await readBody(stream, metadata, maxBytes);
1836
+ } catch (err) {
1837
+ throw mapBodyReadFailure(err, signal, {
1838
+ key: metadata.key,
1839
+ bucket: metadata.bucket,
1840
+ op: "downloadBuffer"
1841
+ });
1842
+ }
1843
+ }
1823
1844
 
1824
1845
  // src/server/services/storage.service.ts
1825
1846
  var MAX_LIST_KEYS = 1e3;
@@ -2093,7 +2114,7 @@ var StorageService = class {
2093
2114
  const stream = guardDownloadBody(
2094
2115
  response.Body,
2095
2116
  this.options.bodyIdleTimeoutMs,
2096
- { key: finalKey, bucket },
2117
+ context,
2097
2118
  options.abortSignal
2098
2119
  );
2099
2120
  return { stream, metadata: this.toObjectMetadata(response, finalKey, bucket) };
@@ -2116,7 +2137,8 @@ var StorageService = class {
2116
2137
  async downloadBuffer(options) {
2117
2138
  assertMaxBytes(options.maxBytes);
2118
2139
  const { stream, metadata } = await this.download(options);
2119
- return { buffer: await readDownloadBody(stream, metadata, options.maxBytes), metadata };
2140
+ const buffer = await readDownloadBody(stream, metadata, options.maxBytes, options.abortSignal);
2141
+ return { buffer, metadata };
2120
2142
  }
2121
2143
  /**
2122
2144
  * Deletes an object. Idempotent: a missing object is a no-op (logged as a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.1.14",
3
+ "version": "1.1.15",
4
4
  "description": "Provider-agnostic S3-compatible object storage for NestJS. Works with AWS S3, DigitalOcean Spaces, Cloudflare R2, Backblaze B2, MinIO, Wasabi.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",