@bymax-one/nest-storage 1.1.5 → 1.1.6

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,29 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.6] - 2026-11-06
17
+
18
+ ### Fixed
19
+
20
+ - **A failed scan cleanup now names the provider's cause and the key as stored, and a failed abort no
21
+ longer says the upload was aborted.** The 1.1.5 failure reports were too thin to act on:
22
+ - `details.cleanupError` of a rejected post-upload scan whose delete failed was the generic
23
+ "Storage Exception", which lost the provider's message. It is now the error code and the
24
+ provider's message, for example `STORAGE_PROVIDER_ERROR: Access Denied`.
25
+ - `details.key` and the `STORAGE_SCAN_CLEANUP_FAILED` log line named the key you passed, not the
26
+ key under the `keyPrefix`. The details now also carry `storedKey`, the key as the provider
27
+ holds it, and the log line names it; an operator audits by listing the bucket.
28
+ - `STORAGE_MULTIPART_ABORTED` carried the message "Multipart upload was aborted" even when
29
+ `details.abort` was `'failed'`. In that case the message is now "Multipart upload failed and
30
+ could not be aborted".
31
+
32
+ **Apply to a derived backend:** code that matches `details.cleanupError` against the old generic
33
+ text, or the multipart message against "Multipart upload was aborted" when the abort failed, no
34
+ longer matches; read `details.cleanup`, `details.abort` and the error code instead. Log queries for
35
+ `STORAGE_SCAN_CLEANUP_FAILED` now see the key with its `keyPrefix`. `details.storedKey` is new.
36
+ `StorageException` gains an optional fourth constructor parameter, `message`, which replaces the
37
+ default message of the code; existing calls are unchanged.
38
+
16
39
  ## [1.1.5] - 2026-11-01
17
40
 
18
41
  ### Fixed
@@ -554,4 +577,5 @@ have regressed from. They are kept because the reasoning is worth having.
554
577
  [1.1.3]: https://github.com/bymaxone/nest-storage/compare/v1.1.2...v1.1.3
555
578
  [1.1.4]: https://github.com/bymaxone/nest-storage/compare/v1.1.3...v1.1.4
556
579
  [1.1.5]: https://github.com/bymaxone/nest-storage/compare/v1.1.4...v1.1.5
557
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.5...HEAD
580
+ [1.1.6]: https://github.com/bymaxone/nest-storage/compare/v1.1.5...v1.1.6
581
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.6...HEAD
package/README.md CHANGED
@@ -580,10 +580,12 @@ mode are not affected; `post-upload` hands the scanner no body, only the key.
580
580
  **A rejected object that could not be removed.** In `post-upload` mode the object is already
581
581
  stored when the scanner rejects it, so the library deletes it and rejects `upload()` with the
582
582
  verdict (`STORAGE_SCAN_INFECTED` or `STORAGE_SCAN_INCONCLUSIVE`). When that delete fails, the
583
- verdict is still the error, and `details` says so: `cleanup: 'failed'`, the `key` and the delete
584
- failure in `cleanupError`; the failure is also logged at error level with the code
585
- `STORAGE_SCAN_CLEANUP_FAILED`. No `details.cleanup` means the object was removed; `cleanup:
586
- 'failed'` means it is **still stored** and has to be removed by other means.
583
+ verdict is still the error, and `details` says so: `cleanup: 'failed'`, the `key` you passed, the
584
+ `storedKey` (the key as the provider holds it, with any `keyPrefix`, which is what a bucket listing
585
+ shows) and the delete failure in `cleanupError` (the error code and the provider's message); the
586
+ failure is also logged at error level with the code `STORAGE_SCAN_CLEANUP_FAILED` and the stored
587
+ key. No `details.cleanup` means the object was removed; `cleanup: 'failed'` means it is **still
588
+ stored** and has to be removed by other means.
587
589
 
588
590
  ---
589
591
 
@@ -758,7 +760,7 @@ All errors are thrown as `StorageException extends HttpException`. The response
758
760
  | `STORAGE_PART_TOO_SMALL` | 400 | Reserved: a `multipart.partSizeBytes` below 5 MiB is rejected at init as `STORAGE_INVALID_CONFIG` |
759
761
  | `STORAGE_INVALID_PART_COUNT` | 400 | `getMultipartUploadUrls()` with `parts` not an integer from 1 to 10 000 (`details.provided`, `details.reason`) |
760
762
  | `STORAGE_BUCKET_UNDEFINED` | 400 | Operation without a bucket and no default in config |
761
- | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed. `details.abort` is `'completed'` when the library aborted it and `'failed'` (with `abortError`) when the abort itself failed: that upload stays open on the provider until a lifecycle rule removes it |
763
+ | `STORAGE_MULTIPART_ABORTED` | 500 | A multipart upload failed. `details.abort` is `'completed'` when the library aborted it and `'failed'` (with `abortError`) when the abort itself failed (the message then reads "Multipart upload failed and could not be aborted"): that upload stays open on the provider until a lifecycle rule removes it |
762
764
  | `STORAGE_INVALID_CONFIG` | 500 | `BymaxStorageModuleOptions` validation failed at initialization |
763
765
  | `STORAGE_TIMEOUT` | 504 | An attempt got no response headers within `requestTimeoutMs` (the SDK's `TimeoutError`); a multipart source that stays silent for `uploadIdleTimeoutMs` also surfaces as `STORAGE_TIMEOUT` (`details.phase: 'source-idle'`); any other failure inside a multipart upload surfaces as `STORAGE_MULTIPART_ABORTED` |
764
766
  | `STORAGE_LIFECYCLE_RULE_INVALID` | 400 | `BucketLifecycleService` input rejected: empty or over-long `id`, non-positive or non-integer `expirationDays`, bad `prefix`, or an id naming a rule outside `keyPrefix` (`details.reason`) |
@@ -117,12 +117,12 @@ var STORAGE_ERROR_STATUS = {
117
117
  // src/server/errors/storage-exception.ts
118
118
  var StorageException = class extends common.HttpException {
119
119
  code;
120
- constructor(code, statusCode = STORAGE_ERROR_STATUS[code], details) {
120
+ constructor(code, statusCode = STORAGE_ERROR_STATUS[code], details, message = STORAGE_ERROR_MESSAGES[code]) {
121
121
  super(
122
122
  {
123
123
  error: {
124
124
  code,
125
- message: STORAGE_ERROR_MESSAGES[code],
125
+ message,
126
126
  ...details ? { details } : {}
127
127
  }
128
128
  },
@@ -1091,6 +1091,7 @@ function guardIdleBody(body, idleMs) {
1091
1091
  }
1092
1092
 
1093
1093
  // src/server/errors/multipart-error-mapper.ts
1094
+ var ABORT_FAILED_MESSAGE = "Multipart upload failed and could not be aborted";
1094
1095
  function mapMultipartError(err, context) {
1095
1096
  if (err instanceof SourceIdleError) {
1096
1097
  return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, common.HttpStatus.GATEWAY_TIMEOUT, {
@@ -1103,25 +1104,37 @@ function mapMultipartError(err, context) {
1103
1104
  if (bucketMissing.code === STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND) {
1104
1105
  return bucketMissing;
1105
1106
  }
1106
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED, void 0, {
1107
- ...context,
1108
- awsMessage: describeError(err)
1109
- });
1107
+ return new StorageException(
1108
+ STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED,
1109
+ void 0,
1110
+ { ...context, awsMessage: describeError(err) },
1111
+ // The code's message says the upload was aborted; it is not, when the abort itself failed.
1112
+ context.abort === "failed" ? ABORT_FAILED_MESSAGE : void 0
1113
+ );
1110
1114
  }
1111
1115
  function knownStatus(error) {
1112
1116
  const name = common.HttpStatus[error.getStatus()];
1113
1117
  return name === void 0 ? void 0 : common.HttpStatus[name];
1114
1118
  }
1115
- function withCleanupFailure(scanError, key, cleanupError) {
1119
+ function describeCleanupError(error) {
1120
+ if (!(error instanceof StorageException)) {
1121
+ return describeError(error);
1122
+ }
1123
+ const body = error.getResponse();
1124
+ const awsMessage = body.error?.details?.awsMessage;
1125
+ return typeof awsMessage === "string" ? `${error.code}: ${awsMessage}` : error.code;
1126
+ }
1127
+ function withCleanupFailure(scanError, keys, cleanupError) {
1116
1128
  if (!(scanError instanceof StorageException)) {
1117
1129
  return scanError;
1118
1130
  }
1119
1131
  const body = scanError.getResponse();
1120
1132
  return new StorageException(scanError.code, knownStatus(scanError), {
1121
1133
  ...body.error?.details ?? {},
1122
- key,
1134
+ key: keys.key,
1135
+ storedKey: keys.storedKey,
1123
1136
  cleanup: "failed",
1124
- cleanupError: describeError(cleanupError)
1137
+ cleanupError: describeCleanupError(cleanupError)
1125
1138
  });
1126
1139
  }
1127
1140
  async function closeMultipartUpload(client, bucket, key, uploadId) {
@@ -1418,10 +1431,10 @@ exports.StorageService = class StorageService {
1418
1431
  await this.delete(key, { bucket });
1419
1432
  } catch (deleteErr) {
1420
1433
  this.logger.error(
1421
- `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${key}`,
1434
+ `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${finalKey}`,
1422
1435
  describeError(deleteErr)
1423
1436
  );
1424
- throw withCleanupFailure(scanErr, key, deleteErr);
1437
+ throw withCleanupFailure(scanErr, { key, storedKey: finalKey }, deleteErr);
1425
1438
  }
1426
1439
  throw scanErr;
1427
1440
  }
@@ -1395,7 +1395,9 @@ declare class StorageException extends HttpException {
1395
1395
  readonly code: StorageErrorCode;
1396
1396
  constructor(code: StorageErrorCode,
1397
1397
  /** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
1398
- statusCode?: HttpStatus, details?: Record<string, unknown>);
1398
+ statusCode?: HttpStatus, details?: Record<string, unknown>,
1399
+ /** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
1400
+ message?: string);
1399
1401
  }
1400
1402
 
1401
1403
  export { type AbortMultipartRuleInput, BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, type BucketLifecycleRule, type BucketLifecycleRuleView, BucketLifecycleService, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type ExpirationRuleInput, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type LifecycleBucketOptions, type LifecycleRuleInput, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
@@ -1395,7 +1395,9 @@ declare class StorageException extends HttpException {
1395
1395
  readonly code: StorageErrorCode;
1396
1396
  constructor(code: StorageErrorCode,
1397
1397
  /** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
1398
- statusCode?: HttpStatus, details?: Record<string, unknown>);
1398
+ statusCode?: HttpStatus, details?: Record<string, unknown>,
1399
+ /** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
1400
+ message?: string);
1399
1401
  }
1400
1402
 
1401
1403
  export { type AbortMultipartRuleInput, BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, type BucketLifecycleRule, type BucketLifecycleRuleView, BucketLifecycleService, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type ExpirationRuleInput, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type LifecycleBucketOptions, type LifecycleRuleInput, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
@@ -115,12 +115,12 @@ var STORAGE_ERROR_STATUS = {
115
115
  // src/server/errors/storage-exception.ts
116
116
  var StorageException = class extends HttpException {
117
117
  code;
118
- constructor(code, statusCode = STORAGE_ERROR_STATUS[code], details) {
118
+ constructor(code, statusCode = STORAGE_ERROR_STATUS[code], details, message = STORAGE_ERROR_MESSAGES[code]) {
119
119
  super(
120
120
  {
121
121
  error: {
122
122
  code,
123
- message: STORAGE_ERROR_MESSAGES[code],
123
+ message,
124
124
  ...details ? { details } : {}
125
125
  }
126
126
  },
@@ -1089,6 +1089,7 @@ function guardIdleBody(body, idleMs) {
1089
1089
  }
1090
1090
 
1091
1091
  // src/server/errors/multipart-error-mapper.ts
1092
+ var ABORT_FAILED_MESSAGE = "Multipart upload failed and could not be aborted";
1092
1093
  function mapMultipartError(err, context) {
1093
1094
  if (err instanceof SourceIdleError) {
1094
1095
  return new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, HttpStatus.GATEWAY_TIMEOUT, {
@@ -1101,25 +1102,37 @@ function mapMultipartError(err, context) {
1101
1102
  if (bucketMissing.code === STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND) {
1102
1103
  return bucketMissing;
1103
1104
  }
1104
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED, void 0, {
1105
- ...context,
1106
- awsMessage: describeError(err)
1107
- });
1105
+ return new StorageException(
1106
+ STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED,
1107
+ void 0,
1108
+ { ...context, awsMessage: describeError(err) },
1109
+ // The code's message says the upload was aborted; it is not, when the abort itself failed.
1110
+ context.abort === "failed" ? ABORT_FAILED_MESSAGE : void 0
1111
+ );
1108
1112
  }
1109
1113
  function knownStatus(error) {
1110
1114
  const name = HttpStatus[error.getStatus()];
1111
1115
  return name === void 0 ? void 0 : HttpStatus[name];
1112
1116
  }
1113
- function withCleanupFailure(scanError, key, cleanupError) {
1117
+ function describeCleanupError(error) {
1118
+ if (!(error instanceof StorageException)) {
1119
+ return describeError(error);
1120
+ }
1121
+ const body = error.getResponse();
1122
+ const awsMessage = body.error?.details?.awsMessage;
1123
+ return typeof awsMessage === "string" ? `${error.code}: ${awsMessage}` : error.code;
1124
+ }
1125
+ function withCleanupFailure(scanError, keys, cleanupError) {
1114
1126
  if (!(scanError instanceof StorageException)) {
1115
1127
  return scanError;
1116
1128
  }
1117
1129
  const body = scanError.getResponse();
1118
1130
  return new StorageException(scanError.code, knownStatus(scanError), {
1119
1131
  ...body.error?.details ?? {},
1120
- key,
1132
+ key: keys.key,
1133
+ storedKey: keys.storedKey,
1121
1134
  cleanup: "failed",
1122
- cleanupError: describeError(cleanupError)
1135
+ cleanupError: describeCleanupError(cleanupError)
1123
1136
  });
1124
1137
  }
1125
1138
  async function closeMultipartUpload(client, bucket, key, uploadId) {
@@ -1416,10 +1429,10 @@ var StorageService = class {
1416
1429
  await this.delete(key, { bucket });
1417
1430
  } catch (deleteErr) {
1418
1431
  this.logger.error(
1419
- `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${key}`,
1432
+ `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${finalKey}`,
1420
1433
  describeError(deleteErr)
1421
1434
  );
1422
- throw withCleanupFailure(scanErr, key, deleteErr);
1435
+ throw withCleanupFailure(scanErr, { key, storedKey: finalKey }, deleteErr);
1423
1436
  }
1424
1437
  throw scanErr;
1425
1438
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.1.5",
3
+ "version": "1.1.6",
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",