@bymax-one/nest-storage 1.1.3 → 1.1.4

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,31 @@ note on each entry is the compatibility contract — read it, not the number.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [1.1.4] - 2026-11-01
17
+
18
+ ### Changed
19
+
20
+ - **A missing bucket is no longer reported as an absent object, and `delete()` no longer hides it.** When
21
+ the provider answers `NoSuchBucket`, `download()`, `upload()`, `list()`, `copy()` and `delete()` now
22
+ reject with the new `STORAGE_BUCKET_NOT_FOUND` (404) instead of `STORAGE_OBJECT_NOT_FOUND`, and
23
+ `delete()`, which used to resolve successfully against a bucket that does not exist, rejects it.
24
+
25
+ **Apply to a derived backend:** a behaviour change for a deployment whose bucket is missing or
26
+ misnamed. Code that treated `STORAGE_OBJECT_NOT_FOUND` after a failed `download()`, `upload()`, `list()`
27
+ or `copy()` as "the bucket or key is not there" must also handle `STORAGE_BUCKET_NOT_FOUND`, and a
28
+ `delete()` that used to succeed silently now fails until the bucket exists. `head()` and `exists()` are
29
+ unchanged: a `HEAD` response has no body, so the provider cannot say which of the bucket and the key is
30
+ missing, and a missing bucket still reads as an absent object there (use `checkBucket()` to tell).
31
+
32
+ ### Added
33
+
34
+ - **`StorageService.checkBucket()`.** One `HeadBucket` that resolves when the bucket is reachable with these
35
+ credentials and otherwise rejects with a typed code: `STORAGE_BUCKET_NOT_FOUND` (404),
36
+ `STORAGE_BUCKET_ACCESS_DENIED` (403, which a provider also answers for a bucket the caller cannot list),
37
+ `STORAGE_BUCKET_REGION_MISMATCH` (301 or `PermanentRedirect`), `STORAGE_TIMEOUT`, or
38
+ `STORAGE_PROVIDER_ERROR`. Nothing calls it at boot; wire it into a readiness endpoint so a misconfigured
39
+ bucket keeps the instance out of rotation. It needs `s3:ListBucket`.
40
+
16
41
  ## [1.1.3] - 2026-11-01
17
42
 
18
43
  ### Fixed
@@ -481,4 +506,5 @@ have regressed from. They are kept because the reasoning is worth having.
481
506
  [1.1.1]: https://github.com/bymaxone/nest-storage/compare/v1.1.0...v1.1.1
482
507
  [1.1.2]: https://github.com/bymaxone/nest-storage/compare/v1.1.1...v1.1.2
483
508
  [1.1.3]: https://github.com/bymaxone/nest-storage/compare/v1.1.2...v1.1.3
484
- [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.3...HEAD
509
+ [1.1.4]: https://github.com/bymaxone/nest-storage/compare/v1.1.3...v1.1.4
510
+ [Unreleased]: https://github.com/bymaxone/nest-storage/compare/v1.1.4...HEAD
package/README.md CHANGED
@@ -285,6 +285,7 @@ The full configuration reference lives in `docs/technical_specification.md` §4.
285
285
 
286
286
  [aws-presigned-expiry]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
287
287
  [aws-get-object]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html
288
+ [aws-head-object]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html
288
289
  [aws-mpu-limits]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html
289
290
  [aws-mpu-abort-rule]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-abort-incomplete-mpu-lifecycle-config.html
290
291
  [sdk-request-timeout]: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-maxsockets.html
@@ -749,6 +750,9 @@ All errors are thrown as `StorageException extends HttpException`. The response
749
750
  | `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`) |
750
751
  | `STORAGE_LIFECYCLE_UNSUPPORTED` | 501 | The provider does not implement the lifecycle API |
751
752
  | `STORAGE_LIFECYCLE_REJECTED` | 422 | The provider refused the lifecycle configuration |
753
+ | `STORAGE_BUCKET_NOT_FOUND` | 404 | The provider answered `NoSuchBucket` (any operation that gets an error body: `download()`, `upload()`, `list()`, `copy()`, `delete()`), or `checkBucket()` got a 404 |
754
+ | `STORAGE_BUCKET_ACCESS_DENIED` | 403 | `checkBucket()` got a 403: the credentials cannot use the bucket, or it does not exist and the credentials cannot list (S3 answers 403 to a caller without `s3:ListBucket`) |
755
+ | `STORAGE_BUCKET_REGION_MISMATCH` | 500 | `checkBucket()` got a 301 or `PermanentRedirect`: the bucket lives in another region than the configured one |
752
756
  | `STORAGE_NOT_MODIFIED` | 304 | `download()` with `ifNoneMatch` equal to the current ETag |
753
757
  | `STORAGE_PRECONDITION_FAILED` | 412 | `download()` with `ifMatch` different from the current ETag |
754
758
 
@@ -782,10 +786,13 @@ This is the index.
782
786
  | `head` | `(key, options?) => Promise<ObjectMetadata>` | Metadata without transferring the body |
783
787
  | `exists` | `(key, options?) => Promise<boolean>` | `head` reduced to a boolean; any non-404 failure is logged and returns `false` |
784
788
  | `getPublicUrl` | `(key, options?) => string` | Composed, not signed — for buckets that are public by policy |
785
- | `delete` | `(key, options?) => Promise<void>` | Idempotent, as S3 delete is |
789
+ | `delete` | `(key, options?) => Promise<void>` | Idempotent for a missing object, as S3 delete is; a missing bucket rejects `STORAGE_BUCKET_NOT_FOUND` |
786
790
  | `deleteMany` | `(keys: string[], options?) => Promise<DeleteManyResult>` | Partial failures are reported, not thrown |
787
791
  | `list` | `(options: ListOptions) => Promise<ListResult>` | Paginated by continuation token |
788
792
  | `copy` | `(options: CopyOptions) => Promise<{ etag }>` | Server-side; the bytes never reach this process |
793
+ | `checkBucket` | `(options?) => Promise<void>` | One `HeadBucket` for a readiness check; resolves when the bucket is reachable, otherwise rejects `STORAGE_BUCKET_NOT_FOUND`, `STORAGE_BUCKET_ACCESS_DENIED`, `STORAGE_BUCKET_REGION_MISMATCH` or `STORAGE_TIMEOUT`; needs `s3:ListBucket`; never called at boot |
794
+
795
+ **A missing bucket and `head()` / `exists()`.** A `HEAD` response has no body, so the provider cannot say which of the bucket and the key is missing: AWS documents that "if the `HEAD` request generates an error, it returns a generic code, such as `400 Bad Request`, `403 Forbidden`, `404 Not Found` ... It's not possible to retrieve the exact exception of these error codes" ([HeadObject][aws-head-object]). `head()` therefore rejects `STORAGE_OBJECT_NOT_FOUND` and `exists()` returns `false` for a missing bucket too. Call `checkBucket()` to tell the two apart, for example from a readiness endpoint.
789
796
 
790
797
  ### `SignedUrlService`
791
798
 
@@ -50,7 +50,10 @@ var STORAGE_ERROR_CODES = {
50
50
  STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED",
51
51
  STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED",
52
52
  STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED",
53
- STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED"
53
+ STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED",
54
+ STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND",
55
+ STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED",
56
+ STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH"
54
57
  };
55
58
 
56
59
  // src/server/errors/storage-error-messages.ts
@@ -77,7 +80,10 @@ var STORAGE_ERROR_MESSAGES = {
77
80
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: "The storage provider does not support bucket lifecycle configuration",
78
81
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: "The storage provider rejected the lifecycle configuration",
79
82
  [STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED]: "The object has not changed since the supplied ETag",
80
- [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: "The object does not satisfy the supplied precondition"
83
+ [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: "The object does not satisfy the supplied precondition",
84
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND]: "The bucket does not exist",
85
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED]: "The bucket cannot be accessed with these credentials (it may also not exist)",
86
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: "The bucket belongs to a different region than the configured one"
81
87
  };
82
88
  var STORAGE_ERROR_STATUS = {
83
89
  [STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED]: common.HttpStatus.SERVICE_UNAVAILABLE,
@@ -102,7 +108,10 @@ var STORAGE_ERROR_STATUS = {
102
108
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: common.HttpStatus.NOT_IMPLEMENTED,
103
109
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: common.HttpStatus.UNPROCESSABLE_ENTITY,
104
110
  [STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED]: common.HttpStatus.NOT_MODIFIED,
105
- [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: common.HttpStatus.PRECONDITION_FAILED
111
+ [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: common.HttpStatus.PRECONDITION_FAILED,
112
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND]: common.HttpStatus.NOT_FOUND,
113
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED]: common.HttpStatus.FORBIDDEN,
114
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: common.HttpStatus.INTERNAL_SERVER_ERROR
106
115
  };
107
116
 
108
117
  // src/server/errors/storage-exception.ts
@@ -415,6 +424,13 @@ function mapAwsError(err, context) {
415
424
  requestId,
416
425
  awsMessage: e.message
417
426
  };
427
+ if (awsCode === "NoSuchBucket") {
428
+ return new StorageException(
429
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND,
430
+ common.HttpStatus.NOT_FOUND,
431
+ details
432
+ );
433
+ }
418
434
  if (e.name === "NotFound" || httpStatus === 404) {
419
435
  return new StorageException(
420
436
  STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND,
@@ -1083,11 +1099,63 @@ function mapMultipartError(err, context) {
1083
1099
  idleMs: err.idleMs
1084
1100
  });
1085
1101
  }
1102
+ const bucketMissing = mapAwsError(err, context);
1103
+ if (bucketMissing.code === STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND) {
1104
+ return bucketMissing;
1105
+ }
1086
1106
  return new StorageException(STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED, void 0, {
1087
1107
  ...context,
1088
1108
  awsMessage: describeError(err)
1089
1109
  });
1090
1110
  }
1111
+ function mapBucketCheckError(err, context) {
1112
+ const failure = err ?? {};
1113
+ const status = failure.$metadata?.httpStatusCode;
1114
+ const details = { ...context, httpStatus: status, awsCode: failure.name };
1115
+ if (status === 301 || failure.name === "PermanentRedirect") {
1116
+ return new StorageException(
1117
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH,
1118
+ void 0,
1119
+ details
1120
+ );
1121
+ }
1122
+ if (status === 403) {
1123
+ return new StorageException(
1124
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED,
1125
+ void 0,
1126
+ details
1127
+ );
1128
+ }
1129
+ if (status === 404) {
1130
+ return new StorageException(
1131
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND,
1132
+ common.HttpStatus.NOT_FOUND,
1133
+ details
1134
+ );
1135
+ }
1136
+ return mapAwsError(err, context);
1137
+ }
1138
+
1139
+ // src/server/utils/list-result.ts
1140
+ function toListedObject(obj, stripPrefix) {
1141
+ return {
1142
+ key: stripPrefix(obj.Key ?? ""),
1143
+ size: obj.Size ?? 0,
1144
+ etag: obj.ETag ?? "",
1145
+ lastModified: obj.LastModified ?? /* @__PURE__ */ new Date(0),
1146
+ ...obj.StorageClass !== void 0 ? { storageClass: obj.StorageClass } : {}
1147
+ };
1148
+ }
1149
+ function toListResult(response, stripPrefix) {
1150
+ const objects = (response.Contents ?? []).map((obj) => toListedObject(obj, stripPrefix));
1151
+ const commonPrefixes = (response.CommonPrefixes ?? []).map((cp) => cp.Prefix ?? "").filter((cp) => cp.length > 0).map((cp) => stripPrefix(cp));
1152
+ return {
1153
+ objects,
1154
+ commonPrefixes,
1155
+ isTruncated: response.IsTruncated ?? false,
1156
+ ...response.NextContinuationToken !== void 0 ? { nextContinuationToken: response.NextContinuationToken } : {}
1157
+ };
1158
+ }
1091
1159
 
1092
1160
  // src/server/utils/header-utils.ts
1093
1161
  function buildContentDisposition(perCall, defaultValue) {
@@ -1414,6 +1482,26 @@ exports.StorageService = class StorageService {
1414
1482
  throw mapped;
1415
1483
  }
1416
1484
  }
1485
+ /**
1486
+ * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
1487
+ * is reachable with these credentials and otherwise rejects with a typed code. Nothing in the
1488
+ * module calls it on its own, so booting costs no request. Needs `s3:ListBucket`.
1489
+ *
1490
+ * @param options - Optional per-call bucket override.
1491
+ * @throws StorageException `STORAGE_BUCKET_NOT_FOUND` (404), `STORAGE_BUCKET_ACCESS_DENIED` (403,
1492
+ * which a provider also answers for a bucket the caller cannot see), `STORAGE_BUCKET_REGION_MISMATCH`
1493
+ * (301), `STORAGE_TIMEOUT`, or `STORAGE_PROVIDER_ERROR`; `STORAGE_NOT_CONFIGURED` and
1494
+ * `STORAGE_BUCKET_UNDEFINED` before any request.
1495
+ */
1496
+ async checkBucket(options) {
1497
+ this.assertConfigured();
1498
+ const bucket = this.resolveBucket(options?.bucket);
1499
+ try {
1500
+ await this.s3Provider.getClient().send(new clientS3.HeadBucketCommand({ Bucket: bucket }));
1501
+ } catch (err) {
1502
+ throw mapBucketCheckError(err, { bucket, op: "checkBucket" });
1503
+ }
1504
+ }
1417
1505
  /** Throws when the S3 client was never built (missing credentials). */
1418
1506
  assertConfigured() {
1419
1507
  if (!this.s3Provider.isConfigured()) {
@@ -1601,32 +1689,11 @@ exports.StorageService = class StorageService {
1601
1689
  Delimiter: options.delimiter
1602
1690
  })
1603
1691
  );
1604
- return this.toListResult(response);
1692
+ return toListResult(response, (key) => this.keyResolver.stripPrefix(key));
1605
1693
  } catch (err) {
1606
1694
  throw mapAwsError(err, { bucket, prefix, op: "list" });
1607
1695
  }
1608
1696
  }
1609
- /** Maps a `ListObjectsV2` response onto the public `ListResult` shape. */
1610
- toListResult(response) {
1611
- const objects = (response.Contents ?? []).map((obj) => this.toListedObject(obj));
1612
- const commonPrefixes = (response.CommonPrefixes ?? []).map((cp) => cp.Prefix ?? "").filter((cp) => cp.length > 0).map((cp) => this.keyResolver.stripPrefix(cp));
1613
- return {
1614
- objects,
1615
- commonPrefixes,
1616
- isTruncated: response.IsTruncated ?? false,
1617
- ...response.NextContinuationToken !== void 0 ? { nextContinuationToken: response.NextContinuationToken } : {}
1618
- };
1619
- }
1620
- /** Maps one `Contents` entry onto `ListedObject`, stripping the global prefix. */
1621
- toListedObject(obj) {
1622
- return {
1623
- key: this.keyResolver.stripPrefix(obj.Key ?? ""),
1624
- size: obj.Size ?? 0,
1625
- etag: obj.ETag ?? "",
1626
- lastModified: obj.LastModified ?? /* @__PURE__ */ new Date(0),
1627
- ...obj.StorageClass !== void 0 ? { storageClass: obj.StorageClass } : {}
1628
- };
1629
- }
1630
1697
  /**
1631
1698
  * Server-side copy of an object (no bytes flow through the app). Supports both
1632
1699
  * same-bucket and cross-bucket copies and preserves the source metadata.
@@ -812,6 +812,18 @@ declare class StorageService {
812
812
  * @param options - Optional per-call bucket override.
813
813
  */
814
814
  delete(key: string, options?: BucketScopedOptions): Promise<void>;
815
+ /**
816
+ * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
817
+ * is reachable with these credentials and otherwise rejects with a typed code. Nothing in the
818
+ * module calls it on its own, so booting costs no request. Needs `s3:ListBucket`.
819
+ *
820
+ * @param options - Optional per-call bucket override.
821
+ * @throws StorageException `STORAGE_BUCKET_NOT_FOUND` (404), `STORAGE_BUCKET_ACCESS_DENIED` (403,
822
+ * which a provider also answers for a bucket the caller cannot see), `STORAGE_BUCKET_REGION_MISMATCH`
823
+ * (301), `STORAGE_TIMEOUT`, or `STORAGE_PROVIDER_ERROR`; `STORAGE_NOT_CONFIGURED` and
824
+ * `STORAGE_BUCKET_UNDEFINED` before any request.
825
+ */
826
+ checkBucket(options?: BucketScopedOptions): Promise<void>;
815
827
  /** Throws when the S3 client was never built (missing credentials). */
816
828
  private assertConfigured;
817
829
  /** Resolves the target bucket from a per-call override or the module default. */
@@ -850,10 +862,6 @@ declare class StorageService {
850
862
  * @throws StorageException mapped from any AWS failure.
851
863
  */
852
864
  list(options: ListOptions): Promise<ListResult>;
853
- /** Maps a `ListObjectsV2` response onto the public `ListResult` shape. */
854
- private toListResult;
855
- /** Maps one `Contents` entry onto `ListedObject`, stripping the global prefix. */
856
- private toListedObject;
857
865
  /**
858
866
  * Server-side copy of an object (no bytes flow through the app). Supports both
859
867
  * same-bucket and cross-bucket copies and preserves the source metadata.
@@ -1349,6 +1357,9 @@ declare const STORAGE_ERROR_CODES: {
1349
1357
  readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
1350
1358
  readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
1351
1359
  readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
1360
+ readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
1361
+ readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
1362
+ readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
1352
1363
  };
1353
1364
  /** Union of every stable storage error code. */
1354
1365
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -812,6 +812,18 @@ declare class StorageService {
812
812
  * @param options - Optional per-call bucket override.
813
813
  */
814
814
  delete(key: string, options?: BucketScopedOptions): Promise<void>;
815
+ /**
816
+ * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
817
+ * is reachable with these credentials and otherwise rejects with a typed code. Nothing in the
818
+ * module calls it on its own, so booting costs no request. Needs `s3:ListBucket`.
819
+ *
820
+ * @param options - Optional per-call bucket override.
821
+ * @throws StorageException `STORAGE_BUCKET_NOT_FOUND` (404), `STORAGE_BUCKET_ACCESS_DENIED` (403,
822
+ * which a provider also answers for a bucket the caller cannot see), `STORAGE_BUCKET_REGION_MISMATCH`
823
+ * (301), `STORAGE_TIMEOUT`, or `STORAGE_PROVIDER_ERROR`; `STORAGE_NOT_CONFIGURED` and
824
+ * `STORAGE_BUCKET_UNDEFINED` before any request.
825
+ */
826
+ checkBucket(options?: BucketScopedOptions): Promise<void>;
815
827
  /** Throws when the S3 client was never built (missing credentials). */
816
828
  private assertConfigured;
817
829
  /** Resolves the target bucket from a per-call override or the module default. */
@@ -850,10 +862,6 @@ declare class StorageService {
850
862
  * @throws StorageException mapped from any AWS failure.
851
863
  */
852
864
  list(options: ListOptions): Promise<ListResult>;
853
- /** Maps a `ListObjectsV2` response onto the public `ListResult` shape. */
854
- private toListResult;
855
- /** Maps one `Contents` entry onto `ListedObject`, stripping the global prefix. */
856
- private toListedObject;
857
865
  /**
858
866
  * Server-side copy of an object (no bytes flow through the app). Supports both
859
867
  * same-bucket and cross-bucket copies and preserves the source metadata.
@@ -1349,6 +1357,9 @@ declare const STORAGE_ERROR_CODES: {
1349
1357
  readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
1350
1358
  readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
1351
1359
  readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
1360
+ readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
1361
+ readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
1362
+ readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
1352
1363
  };
1353
1364
  /** Union of every stable storage error code. */
1354
1365
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -1,5 +1,5 @@
1
1
  import { HttpStatus, Injectable, Inject, Global, Module, Logger, HttpException } from '@nestjs/common';
2
- import { S3Client, GetBucketLifecycleConfigurationCommand, DeleteBucketLifecycleCommand, PutBucketLifecycleConfigurationCommand, HeadObjectCommand, GetObjectCommand, DeleteObjectCommand, PutObjectCommand, ListObjectsV2Command, CopyObjectCommand, DeleteObjectsCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand } from '@aws-sdk/client-s3';
2
+ import { S3Client, GetBucketLifecycleConfigurationCommand, DeleteBucketLifecycleCommand, PutBucketLifecycleConfigurationCommand, HeadObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadBucketCommand, PutObjectCommand, ListObjectsV2Command, CopyObjectCommand, DeleteObjectsCommand, CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand } from '@aws-sdk/client-s3';
3
3
  import { Upload } from '@aws-sdk/lib-storage';
4
4
  import { PassThrough, Readable } from 'stream';
5
5
  import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
@@ -48,7 +48,10 @@ var STORAGE_ERROR_CODES = {
48
48
  STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED",
49
49
  STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED",
50
50
  STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED",
51
- STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED"
51
+ STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED",
52
+ STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND",
53
+ STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED",
54
+ STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH"
52
55
  };
53
56
 
54
57
  // src/server/errors/storage-error-messages.ts
@@ -75,7 +78,10 @@ var STORAGE_ERROR_MESSAGES = {
75
78
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: "The storage provider does not support bucket lifecycle configuration",
76
79
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: "The storage provider rejected the lifecycle configuration",
77
80
  [STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED]: "The object has not changed since the supplied ETag",
78
- [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: "The object does not satisfy the supplied precondition"
81
+ [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: "The object does not satisfy the supplied precondition",
82
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND]: "The bucket does not exist",
83
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED]: "The bucket cannot be accessed with these credentials (it may also not exist)",
84
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: "The bucket belongs to a different region than the configured one"
79
85
  };
80
86
  var STORAGE_ERROR_STATUS = {
81
87
  [STORAGE_ERROR_CODES.STORAGE_NOT_CONFIGURED]: HttpStatus.SERVICE_UNAVAILABLE,
@@ -100,7 +106,10 @@ var STORAGE_ERROR_STATUS = {
100
106
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_UNSUPPORTED]: HttpStatus.NOT_IMPLEMENTED,
101
107
  [STORAGE_ERROR_CODES.STORAGE_LIFECYCLE_REJECTED]: HttpStatus.UNPROCESSABLE_ENTITY,
102
108
  [STORAGE_ERROR_CODES.STORAGE_NOT_MODIFIED]: HttpStatus.NOT_MODIFIED,
103
- [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: HttpStatus.PRECONDITION_FAILED
109
+ [STORAGE_ERROR_CODES.STORAGE_PRECONDITION_FAILED]: HttpStatus.PRECONDITION_FAILED,
110
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND]: HttpStatus.NOT_FOUND,
111
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED]: HttpStatus.FORBIDDEN,
112
+ [STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH]: HttpStatus.INTERNAL_SERVER_ERROR
104
113
  };
105
114
 
106
115
  // src/server/errors/storage-exception.ts
@@ -413,6 +422,13 @@ function mapAwsError(err, context) {
413
422
  requestId,
414
423
  awsMessage: e.message
415
424
  };
425
+ if (awsCode === "NoSuchBucket") {
426
+ return new StorageException(
427
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND,
428
+ HttpStatus.NOT_FOUND,
429
+ details
430
+ );
431
+ }
416
432
  if (e.name === "NotFound" || httpStatus === 404) {
417
433
  return new StorageException(
418
434
  STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND,
@@ -1081,11 +1097,63 @@ function mapMultipartError(err, context) {
1081
1097
  idleMs: err.idleMs
1082
1098
  });
1083
1099
  }
1100
+ const bucketMissing = mapAwsError(err, context);
1101
+ if (bucketMissing.code === STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND) {
1102
+ return bucketMissing;
1103
+ }
1084
1104
  return new StorageException(STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED, void 0, {
1085
1105
  ...context,
1086
1106
  awsMessage: describeError(err)
1087
1107
  });
1088
1108
  }
1109
+ function mapBucketCheckError(err, context) {
1110
+ const failure = err ?? {};
1111
+ const status = failure.$metadata?.httpStatusCode;
1112
+ const details = { ...context, httpStatus: status, awsCode: failure.name };
1113
+ if (status === 301 || failure.name === "PermanentRedirect") {
1114
+ return new StorageException(
1115
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_REGION_MISMATCH,
1116
+ void 0,
1117
+ details
1118
+ );
1119
+ }
1120
+ if (status === 403) {
1121
+ return new StorageException(
1122
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_ACCESS_DENIED,
1123
+ void 0,
1124
+ details
1125
+ );
1126
+ }
1127
+ if (status === 404) {
1128
+ return new StorageException(
1129
+ STORAGE_ERROR_CODES.STORAGE_BUCKET_NOT_FOUND,
1130
+ HttpStatus.NOT_FOUND,
1131
+ details
1132
+ );
1133
+ }
1134
+ return mapAwsError(err, context);
1135
+ }
1136
+
1137
+ // src/server/utils/list-result.ts
1138
+ function toListedObject(obj, stripPrefix) {
1139
+ return {
1140
+ key: stripPrefix(obj.Key ?? ""),
1141
+ size: obj.Size ?? 0,
1142
+ etag: obj.ETag ?? "",
1143
+ lastModified: obj.LastModified ?? /* @__PURE__ */ new Date(0),
1144
+ ...obj.StorageClass !== void 0 ? { storageClass: obj.StorageClass } : {}
1145
+ };
1146
+ }
1147
+ function toListResult(response, stripPrefix) {
1148
+ const objects = (response.Contents ?? []).map((obj) => toListedObject(obj, stripPrefix));
1149
+ const commonPrefixes = (response.CommonPrefixes ?? []).map((cp) => cp.Prefix ?? "").filter((cp) => cp.length > 0).map((cp) => stripPrefix(cp));
1150
+ return {
1151
+ objects,
1152
+ commonPrefixes,
1153
+ isTruncated: response.IsTruncated ?? false,
1154
+ ...response.NextContinuationToken !== void 0 ? { nextContinuationToken: response.NextContinuationToken } : {}
1155
+ };
1156
+ }
1089
1157
 
1090
1158
  // src/server/utils/header-utils.ts
1091
1159
  function buildContentDisposition(perCall, defaultValue) {
@@ -1412,6 +1480,26 @@ var StorageService = class {
1412
1480
  throw mapped;
1413
1481
  }
1414
1482
  }
1483
+ /**
1484
+ * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
1485
+ * is reachable with these credentials and otherwise rejects with a typed code. Nothing in the
1486
+ * module calls it on its own, so booting costs no request. Needs `s3:ListBucket`.
1487
+ *
1488
+ * @param options - Optional per-call bucket override.
1489
+ * @throws StorageException `STORAGE_BUCKET_NOT_FOUND` (404), `STORAGE_BUCKET_ACCESS_DENIED` (403,
1490
+ * which a provider also answers for a bucket the caller cannot see), `STORAGE_BUCKET_REGION_MISMATCH`
1491
+ * (301), `STORAGE_TIMEOUT`, or `STORAGE_PROVIDER_ERROR`; `STORAGE_NOT_CONFIGURED` and
1492
+ * `STORAGE_BUCKET_UNDEFINED` before any request.
1493
+ */
1494
+ async checkBucket(options) {
1495
+ this.assertConfigured();
1496
+ const bucket = this.resolveBucket(options?.bucket);
1497
+ try {
1498
+ await this.s3Provider.getClient().send(new HeadBucketCommand({ Bucket: bucket }));
1499
+ } catch (err) {
1500
+ throw mapBucketCheckError(err, { bucket, op: "checkBucket" });
1501
+ }
1502
+ }
1415
1503
  /** Throws when the S3 client was never built (missing credentials). */
1416
1504
  assertConfigured() {
1417
1505
  if (!this.s3Provider.isConfigured()) {
@@ -1599,32 +1687,11 @@ var StorageService = class {
1599
1687
  Delimiter: options.delimiter
1600
1688
  })
1601
1689
  );
1602
- return this.toListResult(response);
1690
+ return toListResult(response, (key) => this.keyResolver.stripPrefix(key));
1603
1691
  } catch (err) {
1604
1692
  throw mapAwsError(err, { bucket, prefix, op: "list" });
1605
1693
  }
1606
1694
  }
1607
- /** Maps a `ListObjectsV2` response onto the public `ListResult` shape. */
1608
- toListResult(response) {
1609
- const objects = (response.Contents ?? []).map((obj) => this.toListedObject(obj));
1610
- const commonPrefixes = (response.CommonPrefixes ?? []).map((cp) => cp.Prefix ?? "").filter((cp) => cp.length > 0).map((cp) => this.keyResolver.stripPrefix(cp));
1611
- return {
1612
- objects,
1613
- commonPrefixes,
1614
- isTruncated: response.IsTruncated ?? false,
1615
- ...response.NextContinuationToken !== void 0 ? { nextContinuationToken: response.NextContinuationToken } : {}
1616
- };
1617
- }
1618
- /** Maps one `Contents` entry onto `ListedObject`, stripping the global prefix. */
1619
- toListedObject(obj) {
1620
- return {
1621
- key: this.keyResolver.stripPrefix(obj.Key ?? ""),
1622
- size: obj.Size ?? 0,
1623
- etag: obj.ETag ?? "",
1624
- lastModified: obj.LastModified ?? /* @__PURE__ */ new Date(0),
1625
- ...obj.StorageClass !== void 0 ? { storageClass: obj.StorageClass } : {}
1626
- };
1627
- }
1628
1695
  /**
1629
1696
  * Server-side copy of an object (no bytes flow through the app). Supports both
1630
1697
  * same-bucket and cross-bucket copies and preserves the source metadata.
@@ -26,7 +26,10 @@ var STORAGE_ERROR_CODES = {
26
26
  STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED",
27
27
  STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED",
28
28
  STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED",
29
- STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED"
29
+ STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED",
30
+ STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND",
31
+ STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED",
32
+ STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH"
30
33
  };
31
34
 
32
35
  // src/shared/constants/mime-types.constants.ts
@@ -95,6 +95,9 @@ declare const STORAGE_ERROR_CODES: {
95
95
  readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
96
96
  readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
97
97
  readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
98
+ readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
99
+ readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
100
+ readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
98
101
  };
99
102
  /** Union of every stable storage error code. */
100
103
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -95,6 +95,9 @@ declare const STORAGE_ERROR_CODES: {
95
95
  readonly STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED";
96
96
  readonly STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED";
97
97
  readonly STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED";
98
+ readonly STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND";
99
+ readonly STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED";
100
+ readonly STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH";
98
101
  };
99
102
  /** Union of every stable storage error code. */
100
103
  type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
@@ -24,7 +24,10 @@ var STORAGE_ERROR_CODES = {
24
24
  STORAGE_LIFECYCLE_UNSUPPORTED: "STORAGE_LIFECYCLE_UNSUPPORTED",
25
25
  STORAGE_LIFECYCLE_REJECTED: "STORAGE_LIFECYCLE_REJECTED",
26
26
  STORAGE_NOT_MODIFIED: "STORAGE_NOT_MODIFIED",
27
- STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED"
27
+ STORAGE_PRECONDITION_FAILED: "STORAGE_PRECONDITION_FAILED",
28
+ STORAGE_BUCKET_NOT_FOUND: "STORAGE_BUCKET_NOT_FOUND",
29
+ STORAGE_BUCKET_ACCESS_DENIED: "STORAGE_BUCKET_ACCESS_DENIED",
30
+ STORAGE_BUCKET_REGION_MISMATCH: "STORAGE_BUCKET_REGION_MISMATCH"
28
31
  };
29
32
 
30
33
  // src/shared/constants/mime-types.constants.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-storage",
3
- "version": "1.1.3",
3
+ "version": "1.1.4",
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",