@venizia/ignis-helpers 0.4.8-9 → 0.4.8

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.
Files changed (199) hide show
  1. package/README.md +2 -3
  2. package/dist/esm/common/constants/app.d.ts +1 -3
  3. package/dist/esm/common/constants/app.js +1 -11
  4. package/dist/esm/common/constants/app.js.map +1 -1
  5. package/dist/esm/common/constants/http.d.ts +2 -0
  6. package/dist/esm/common/constants/http.js +3 -0
  7. package/dist/esm/common/constants/http.js.map +1 -1
  8. package/dist/esm/common/constants/mime.d.ts +0 -2
  9. package/dist/esm/common/constants/mime.js +0 -4
  10. package/dist/esm/common/constants/mime.js.map +1 -1
  11. package/dist/esm/common/redact.js.map +1 -1
  12. package/dist/esm/common/types/class.d.ts +14 -12
  13. package/dist/esm/common/types/class.js.map +1 -1
  14. package/dist/esm/common/types/const-value.d.ts +3 -3
  15. package/dist/esm/common/types/const-value.js.map +1 -1
  16. package/dist/esm/common/types/field-mapping.d.ts +6 -8
  17. package/dist/esm/common/types/field-mapping.js +0 -10
  18. package/dist/esm/common/types/field-mapping.js.map +1 -1
  19. package/dist/esm/common/types/index.d.ts +1 -0
  20. package/dist/esm/common/types/index.js +1 -0
  21. package/dist/esm/common/types/index.js.map +1 -1
  22. package/dist/esm/common/types/injection.d.ts +1 -1
  23. package/dist/esm/common/types/injection.js.map +1 -1
  24. package/dist/esm/common/types/json.d.ts +14 -0
  25. package/dist/esm/common/types/json.js +2 -0
  26. package/dist/esm/common/types/json.js.map +1 -0
  27. package/dist/esm/common/types/utility.d.ts +0 -4
  28. package/dist/esm/common/types/utility.js.map +1 -1
  29. package/dist/esm/modules/env/app-env.d.ts +17 -8
  30. package/dist/esm/modules/env/app-env.js +18 -15
  31. package/dist/esm/modules/env/app-env.js.map +1 -1
  32. package/dist/esm/modules/env/common/types.d.ts +22 -6
  33. package/dist/esm/modules/env/common/types.js.map +1 -1
  34. package/dist/esm/modules/logger/base/abstract.d.ts +6 -7
  35. package/dist/esm/modules/logger/base/abstract.js.map +1 -1
  36. package/dist/esm/modules/logger/base/base.d.ts +7 -8
  37. package/dist/esm/modules/logger/base/base.js.map +1 -1
  38. package/dist/esm/modules/logger/base/console.d.ts +6 -7
  39. package/dist/esm/modules/logger/base/console.js.map +1 -1
  40. package/dist/esm/modules/logger/common/types.d.ts +7 -7
  41. package/dist/esm/modules/logger/common/types.js.map +1 -1
  42. package/dist/esm/modules/logger/factory.js.map +1 -1
  43. package/dist/esm/modules/logger/hf/flusher.js.map +1 -1
  44. package/dist/esm/modules/logger/hf/logger.d.ts +6 -7
  45. package/dist/esm/modules/logger/hf/logger.js.map +1 -1
  46. package/dist/esm/modules/logger/pino/backing.js.map +1 -1
  47. package/dist/esm/modules/logger/pino/destination.d.ts +1 -1
  48. package/dist/esm/modules/logger/pino/destination.js.map +1 -1
  49. package/dist/esm/modules/logger/pino/logger.d.ts +1 -2
  50. package/dist/esm/modules/logger/pino/logger.js.map +1 -1
  51. package/dist/esm/modules/logger/winston/formats.js +2 -2
  52. package/dist/esm/modules/logger/winston/formats.js.map +1 -1
  53. package/dist/esm/modules/logger/winston/logger.d.ts +1 -2
  54. package/dist/esm/modules/logger/winston/logger.js.map +1 -1
  55. package/dist/esm/modules/logger/winston/transports/dgram.transport.d.ts +1 -1
  56. package/dist/esm/modules/logger/winston/transports/dgram.transport.js +1 -1
  57. package/dist/esm/modules/logger/winston/transports/dgram.transport.js.map +1 -1
  58. package/dist/esm/modules/network/http-request/common/constants.d.ts +0 -2
  59. package/dist/esm/modules/network/http-request/common/constants.js +0 -4
  60. package/dist/esm/modules/network/http-request/common/constants.js.map +1 -1
  61. package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.d.ts +6 -6
  62. package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.js.map +1 -1
  63. package/dist/esm/modules/network/http-request/fetcher/base-fetcher.d.ts +2 -3
  64. package/dist/esm/modules/network/http-request/fetcher/base-fetcher.js.map +1 -1
  65. package/dist/esm/modules/network/http-request/fetcher/common/types.d.ts +1 -1
  66. package/dist/esm/modules/network/http-request/fetcher/common/types.js.map +1 -1
  67. package/dist/esm/modules/network/http-request/fetcher/node-fetcher.d.ts +1 -2
  68. package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js +5 -6
  69. package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js.map +1 -1
  70. package/dist/esm/modules/network/tcp-socket/base-tcp-client.helper.d.ts +4 -4
  71. package/dist/esm/modules/network/tcp-socket/base-tcp-client.helper.js +1 -1
  72. package/dist/esm/modules/network/tcp-socket/base-tcp-client.helper.js.map +1 -1
  73. package/dist/esm/modules/network/tcp-socket/base-tcp-server.helper.d.ts +3 -5
  74. package/dist/esm/modules/network/tcp-socket/base-tcp-server.helper.js +0 -8
  75. package/dist/esm/modules/network/tcp-socket/base-tcp-server.helper.js.map +1 -1
  76. package/dist/esm/modules/network/utilities/query-string.d.ts +2 -2
  77. package/dist/esm/modules/network/utilities/query-string.js.map +1 -1
  78. package/dist/esm/modules/network/utilities/url-safety/common/constants.d.ts +0 -2
  79. package/dist/esm/modules/network/utilities/url-safety/common/constants.js +0 -4
  80. package/dist/esm/modules/network/utilities/url-safety/common/constants.js.map +1 -1
  81. package/dist/esm/modules/network/utilities/url-safety/ingest.js.map +1 -1
  82. package/dist/esm/modules/queue/bullmq/helper.d.ts +23 -10
  83. package/dist/esm/modules/queue/bullmq/helper.js +57 -10
  84. package/dist/esm/modules/queue/bullmq/helper.js.map +1 -1
  85. package/dist/esm/modules/queue/common/constants.d.ts +6 -2
  86. package/dist/esm/modules/queue/common/constants.js +6 -4
  87. package/dist/esm/modules/queue/common/constants.js.map +1 -1
  88. package/dist/esm/modules/queue/internal/sequential/common/types.d.ts +2 -4
  89. package/dist/esm/modules/queue/internal/sequential/common/types.js +0 -4
  90. package/dist/esm/modules/queue/internal/sequential/common/types.js.map +1 -1
  91. package/dist/esm/modules/queue/kafka/base.d.ts +1 -1
  92. package/dist/esm/modules/queue/kafka/base.js +13 -2
  93. package/dist/esm/modules/queue/kafka/base.js.map +1 -1
  94. package/dist/esm/modules/queue/kafka/common/constants.d.ts +0 -4
  95. package/dist/esm/modules/queue/kafka/common/constants.js +0 -8
  96. package/dist/esm/modules/queue/kafka/common/constants.js.map +1 -1
  97. package/dist/esm/modules/redis/base/abstract.helper.d.ts +13 -2
  98. package/dist/esm/modules/redis/base/abstract.helper.js +53 -45
  99. package/dist/esm/modules/redis/base/abstract.helper.js.map +1 -1
  100. package/dist/esm/modules/redis/cluster/cluster.helper.d.ts +1 -2
  101. package/dist/esm/modules/redis/cluster/cluster.helper.js +21 -9
  102. package/dist/esm/modules/redis/cluster/cluster.helper.js.map +1 -1
  103. package/dist/esm/modules/redis/cluster/index.d.ts +1 -0
  104. package/dist/esm/modules/redis/cluster/index.js +1 -0
  105. package/dist/esm/modules/redis/cluster/index.js.map +1 -1
  106. package/dist/esm/modules/redis/cluster/types.d.ts +20 -0
  107. package/dist/esm/modules/redis/cluster/types.js +2 -0
  108. package/dist/esm/modules/redis/cluster/types.js.map +1 -0
  109. package/dist/esm/modules/redis/common/constants.d.ts +15 -19
  110. package/dist/esm/modules/redis/common/constants.js +16 -18
  111. package/dist/esm/modules/redis/common/constants.js.map +1 -1
  112. package/dist/esm/modules/redis/common/types.d.ts +10 -60
  113. package/dist/esm/modules/redis/common/types.js.map +1 -1
  114. package/dist/esm/modules/redis/factory.d.ts +7 -25
  115. package/dist/esm/modules/redis/factory.js +9 -18
  116. package/dist/esm/modules/redis/factory.js.map +1 -1
  117. package/dist/esm/modules/redis/sentinel/constants.d.ts +14 -0
  118. package/dist/esm/modules/redis/sentinel/constants.js +11 -0
  119. package/dist/esm/modules/redis/sentinel/constants.js.map +1 -0
  120. package/dist/esm/modules/redis/sentinel/index.d.ts +2 -0
  121. package/dist/esm/modules/redis/sentinel/index.js +2 -0
  122. package/dist/esm/modules/redis/sentinel/index.js.map +1 -1
  123. package/dist/esm/modules/redis/sentinel/sentinel.helper.d.ts +1 -2
  124. package/dist/esm/modules/redis/sentinel/sentinel.helper.js +25 -15
  125. package/dist/esm/modules/redis/sentinel/sentinel.helper.js.map +1 -1
  126. package/dist/esm/modules/redis/sentinel/types.d.ts +26 -0
  127. package/dist/esm/modules/redis/sentinel/types.js +2 -0
  128. package/dist/esm/modules/redis/sentinel/types.js.map +1 -0
  129. package/dist/esm/modules/redis/single/index.d.ts +1 -0
  130. package/dist/esm/modules/redis/single/index.js +1 -0
  131. package/dist/esm/modules/redis/single/index.js.map +1 -1
  132. package/dist/esm/modules/redis/single/single.helper.d.ts +1 -2
  133. package/dist/esm/modules/redis/single/single.helper.js +5 -6
  134. package/dist/esm/modules/redis/single/single.helper.js.map +1 -1
  135. package/dist/esm/modules/redis/single/types.d.ts +15 -0
  136. package/dist/esm/modules/redis/single/types.js +2 -0
  137. package/dist/esm/modules/redis/single/types.js.map +1 -0
  138. package/dist/esm/modules/secrets/base/abstract.helper.js +6 -1
  139. package/dist/esm/modules/secrets/base/abstract.helper.js.map +1 -1
  140. package/dist/esm/modules/secrets/common/types/registration.d.ts +25 -6
  141. package/dist/esm/modules/secrets/common/types/registration.js.map +1 -1
  142. package/dist/esm/modules/secrets/dotenv/dotenv.helper.js +1 -1
  143. package/dist/esm/modules/secrets/dotenv/dotenv.helper.js.map +1 -1
  144. package/dist/esm/modules/secrets/factory.js +7 -6
  145. package/dist/esm/modules/secrets/factory.js.map +1 -1
  146. package/dist/esm/modules/secrets/hashicorp/hashicorp.helper.d.ts +12 -10
  147. package/dist/esm/modules/secrets/hashicorp/hashicorp.helper.js +50 -25
  148. package/dist/esm/modules/secrets/hashicorp/hashicorp.helper.js.map +1 -1
  149. package/dist/esm/modules/socket/socket-io/client/browser-helper.js.map +1 -1
  150. package/dist/esm/modules/socket/socket-io/common/types/client.d.ts +2 -2
  151. package/dist/esm/modules/socket/socket-io/common/types/client.js.map +1 -1
  152. package/dist/esm/modules/socket/socket-io/common/types/server.d.ts +3 -1
  153. package/dist/esm/modules/socket/socket-io/common/types/server.js.map +1 -1
  154. package/dist/esm/modules/socket/socket-io/server/helper.d.ts +2 -2
  155. package/dist/esm/modules/socket/socket-io/server/helper.js.map +1 -1
  156. package/dist/esm/modules/storage/base.d.ts +24 -60
  157. package/dist/esm/modules/storage/base.js +66 -123
  158. package/dist/esm/modules/storage/base.js.map +1 -1
  159. package/dist/esm/modules/storage/bun-s3/helper.d.ts +21 -35
  160. package/dist/esm/modules/storage/bun-s3/helper.js +126 -128
  161. package/dist/esm/modules/storage/bun-s3/helper.js.map +1 -1
  162. package/dist/esm/modules/storage/bun-s3/utility.d.ts +13 -7
  163. package/dist/esm/modules/storage/bun-s3/utility.js +63 -45
  164. package/dist/esm/modules/storage/bun-s3/utility.js.map +1 -1
  165. package/dist/esm/modules/storage/common/constants.d.ts +29 -2
  166. package/dist/esm/modules/storage/common/constants.js +29 -4
  167. package/dist/esm/modules/storage/common/constants.js.map +1 -1
  168. package/dist/esm/modules/storage/common/errors.d.ts +9 -0
  169. package/dist/esm/modules/storage/common/errors.js +9 -0
  170. package/dist/esm/modules/storage/common/errors.js.map +1 -1
  171. package/dist/esm/modules/storage/common/types.d.ts +90 -61
  172. package/dist/esm/modules/storage/common/types.js.map +1 -1
  173. package/dist/esm/modules/storage/common/utility.d.ts +8 -0
  174. package/dist/esm/modules/storage/common/utility.js +14 -2
  175. package/dist/esm/modules/storage/common/utility.js.map +1 -1
  176. package/dist/esm/modules/storage/disk/helper.d.ts +3 -8
  177. package/dist/esm/modules/storage/disk/helper.js +1 -0
  178. package/dist/esm/modules/storage/disk/helper.js.map +1 -1
  179. package/dist/esm/modules/storage/in-memory/helper.d.ts +2 -3
  180. package/dist/esm/modules/storage/in-memory/helper.js.map +1 -1
  181. package/dist/esm/modules/worker-thread/common/types.d.ts +2 -2
  182. package/dist/esm/modules/worker-thread/common/types.js.map +1 -1
  183. package/dist/esm/modules/worker-thread/thread/abstract.d.ts +2 -2
  184. package/dist/esm/modules/worker-thread/thread/abstract.js.map +1 -1
  185. package/dist/esm/modules/worker-thread/worker-pool.d.ts +1 -1
  186. package/dist/esm/modules/worker-thread/worker-pool.js.map +1 -1
  187. package/dist/esm/utilities/module.utility.d.ts +8 -5
  188. package/dist/esm/utilities/module.utility.js +5 -1
  189. package/dist/esm/utilities/module.utility.js.map +1 -1
  190. package/dist/esm/utilities/parse.utility.d.ts +34 -6
  191. package/dist/esm/utilities/parse.utility.js +82 -15
  192. package/dist/esm/utilities/parse.utility.js.map +1 -1
  193. package/dist/esm/utilities/performance.utility.d.ts +3 -3
  194. package/dist/esm/utilities/performance.utility.js.map +1 -1
  195. package/dist/esm/utilities/promise.utility.d.ts +1 -1
  196. package/dist/esm/utilities/promise.utility.js.map +1 -1
  197. package/dist/esm/utilities/request.utility.d.ts +9 -11
  198. package/dist/esm/utilities/request.utility.js.map +1 -1
  199. package/package.json +3 -3
@@ -4,8 +4,7 @@ import { BaseHelper } from '../base.js';
4
4
  import { getError } from '../error/index.js';
5
5
  import { EchoUtility } from '../../utilities/echo.utility.js';
6
6
  import { PromiseUtility } from '../../utilities/promise.utility.js';
7
- import { Readable } from 'node:stream';
8
- import { StorageUtility, StorageConcurrency, StorageErrors } from './common/index.js';
7
+ import { StorageUtility, StorageConcurrency, StorageErrors, StorageLimits } from './common/index.js';
9
8
  /** Shared base for storage helpers: MIME lookup, name and path validation, and upload naming. Concrete helpers implement the backend calls. */
10
9
  export class BaseStorageHelper extends BaseHelper {
11
10
  constructor(opts) {
@@ -14,64 +13,46 @@ export class BaseStorageHelper extends BaseHelper {
14
13
  getMimeType(opts) {
15
14
  return ContentTypeTable.resolve(opts);
16
15
  }
17
- /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */
18
- isValidSegment(opts) {
19
- const name = opts.segment;
20
- if (typeof name !== 'string') {
21
- this.logger
22
- .for(this.isValidSegment.name)
23
- .error('Invalid name provided: %s', EchoUtility.toSafeEcho({ value: name }));
24
- return false;
25
- }
26
- if (!name || ObjectUtility.isEmpty({ value: name })) {
27
- this.logger.for(this.isValidSegment.name).error('Empty name provided');
28
- return false;
29
- }
30
- if (name.includes('..') || name.includes('/') || name.includes('\\')) {
31
- this.logger
32
- .for(this.isValidSegment.name)
33
- .error('Name contains invalid path characters: %s', EchoUtility.toSafeEcho({ value: name }));
34
- return false;
35
- }
36
- if (name.startsWith('.')) {
37
- this.logger
38
- .for(this.isValidSegment.name)
39
- .error('Name cannot start with a dot: %s', EchoUtility.toSafeEcho({ value: name }));
40
- return false;
41
- }
42
- const dangerousChars = /[;|&$`<>{}[\]!#]/;
43
- if (dangerousChars.test(name)) {
44
- this.logger
45
- .for(this.isValidSegment.name)
46
- .error('Name contains dangerous characters: %s', EchoUtility.toSafeEcho({ value: name }));
47
- return false;
48
- }
49
- if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {
50
- // The length, not the name: a control character in a log line is the line's own to forge.
51
- this.logger
52
- .for(this.isValidSegment.name)
53
- .error('Name contains a control or bidirectional character | length: %d', name.length);
54
- return false;
55
- }
56
- const byteLength = BaseStorageHelper.UTF8.encode(name).byteLength;
57
- if (byteLength > 255) {
58
- this.logger
59
- .for(this.isValidSegment.name)
60
- .error('Name is too long (%d bytes): %s', byteLength, EchoUtility.toSafeEcho({ value: name }));
61
- return false;
62
- }
63
- if (name.trim().length === 0) {
64
- this.logger
65
- .for(this.isValidSegment.name)
66
- .error('Name cannot be empty or whitespace only: %s', EchoUtility.toSafeEcho({ value: name }));
67
- return false;
68
- }
69
- return true;
70
- }
71
16
  static { this.DEFAULT_MAX_FOLDER_DEPTH = 2; }
72
17
  static { this.UTF8 = new TextEncoder(); }
18
+ static { this.DANGEROUS_NAME_CHARACTERS = /[;|&$`<>{}[\]!#]/; }
73
19
  /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */
74
20
  static { this.UNSAFE_NAME_CHARACTERS = /[\p{Cc}\p{Cs}\u061C\u200E\u200F\u2028\u2029\u202A-\u202E\u2066-\u2069]/u; }
21
+ /** Every way a segment can be refused, first match wins. */
22
+ static { this.SEGMENT_RULES = [
23
+ { reason: 'Name is empty or whitespace only', isViolated: (name) => name.trim().length === 0 },
24
+ {
25
+ reason: 'Name contains invalid path characters',
26
+ isViolated: (name) => name.includes('..') || name.includes('/') || name.includes('\\'),
27
+ },
28
+ { reason: 'Name cannot start with a dot', isViolated: (name) => name.startsWith('.') },
29
+ {
30
+ reason: 'Name contains dangerous characters',
31
+ isViolated: (name) => BaseStorageHelper.DANGEROUS_NAME_CHARACTERS.test(name),
32
+ },
33
+ {
34
+ reason: 'Name contains a control or bidirectional character',
35
+ isViolated: (name) => BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name),
36
+ },
37
+ {
38
+ reason: `Name is longer than ${StorageLimits.MAX_SEGMENT_BYTES} bytes`,
39
+ isViolated: (name) => BaseStorageHelper.UTF8.encode(name).byteLength > StorageLimits.MAX_SEGMENT_BYTES,
40
+ },
41
+ ]; }
42
+ /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */
43
+ isValidSegment(opts) {
44
+ const name = opts.segment;
45
+ const reason = typeof name === 'string'
46
+ ? BaseStorageHelper.SEGMENT_RULES.find((rule) => rule.isViolated(name))?.reason
47
+ : 'Name is not a string';
48
+ if (reason === undefined) {
49
+ return true;
50
+ }
51
+ this.logger
52
+ .for(this.isValidSegment.name)
53
+ .error('%s | name: %s', reason, EchoUtility.toSafeEcho({ value: name }));
54
+ return false;
55
+ }
75
56
  /** A bucket name is one segment; a separator in it would silently address a different bucket. */
76
57
  isValidBucketName(opts) {
77
58
  return this.isValidSegment({ segment: opts.bucket.name });
@@ -126,7 +107,7 @@ export class BaseStorageHelper extends BaseHelper {
126
107
  }
127
108
  }
128
109
  const byteLength = BaseStorageHelper.UTF8.encode(normalized).byteLength;
129
- if (byteLength > 1024) {
110
+ if (byteLength > StorageLimits.MAX_KEY_BYTES) {
130
111
  this.logger
131
112
  .for(this.isValidKeyPath.name)
132
113
  .error('Path is too long (%d bytes): %s', byteLength, EchoUtility.toSafeEcho({ value: pathStr }));
@@ -167,7 +148,9 @@ export class BaseStorageHelper extends BaseHelper {
167
148
  /** An original name that is only metadata - the key is resolved elsewhere and validated on its own. */
168
149
  isValidOriginalName(opts) {
169
150
  const { name } = opts;
170
- if (typeof name !== 'string' || name.trim().length === 0 || name.length > 255) {
151
+ if (typeof name !== 'string' ||
152
+ name.trim().length === 0 ||
153
+ name.length > StorageLimits.MAX_SEGMENT_BYTES) {
171
154
  this.logger
172
155
  .for(this.isValidOriginalName.name)
173
156
  .error('Invalid original name: %s', EchoUtility.toSafeEcho({ value: name }));
@@ -275,50 +258,8 @@ export class BaseStorageHelper extends BaseHelper {
275
258
  },
276
259
  });
277
260
  }
278
- /** Correct anywhere; overridden by a backend whose transport is already a web stream. */
279
- async getObjectStream(opts) {
280
- const { bucket, object, range } = opts;
281
- const source = await this.getObject({ bucket, object });
282
- if (!range) {
283
- return Readable.toWeb(source);
284
- }
285
- // No native range here: take the window off the front of the full stream. `pull` rather than
286
- // `start`, so one chunk is read per demand instead of the whole range landing in memory.
287
- const { start, end } = range;
288
- const chunks = source[Symbol.asyncIterator]();
289
- let offset = 0;
290
- return new ReadableStream({
291
- async pull(controller) {
292
- while (true) {
293
- const next = await chunks.next();
294
- if (next.done) {
295
- controller.close();
296
- return;
297
- }
298
- const bytes = next.value;
299
- const chunkEnd = offset + bytes.byteLength;
300
- const from = Math.max(start - offset, 0);
301
- const to = end === undefined ? bytes.byteLength : Math.min(end + 1 - offset, bytes.byteLength);
302
- const isWanted = chunkEnd > start && from < to;
303
- if (isWanted) {
304
- controller.enqueue(bytes.subarray(from, to));
305
- }
306
- offset = chunkEnd;
307
- if (end !== undefined && offset > end) {
308
- source.destroy();
309
- controller.close();
310
- return;
311
- }
312
- if (isWanted) {
313
- return;
314
- }
315
- }
316
- },
317
- // Without this a client that aborts leaves the backend stream draining to nowhere.
318
- cancel() {
319
- source.destroy();
320
- },
321
- });
261
+ async getObjectStream(_opts) {
262
+ throw this.unsupported({ operation: 'getObjectStream', feature: 'Streaming a read' });
322
263
  }
323
264
  /**
324
265
  * Correct anywhere, and the wrong path to stay on: it buffers, so a backend whose transport takes
@@ -338,8 +279,8 @@ export class BaseStorageHelper extends BaseHelper {
338
279
  });
339
280
  }
340
281
  // As `upload` does: a write never creates the bucket.
341
- const result2 = await this.hasBucket({ bucket });
342
- if (!result2) {
282
+ const isExists = await this.hasBucket({ bucket });
283
+ if (!isExists) {
343
284
  throw getError({
344
285
  message: `[writeStream] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,
345
286
  });
@@ -380,36 +321,38 @@ export class BaseStorageHelper extends BaseHelper {
380
321
  message: `[${operation}] Object not found | bucket: ${EchoUtility.toSafeText({ value: bucket.name })} | key: ${EchoUtility.toSafeText({ value: object.key })}`,
381
322
  });
382
323
  }
383
- // No transport for these: throwing beats returning undefined, which reads as a valid empty result.
384
- async copyObject(_opts) {
385
- throw getError({
386
- message: `[${this.constructor.name}.copyObject] Server-side copy is not supported by this helper`,
324
+ /** For a backend with no ETag or versions to condition a read on: refusing is honest, ignoring would read unpinned. */
325
+ refuseReadCondition(opts) {
326
+ if (opts.condition.ifMatch !== undefined || opts.condition.versionId !== undefined) {
327
+ throw this.unsupported({
328
+ operation: opts.operation,
329
+ feature: 'A conditional read (ifMatch, versionId)',
330
+ });
331
+ }
332
+ }
333
+ /** The error of an operation this helper has no transport for: throwing beats returning undefined, which reads as a valid empty result. */
334
+ unsupported(opts) {
335
+ return getError({
336
+ message: `[${this.constructor.name}.${opts.operation}] ${opts.feature} is not supported by this helper`,
387
337
  });
388
338
  }
339
+ async copyObject(_opts) {
340
+ throw this.unsupported({ operation: 'copyObject', feature: 'Server-side copy' });
341
+ }
389
342
  async presignPost(_opts) {
390
- throw getError({
391
- message: `[${this.constructor.name}.presignPost] Signed POST policies are not supported by this helper`,
392
- });
343
+ throw this.unsupported({ operation: 'presignPost', feature: 'Signed POST policies' });
393
344
  }
394
345
  async presignPut(_opts) {
395
- throw getError({
396
- message: `[${this.constructor.name}.presignPut] Presigned PUT URLs are not supported by this helper`,
397
- });
346
+ throw this.unsupported({ operation: 'presignPut', feature: 'Presigned PUT URLs' });
398
347
  }
399
348
  async presignGet(_opts) {
400
- throw getError({
401
- message: `[${this.constructor.name}.presignGet] Presigned GET URLs are not supported by this helper`,
402
- });
349
+ throw this.unsupported({ operation: 'presignGet', feature: 'Presigned GET URLs' });
403
350
  }
404
351
  async getObjectTags(_opts) {
405
- throw getError({
406
- message: `[${this.constructor.name}.getObjectTags] Object tagging is not supported by this helper`,
407
- });
352
+ throw this.unsupported({ operation: 'getObjectTags', feature: 'Object tagging' });
408
353
  }
409
354
  async replaceObjectTags(_opts) {
410
- throw getError({
411
- message: `[${this.constructor.name}.replaceObjectTags] Object tagging is not supported by this helper`,
412
- });
355
+ throw this.unsupported({ operation: 'replaceObjectTags', feature: 'Object tagging' });
413
356
  }
414
357
  }
415
358
  //# sourceMappingURL=base.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/modules/storage/base.ts"],"names":[],"mappings":"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","sourcesContent":["import { ObjectUtility } from '@venizia/ignis-inversion';\nimport { ContentTypeTable, type IDuration, MimeTypes } from '@/common';\nimport { BaseHelper } from '@/modules/base';\nimport { getError } from '@/modules/error';\nimport { EchoUtility } from '@/utilities/echo.utility';\nimport { PromiseUtility } from '@/utilities/promise.utility';\nimport { Readable } from 'node:stream';\nimport {\n type IBucketInfo,\n type IBucketRef,\n type IFileStat,\n type IListObjectsOptions,\n type IObjectInfo,\n type IObjectLocation,\n type IPostPolicy,\n type IObjectRef,\n type IStorageHelper,\n type IUploadFile,\n type IUploadResult,\n type TUploadNaming,\n} from './common';\nimport { StorageUtility, StorageConcurrency, StorageErrors } from './common';\n\n/** Shared base for storage helpers: MIME lookup, name and path validation, and upload naming. Concrete helpers implement the backend calls. */\nexport abstract class BaseStorageHelper extends BaseHelper implements IStorageHelper {\n constructor(opts: { scope: string; identifier: string }) {\n super(opts);\n }\n\n getMimeType(opts: { filename: string }): string {\n return ContentTypeTable.resolve(opts);\n }\n\n /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */\n isValidSegment(opts: { segment: string }): boolean {\n const name = opts.segment;\n\n if (typeof name !== 'string') {\n this.logger\n .for(this.isValidSegment.name)\n .error('Invalid name provided: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (!name || ObjectUtility.isEmpty({ value: name })) {\n this.logger.for(this.isValidSegment.name).error('Empty name provided');\n\n return false;\n }\n\n if (name.includes('..') || name.includes('/') || name.includes('\\\\')) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name contains invalid path characters: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n if (name.startsWith('.')) {\n this.logger\n .for(this.isValidSegment.name)\n .error('Name cannot start with a dot: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n const dangerousChars = /[;|&$`<>{}[\\]!#]/;\n\n if (dangerousChars.test(name)) {\n this.logger\n .for(this.isValidSegment.name)\n .error('Name contains dangerous characters: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n // The length, not the name: a control character in a log line is the line's own to forge.\n this.logger\n .for(this.isValidSegment.name)\n .error('Name contains a control or bidirectional character | length: %d', name.length);\n\n return false;\n }\n\n const byteLength = BaseStorageHelper.UTF8.encode(name).byteLength;\n\n if (byteLength > 255) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name is too long (%d bytes): %s',\n byteLength,\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n if (name.trim().length === 0) {\n this.logger\n .for(this.isValidSegment.name)\n .error(\n 'Name cannot be empty or whitespace only: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n static readonly DEFAULT_MAX_FOLDER_DEPTH = 2;\n\n private static readonly UTF8 = new TextEncoder();\n\n /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */\n private static readonly UNSAFE_NAME_CHARACTERS =\n /[\\p{Cc}\\p{Cs}\\u061C\\u200E\\u200F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069]/u;\n\n /** A bucket name is one segment; a separator in it would silently address a different bucket. */\n isValidBucketName(opts: { bucket: IBucketRef }): boolean {\n return this.isValidSegment({ segment: opts.bucket.name });\n }\n\n /** A whole object key: every segment valid, no trailing `/`, and no deeper than `maxDepth` folders. */\n isValidObjectKey(opts: { object: IObjectRef; maxDepth?: number }): boolean {\n const { key } = opts.object;\n\n if (typeof key === 'string' && key.endsWith('/')) {\n this.logger\n .for(this.isValidObjectKey.name)\n .error('Object key ends with a slash: %s', EchoUtility.toSafeEcho({ value: key }));\n\n return false;\n }\n\n return this.isValidKeyPath({ path: key, maxDepth: opts.maxDepth });\n }\n\n /** The shared rule behind `isValidObjectKey` and the folder check inside `upload`. */\n protected isValidKeyPath(opts: { path: string; maxDepth?: number }): boolean {\n const { path: pathStr } = opts;\n const maxDepth = opts.maxDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n\n if (typeof pathStr !== 'string' || !pathStr || ObjectUtility.isEmpty({ value: pathStr })) {\n this.logger.for(this.isValidKeyPath.name).error('Empty or invalid path provided');\n\n return false;\n }\n\n const normalized = pathStr.replace(/^\\/+|\\/+$/g, '');\n\n if (!normalized) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error('Path resolved to empty after trimming slashes');\n\n return false;\n }\n\n const segments = normalized.split('/');\n\n if (segments.some((s) => s.length === 0)) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path contains empty segments (double slashes): %s',\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n // segments include the filename, so depth is one less.\n const folderDepth = segments.length - 1;\n\n if (folderDepth > maxDepth) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path exceeds max folder depth (%d): %s (depth: %d)',\n maxDepth,\n EchoUtility.toSafeEcho({ value: pathStr }),\n folderDepth,\n );\n\n return false;\n }\n\n for (const segment of segments) {\n if (!this.isValidSegment({ segment })) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path segment failed validation: %s (in path: %s)',\n EchoUtility.toSafeEcho({ value: segment }),\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n }\n\n const byteLength = BaseStorageHelper.UTF8.encode(normalized).byteLength;\n\n if (byteLength > 1024) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path is too long (%d bytes): %s',\n byteLength,\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n return true;\n }\n\n getMediaType(opts: { mimeType: string }): string {\n const { mimeType } = opts;\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.IMAGE)) {\n return MimeTypes.IMAGE;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.VIDEO)) {\n return MimeTypes.VIDEO;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.TEXT)) {\n return MimeTypes.TEXT;\n }\n\n return MimeTypes.UNKNOWN;\n }\n\n /** Public URL prefix; keeps its trailing slash. */\n protected abstract get defaultLinkPrefix(): string;\n\n /** Backend write step; owns its metadata and error handling. */\n protected abstract writeObject(opts: IObjectLocation & { file: IUploadFile }): Promise<void>;\n\n /** The key `upload` writes when no naming hook is given: lowercase, spaces become `_`, under the folder when there is one. Public so a naming hook can start from the very key the helper would have written. */\n static normalizeObjectName(opts: { file: TUploadNaming }): string {\n const { originalName, folderPath } = opts.file;\n const normalizedFileName = originalName.toLowerCase().replace(/ /g, '_');\n\n if (!folderPath) {\n return normalizedFileName;\n }\n\n return `${folderPath.toLowerCase().replace(/ /g, '_')}/${normalizedFileName}`;\n }\n\n protected normalizeObjectLink(opts: IObjectLocation): string {\n const bucketName = opts.bucket.name;\n const encodedName = opts.object.key\n .split('/')\n .map((segment) => encodeURIComponent(segment))\n .join('/');\n\n return `${this.defaultLinkPrefix}${bucketName}/${encodedName}`;\n }\n\n /** An original name that is only metadata - the key is resolved elsewhere and validated on its own. */\n protected isValidOriginalName(opts: { name: string }): boolean {\n const { name } = opts;\n\n if (typeof name !== 'string' || name.trim().length === 0 || name.length > 255) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error('Invalid original name: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error(\n 'Original name contains a control character or a lone surrogate: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n /** `isKeyResolvedByCaller`: a `normalizeNameFn` decides the key, so the original name is metadata and meets the metadata rule, not the key rule. */\n protected validateUploadFiles(opts: {\n files: IUploadFile[];\n maxFolderDepth?: number;\n isKeyResolvedByCaller?: boolean;\n }): void {\n const { files, maxFolderDepth, isKeyResolvedByCaller = false } = opts;\n\n for (const file of files) {\n this.validateUploadFile({ file, maxFolderDepth, isKeyResolvedByCaller });\n }\n }\n\n private validateUploadFile(opts: {\n file: IUploadFile;\n maxFolderDepth?: number;\n isKeyResolvedByCaller: boolean;\n }): void {\n const { file, maxFolderDepth, isKeyResolvedByCaller } = opts;\n const { originalName, size, folderPath } = file;\n\n const isNameValid = isKeyResolvedByCaller\n ? this.isValidOriginalName({ name: originalName })\n : this.isValidSegment({ segment: originalName });\n\n if (!isNameValid) {\n throw getError({ message: '[upload] Invalid original file name' });\n }\n\n // Checked against the CALLER's depth, before the body is spooled. `isValidKeyPath` measures an\n // object path (one folder deeper than a bare folderPath), so the depth is checked directly.\n if (folderPath) {\n const depthLimit = maxFolderDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n const folderSegments = folderPath.replace(/^\\/+|\\/+$/g, '').split('/');\n\n if (folderSegments.length > depthLimit) {\n throw getError({\n error: StorageErrors.FOLDER_DEPTH_EXCEEDED,\n message: `[upload] Invalid folder path | depth: ${folderSegments.length} | max: ${depthLimit}`,\n });\n }\n\n if (!this.isValidKeyPath({ path: folderPath, maxDepth: depthLimit })) {\n throw getError({\n error: StorageErrors.FOLDER_PATH_INVALID,\n message: '[upload] Invalid folder path',\n });\n }\n }\n\n // Missing or negative is invalid; zero is a legitimate empty file.\n if (size === undefined || size === null || size < 0) {\n throw getError({ message: `[upload] Invalid file size | size: ${size}` });\n }\n }\n\n async upload(opts: {\n bucket: IBucketRef;\n files: IUploadFile[];\n normalizeNameFn?: (opts: { file: TUploadNaming }) => string;\n normalizeLinkFn?: (opts: IObjectLocation) => string;\n /**\n * Folder nesting allowed.\n *\n * @default BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH\n */\n maxFolderDepth?: number;\n /**\n * Folders the finished key may carry, a scope the `normalizeNameFn` adds included.\n *\n * @default `maxFolderDepth`\n */\n maxKeyDepth?: number;\n }): Promise<IUploadResult[]> {\n const { bucket, files, normalizeNameFn, normalizeLinkFn, maxFolderDepth } = opts;\n const maxKeyDepth = opts.maxKeyDepth ?? maxFolderDepth;\n\n if (!files || files.length === 0) {\n return [];\n }\n\n const isExists = await this.hasBucket({ bucket });\n\n if (!isExists) {\n throw getError({\n message: `[upload] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n this.validateUploadFiles({\n files,\n maxFolderDepth,\n isKeyResolvedByCaller: normalizeNameFn !== undefined,\n });\n\n // Every key is resolved and validated before the first write, so one bad key stores nothing.\n const keys = files.map((file) => {\n const naming: TUploadNaming = {\n originalName: file.originalName,\n folderPath: file.folderPath,\n };\n const key = normalizeNameFn\n ? normalizeNameFn({ file: naming })\n : BaseStorageHelper.normalizeObjectName({ file: naming });\n\n if (!this.isValidObjectKey({ object: { key }, maxDepth: maxKeyDepth })) {\n throw getError({\n message: `[upload] Invalid normalized object name | name: ${EchoUtility.toSafeText({ value: key })}`,\n });\n }\n\n return key;\n });\n\n return this.mapWithConcurrency({\n items: files,\n task: async ({ item: file, index }) => {\n const { mimetype: mimeType, size, encoding } = file;\n const t = performance.now();\n const key = keys[index];\n\n const object: IObjectRef = { key };\n const link = normalizeLinkFn\n ? normalizeLinkFn({ bucket, object })\n : this.normalizeObjectLink({ bucket, object });\n\n await this.writeObject({ bucket, object, file });\n\n this.logger\n .for(this.upload.name)\n .info(\n 'Uploaded: %s | Took: %s (ms)',\n EchoUtility.toSafeEcho({ value: { key, link, mimeType, encoding, size } }),\n performance.now() - t,\n );\n\n return {\n bucket: { name: bucket.name },\n object: { key, size, contentType: mimeType },\n link,\n };\n },\n });\n }\n\n /** Correct anywhere; overridden by a backend whose transport is already a web stream. */\n async getObjectStream(\n opts: IObjectLocation & { range?: { start: number; end?: number } },\n ): Promise<ReadableStream<Uint8Array>> {\n const { bucket, object, range } = opts;\n const source = await this.getObject({ bucket, object });\n\n if (!range) {\n return Readable.toWeb(source) as ReadableStream<Uint8Array>;\n }\n\n // No native range here: take the window off the front of the full stream. `pull` rather than\n // `start`, so one chunk is read per demand instead of the whole range landing in memory.\n const { start, end } = range;\n const chunks = source[Symbol.asyncIterator]();\n let offset = 0;\n\n return new ReadableStream<Uint8Array>({\n async pull(controller) {\n while (true) {\n const next = await chunks.next();\n\n if (next.done) {\n controller.close();\n\n return;\n }\n\n const bytes = next.value as Uint8Array;\n const chunkEnd = offset + bytes.byteLength;\n const from = Math.max(start - offset, 0);\n const to =\n end === undefined ? bytes.byteLength : Math.min(end + 1 - offset, bytes.byteLength);\n const isWanted = chunkEnd > start && from < to;\n\n if (isWanted) {\n controller.enqueue(bytes.subarray(from, to));\n }\n\n offset = chunkEnd;\n\n if (end !== undefined && offset > end) {\n source.destroy();\n controller.close();\n\n return;\n }\n\n if (isWanted) {\n return;\n }\n }\n },\n\n // Without this a client that aborts leaves the backend stream draining to nowhere.\n cancel() {\n source.destroy();\n },\n });\n }\n\n /**\n * Correct anywhere, and the wrong path to stay on: it buffers, so a backend whose transport takes\n * a stream overrides it. `BunS3Helper` does.\n */\n async writeStream(\n opts: IObjectLocation & {\n source: ReadableStream<Uint8Array> | Blob | Response | Request;\n contentType?: string;\n maxFolderDepth?: number;\n },\n ): Promise<void> {\n const { bucket, object, source, contentType } = opts;\n\n // The same depth rule `upload` applies, as `BunS3Helper.writeStream` does: one object, two doors, one answer.\n if (!this.isValidObjectKey({ object, maxDepth: opts.maxFolderDepth })) {\n throw getError({\n message: `[writeStream] Invalid object name | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n if (!this.isValidBucketName({ bucket })) {\n throw getError({\n message: `[storage] Invalid bucket name | bucket: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n // As `upload` does: a write never creates the bucket.\n const result2 = await this.hasBucket({ bucket });\n\n if (!result2) {\n throw getError({\n message: `[writeStream] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n const body =\n source instanceof Response || source instanceof Request ? source : new Response(source);\n const result = await body.arrayBuffer();\n const buffer = Buffer.from(result);\n\n await this.writeObject({\n bucket,\n object,\n file: {\n originalName: object.key,\n mimetype: contentType ?? this.getMimeType({ filename: object.key }),\n buffer,\n size: buffer.length,\n },\n });\n }\n\n /** Bounded fan-out on the shared limiter; unbounded exhausts sockets and gets rate limited. */\n protected async mapWithConcurrency<Item, Result>(opts: {\n items: Item[];\n limit?: number;\n task: (taskOptions: { item: Item; index: number }) => Promise<Result>;\n }): Promise<Result[]> {\n const { items, task } = opts;\n\n if (items.length === 0) {\n return [];\n }\n\n return PromiseUtility.executeWithLimit({\n limit: Math.max(1, opts.limit ?? StorageConcurrency.DEFAULT_LIMIT),\n tasks: items.map((item, index) => () => task({ item, index })),\n });\n }\n\n /** A \"not there\" failure becomes a catalogued 404; every other failure passes through unchanged. */\n protected asStorageError(opts: IObjectLocation & { error: unknown; operation: string }): unknown {\n const { error, operation, bucket, object } = opts;\n\n if (!StorageUtility.isNotFoundError({ error })) {\n return error;\n }\n\n return getError({\n error: StorageErrors.OBJECT_NOT_FOUND,\n message: `[${operation}] Object not found | bucket: ${EchoUtility.toSafeText({ value: bucket.name })} | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n // No transport for these: throwing beats returning undefined, which reads as a valid empty result.\n async copyObject(_opts: {\n bucket: IBucketRef;\n source: IObjectRef;\n destination: IObjectRef;\n }): Promise<void> {\n throw getError({\n message: `[${this.constructor.name}.copyObject] Server-side copy is not supported by this helper`,\n });\n }\n\n async presignPost(\n _opts: IObjectLocation & {\n maxBytes: number;\n contentType?: string;\n expiresIn?: IDuration;\n },\n ): Promise<IPostPolicy> {\n throw getError({\n message: `[${this.constructor.name}.presignPost] Signed POST policies are not supported by this helper`,\n });\n }\n\n async presignPut(\n _opts: IObjectLocation & {\n expiresIn?: IDuration;\n tagging?: Record<string, string>;\n contentLength?: number;\n contentType?: string;\n },\n ): Promise<string> {\n throw getError({\n message: `[${this.constructor.name}.presignPut] Presigned PUT URLs are not supported by this helper`,\n });\n }\n\n async presignGet(\n _opts: IObjectLocation & { expiresIn?: IDuration; responseContentType?: string },\n ): Promise<string> {\n throw getError({\n message: `[${this.constructor.name}.presignGet] Presigned GET URLs are not supported by this helper`,\n });\n }\n\n async getObjectTags(_opts: IObjectLocation): Promise<Record<string, string>> {\n throw getError({\n message: `[${this.constructor.name}.getObjectTags] Object tagging is not supported by this helper`,\n });\n }\n\n async replaceObjectTags(\n _opts: IObjectLocation & { tags: Record<string, string> },\n ): Promise<void> {\n throw getError({\n message: `[${this.constructor.name}.replaceObjectTags] Object tagging is not supported by this helper`,\n });\n }\n\n abstract hasBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n abstract getBuckets(): Promise<IBucketInfo[]>;\n abstract getBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract createBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract removeBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n\n abstract getObject(opts: IObjectLocation & { options?: any }): Promise<Readable>;\n abstract getStat(opts: IObjectLocation): Promise<IFileStat>;\n abstract removeObject(opts: IObjectLocation): Promise<void>;\n abstract removeObjects(opts: { bucket: IBucketRef; objects: IObjectRef[] }): Promise<void>;\n abstract listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;\n}\n"]}
1
+ {"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../src/modules/storage/base.ts"],"names":[],"mappings":"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","sourcesContent":["import { ObjectUtility } from '@venizia/ignis-inversion';\nimport { ContentTypeTable, MimeTypes } from '@/common';\nimport { BaseHelper } from '@/modules/base';\nimport { getError } from '@/modules/error';\nimport { EchoUtility } from '@/utilities/echo.utility';\nimport { PromiseUtility } from '@/utilities/promise.utility';\nimport type { Readable } from 'node:stream';\nimport {\n type IBucketInfo,\n type IBucketRef,\n type IFileStat,\n type IListObjectsOptions,\n type IObjectInfo,\n type IObjectLocation,\n type IPostPolicy,\n type IObjectRef,\n type IStorageHelper,\n type IStorageReadCondition,\n type ICopyObjectOptions,\n type IPresignGetOptions,\n type IPresignPostOptions,\n type IPresignPutOptions,\n type IUploadOptions,\n type IWriteStreamOptions,\n type TObjectStreamOptions,\n type IUploadFile,\n type IUploadResult,\n type TUploadNaming,\n} from './common';\nimport { StorageUtility, StorageConcurrency, StorageErrors, StorageLimits } from './common';\n\n/** Shared base for storage helpers: MIME lookup, name and path validation, and upload naming. Concrete helpers implement the backend calls. */\nexport abstract class BaseStorageHelper extends BaseHelper implements IStorageHelper {\n constructor(opts: { scope: string; identifier: string }) {\n super(opts);\n }\n\n getMimeType(opts: { filename: string }): string {\n return ContentTypeTable.resolve(opts);\n }\n\n static readonly DEFAULT_MAX_FOLDER_DEPTH = 2;\n\n private static readonly UTF8 = new TextEncoder();\n\n private static readonly DANGEROUS_NAME_CHARACTERS = /[;|&$`<>{}[\\]!#]/;\n\n /** Control characters, lone surrogates, the line and paragraph separators (U+2028, U+2029) and the bidirectional marks and overrides: never part of a file name or a key (the overrides make `gpj.exe` display as `exe.jpg`), and a control character or a surrogate cannot be encoded into a header. */\n private static readonly UNSAFE_NAME_CHARACTERS =\n /[\\p{Cc}\\p{Cs}\\u061C\\u200E\\u200F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069]/u;\n\n /** Every way a segment can be refused, first match wins. */\n private static readonly SEGMENT_RULES: Array<{\n reason: string;\n isViolated: (name: string) => boolean;\n }> = [\n { reason: 'Name is empty or whitespace only', isViolated: (name) => name.trim().length === 0 },\n {\n reason: 'Name contains invalid path characters',\n isViolated: (name) => name.includes('..') || name.includes('/') || name.includes('\\\\'),\n },\n { reason: 'Name cannot start with a dot', isViolated: (name) => name.startsWith('.') },\n {\n reason: 'Name contains dangerous characters',\n isViolated: (name) => BaseStorageHelper.DANGEROUS_NAME_CHARACTERS.test(name),\n },\n {\n reason: 'Name contains a control or bidirectional character',\n isViolated: (name) => BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name),\n },\n {\n reason: `Name is longer than ${StorageLimits.MAX_SEGMENT_BYTES} bytes`,\n isViolated: (name) =>\n BaseStorageHelper.UTF8.encode(name).byteLength > StorageLimits.MAX_SEGMENT_BYTES,\n },\n ];\n\n /** One path segment or file name: at most 255 UTF-8 bytes, no separator, no traversal, no control or shell character. */\n isValidSegment(opts: { segment: string }): boolean {\n const name = opts.segment;\n\n const reason =\n typeof name === 'string'\n ? BaseStorageHelper.SEGMENT_RULES.find((rule) => rule.isViolated(name))?.reason\n : 'Name is not a string';\n\n if (reason === undefined) {\n return true;\n }\n\n this.logger\n .for(this.isValidSegment.name)\n .error('%s | name: %s', reason, EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n /** A bucket name is one segment; a separator in it would silently address a different bucket. */\n isValidBucketName(opts: { bucket: IBucketRef }): boolean {\n return this.isValidSegment({ segment: opts.bucket.name });\n }\n\n /** A whole object key: every segment valid, no trailing `/`, and no deeper than `maxDepth` folders. */\n isValidObjectKey(opts: { object: IObjectRef; maxDepth?: number }): boolean {\n const { key } = opts.object;\n\n if (typeof key === 'string' && key.endsWith('/')) {\n this.logger\n .for(this.isValidObjectKey.name)\n .error('Object key ends with a slash: %s', EchoUtility.toSafeEcho({ value: key }));\n\n return false;\n }\n\n return this.isValidKeyPath({ path: key, maxDepth: opts.maxDepth });\n }\n\n /** The shared rule behind `isValidObjectKey` and the folder check inside `upload`. */\n protected isValidKeyPath(opts: { path: string; maxDepth?: number }): boolean {\n const { path: pathStr } = opts;\n const maxDepth = opts.maxDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n\n if (typeof pathStr !== 'string' || !pathStr || ObjectUtility.isEmpty({ value: pathStr })) {\n this.logger.for(this.isValidKeyPath.name).error('Empty or invalid path provided');\n\n return false;\n }\n\n const normalized = pathStr.replace(/^\\/+|\\/+$/g, '');\n\n if (!normalized) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error('Path resolved to empty after trimming slashes');\n\n return false;\n }\n\n const segments = normalized.split('/');\n\n if (segments.some((s) => s.length === 0)) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path contains empty segments (double slashes): %s',\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n // segments include the filename, so depth is one less.\n const folderDepth = segments.length - 1;\n\n if (folderDepth > maxDepth) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path exceeds max folder depth (%d): %s (depth: %d)',\n maxDepth,\n EchoUtility.toSafeEcho({ value: pathStr }),\n folderDepth,\n );\n\n return false;\n }\n\n for (const segment of segments) {\n if (!this.isValidSegment({ segment })) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path segment failed validation: %s (in path: %s)',\n EchoUtility.toSafeEcho({ value: segment }),\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n }\n\n const byteLength = BaseStorageHelper.UTF8.encode(normalized).byteLength;\n\n if (byteLength > StorageLimits.MAX_KEY_BYTES) {\n this.logger\n .for(this.isValidKeyPath.name)\n .error(\n 'Path is too long (%d bytes): %s',\n byteLength,\n EchoUtility.toSafeEcho({ value: pathStr }),\n );\n\n return false;\n }\n\n return true;\n }\n\n getMediaType(opts: { mimeType: string }): string {\n const { mimeType } = opts;\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.IMAGE)) {\n return MimeTypes.IMAGE;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.VIDEO)) {\n return MimeTypes.VIDEO;\n }\n\n if (mimeType?.toLowerCase()?.startsWith(MimeTypes.TEXT)) {\n return MimeTypes.TEXT;\n }\n\n return MimeTypes.UNKNOWN;\n }\n\n /** Public URL prefix; keeps its trailing slash. */\n protected abstract get defaultLinkPrefix(): string;\n\n /** Backend write step; owns its metadata and error handling. */\n protected abstract writeObject(opts: IObjectLocation & { file: IUploadFile }): Promise<void>;\n\n /** The key `upload` writes when no naming hook is given: lowercase, spaces become `_`, under the folder when there is one. Public so a naming hook can start from the very key the helper would have written. */\n static normalizeObjectName(opts: { file: TUploadNaming }): string {\n const { originalName, folderPath } = opts.file;\n const normalizedFileName = originalName.toLowerCase().replace(/ /g, '_');\n\n if (!folderPath) {\n return normalizedFileName;\n }\n\n return `${folderPath.toLowerCase().replace(/ /g, '_')}/${normalizedFileName}`;\n }\n\n protected normalizeObjectLink(opts: IObjectLocation): string {\n const bucketName = opts.bucket.name;\n const encodedName = opts.object.key\n .split('/')\n .map((segment) => encodeURIComponent(segment))\n .join('/');\n\n return `${this.defaultLinkPrefix}${bucketName}/${encodedName}`;\n }\n\n /** An original name that is only metadata - the key is resolved elsewhere and validated on its own. */\n protected isValidOriginalName(opts: { name: string }): boolean {\n const { name } = opts;\n\n if (\n typeof name !== 'string' ||\n name.trim().length === 0 ||\n name.length > StorageLimits.MAX_SEGMENT_BYTES\n ) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error('Invalid original name: %s', EchoUtility.toSafeEcho({ value: name }));\n\n return false;\n }\n\n if (BaseStorageHelper.UNSAFE_NAME_CHARACTERS.test(name)) {\n this.logger\n .for(this.isValidOriginalName.name)\n .error(\n 'Original name contains a control character or a lone surrogate: %s',\n EchoUtility.toSafeEcho({ value: name }),\n );\n\n return false;\n }\n\n return true;\n }\n\n /** `isKeyResolvedByCaller`: a `normalizeNameFn` decides the key, so the original name is metadata and meets the metadata rule, not the key rule. */\n protected validateUploadFiles(opts: {\n files: IUploadFile[];\n maxFolderDepth?: number;\n isKeyResolvedByCaller?: boolean;\n }): void {\n const { files, maxFolderDepth, isKeyResolvedByCaller = false } = opts;\n\n for (const file of files) {\n this.validateUploadFile({ file, maxFolderDepth, isKeyResolvedByCaller });\n }\n }\n\n private validateUploadFile(opts: {\n file: IUploadFile;\n maxFolderDepth?: number;\n isKeyResolvedByCaller: boolean;\n }): void {\n const { file, maxFolderDepth, isKeyResolvedByCaller } = opts;\n const { originalName, size, folderPath } = file;\n\n const isNameValid = isKeyResolvedByCaller\n ? this.isValidOriginalName({ name: originalName })\n : this.isValidSegment({ segment: originalName });\n\n if (!isNameValid) {\n throw getError({ message: '[upload] Invalid original file name' });\n }\n\n // Checked against the CALLER's depth, before the body is spooled. `isValidKeyPath` measures an\n // object path (one folder deeper than a bare folderPath), so the depth is checked directly.\n if (folderPath) {\n const depthLimit = maxFolderDepth ?? BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH;\n const folderSegments = folderPath.replace(/^\\/+|\\/+$/g, '').split('/');\n\n if (folderSegments.length > depthLimit) {\n throw getError({\n error: StorageErrors.FOLDER_DEPTH_EXCEEDED,\n message: `[upload] Invalid folder path | depth: ${folderSegments.length} | max: ${depthLimit}`,\n });\n }\n\n if (!this.isValidKeyPath({ path: folderPath, maxDepth: depthLimit })) {\n throw getError({\n error: StorageErrors.FOLDER_PATH_INVALID,\n message: '[upload] Invalid folder path',\n });\n }\n }\n\n // Missing or negative is invalid; zero is a legitimate empty file.\n if (size === undefined || size === null || size < 0) {\n throw getError({ message: `[upload] Invalid file size | size: ${size}` });\n }\n }\n\n async upload(opts: IUploadOptions): Promise<IUploadResult[]> {\n const { bucket, files, normalizeNameFn, normalizeLinkFn, maxFolderDepth } = opts;\n const maxKeyDepth = opts.maxKeyDepth ?? maxFolderDepth;\n\n if (!files || files.length === 0) {\n return [];\n }\n\n const isExists = await this.hasBucket({ bucket });\n\n if (!isExists) {\n throw getError({\n message: `[upload] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n this.validateUploadFiles({\n files,\n maxFolderDepth,\n isKeyResolvedByCaller: normalizeNameFn !== undefined,\n });\n\n // Every key is resolved and validated before the first write, so one bad key stores nothing.\n const keys = files.map((file) => {\n const naming: TUploadNaming = {\n originalName: file.originalName,\n folderPath: file.folderPath,\n };\n const key = normalizeNameFn\n ? normalizeNameFn({ file: naming })\n : BaseStorageHelper.normalizeObjectName({ file: naming });\n\n if (!this.isValidObjectKey({ object: { key }, maxDepth: maxKeyDepth })) {\n throw getError({\n message: `[upload] Invalid normalized object name | name: ${EchoUtility.toSafeText({ value: key })}`,\n });\n }\n\n return key;\n });\n\n return this.mapWithConcurrency({\n items: files,\n task: async ({ item: file, index }) => {\n const { mimetype: mimeType, size, encoding } = file;\n const t = performance.now();\n const key = keys[index];\n\n const object: IObjectRef = { key };\n const link = normalizeLinkFn\n ? normalizeLinkFn({ bucket, object })\n : this.normalizeObjectLink({ bucket, object });\n\n await this.writeObject({ bucket, object, file });\n\n this.logger\n .for(this.upload.name)\n .info(\n 'Uploaded: %s | Took: %s (ms)',\n EchoUtility.toSafeEcho({ value: { key, link, mimeType, encoding, size } }),\n performance.now() - t,\n );\n\n return {\n bucket: { name: bucket.name },\n object: { key, size, contentType: mimeType },\n link,\n };\n },\n });\n }\n\n async getObjectStream(_opts: TObjectStreamOptions): Promise<ReadableStream<Uint8Array>> {\n throw this.unsupported({ operation: 'getObjectStream', feature: 'Streaming a read' });\n }\n\n /**\n * Correct anywhere, and the wrong path to stay on: it buffers, so a backend whose transport takes\n * a stream overrides it. `BunS3Helper` does.\n */\n async writeStream(opts: IWriteStreamOptions): Promise<void> {\n const { bucket, object, source, contentType } = opts;\n\n // The same depth rule `upload` applies, as `BunS3Helper.writeStream` does: one object, two doors, one answer.\n if (!this.isValidObjectKey({ object, maxDepth: opts.maxFolderDepth })) {\n throw getError({\n message: `[writeStream] Invalid object name | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n if (!this.isValidBucketName({ bucket })) {\n throw getError({\n message: `[storage] Invalid bucket name | bucket: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n // As `upload` does: a write never creates the bucket.\n const isExists = await this.hasBucket({ bucket });\n\n if (!isExists) {\n throw getError({\n message: `[writeStream] Bucket does not exist | name: ${EchoUtility.toSafeText({ value: bucket.name })}`,\n });\n }\n\n const body =\n source instanceof Response || source instanceof Request ? source : new Response(source);\n const result = await body.arrayBuffer();\n const buffer = Buffer.from(result);\n\n await this.writeObject({\n bucket,\n object,\n file: {\n originalName: object.key,\n mimetype: contentType ?? this.getMimeType({ filename: object.key }),\n buffer,\n size: buffer.length,\n },\n });\n }\n\n /** Bounded fan-out on the shared limiter; unbounded exhausts sockets and gets rate limited. */\n protected async mapWithConcurrency<Item, Result>(opts: {\n items: Item[];\n limit?: number;\n task: (taskOptions: { item: Item; index: number }) => Promise<Result>;\n }): Promise<Result[]> {\n const { items, task } = opts;\n\n if (items.length === 0) {\n return [];\n }\n\n return PromiseUtility.executeWithLimit({\n limit: Math.max(1, opts.limit ?? StorageConcurrency.DEFAULT_LIMIT),\n tasks: items.map((item, index) => () => task({ item, index })),\n });\n }\n\n /** A \"not there\" failure becomes a catalogued 404; every other failure passes through unchanged. */\n protected asStorageError(opts: IObjectLocation & { error: unknown; operation: string }): unknown {\n const { error, operation, bucket, object } = opts;\n\n if (!StorageUtility.isNotFoundError({ error })) {\n return error;\n }\n\n return getError({\n error: StorageErrors.OBJECT_NOT_FOUND,\n message: `[${operation}] Object not found | bucket: ${EchoUtility.toSafeText({ value: bucket.name })} | key: ${EchoUtility.toSafeText({ value: object.key })}`,\n });\n }\n\n /** For a backend with no ETag or versions to condition a read on: refusing is honest, ignoring would read unpinned. */\n protected refuseReadCondition(opts: { condition: IStorageReadCondition; operation: string }) {\n if (opts.condition.ifMatch !== undefined || opts.condition.versionId !== undefined) {\n throw this.unsupported({\n operation: opts.operation,\n feature: 'A conditional read (ifMatch, versionId)',\n });\n }\n }\n\n /** The error of an operation this helper has no transport for: throwing beats returning undefined, which reads as a valid empty result. */\n private unsupported(opts: { operation: string; feature: string }) {\n return getError({\n message: `[${this.constructor.name}.${opts.operation}] ${opts.feature} is not supported by this helper`,\n });\n }\n\n async copyObject(_opts: ICopyObjectOptions): Promise<void> {\n throw this.unsupported({ operation: 'copyObject', feature: 'Server-side copy' });\n }\n\n async presignPost(_opts: IPresignPostOptions): Promise<IPostPolicy> {\n throw this.unsupported({ operation: 'presignPost', feature: 'Signed POST policies' });\n }\n\n async presignPut(_opts: IPresignPutOptions): Promise<string> {\n throw this.unsupported({ operation: 'presignPut', feature: 'Presigned PUT URLs' });\n }\n\n async presignGet(_opts: IPresignGetOptions): Promise<string> {\n throw this.unsupported({ operation: 'presignGet', feature: 'Presigned GET URLs' });\n }\n\n async getObjectTags(_opts: IObjectLocation): Promise<Record<string, string>> {\n throw this.unsupported({ operation: 'getObjectTags', feature: 'Object tagging' });\n }\n\n async replaceObjectTags(\n _opts: IObjectLocation & { tags: Record<string, string> },\n ): Promise<void> {\n throw this.unsupported({ operation: 'replaceObjectTags', feature: 'Object tagging' });\n }\n\n abstract hasBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n abstract getBuckets(): Promise<IBucketInfo[]>;\n abstract getBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract createBucket(opts: { bucket: IBucketRef }): Promise<IBucketInfo | null>;\n abstract removeBucket(opts: { bucket: IBucketRef }): Promise<boolean>;\n\n abstract getObject(opts: IObjectLocation & { options?: unknown }): Promise<Readable>;\n abstract getStat(opts: IObjectLocation): Promise<IFileStat>;\n abstract removeObject(opts: IObjectLocation): Promise<void>;\n abstract removeObjects(opts: { bucket: IBucketRef; objects: IObjectRef[] }): Promise<void>;\n abstract listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;\n}\n"]}
@@ -1,7 +1,6 @@
1
- import type { IDuration } from '../../../common/index.js';
2
1
  import { Readable } from 'node:stream';
3
2
  import { BaseStorageHelper } from '../base.js';
4
- import type { IBucketInfo, IBucketRef, IFileStat, IListObjectsOptions, IObjectInfo, IObjectLocation, IObjectRef, IPostPolicy, IStorageHelperOptions, IUploadFile } from '../common/index.js';
3
+ import type { IBucketInfo, IBucketRef, ICopyObjectOptions, IFileStat, IListObjectsOptions, IObjectInfo, IObjectLocation, IObjectRef, IPostPolicy, IPresignGetOptions, IPresignPostOptions, IPresignPutOptions, IStorageHelperOptions, IUploadFile, IWriteStreamOptions, TObjectStreamOptions } from '../common/index.js';
5
4
  /** Options for `BunS3Helper`. Unset `partSize`, `queueSize` and `retry` leave Bun defaults in force. */
6
5
  export interface IBunS3HelperOptions extends IStorageHelperOptions {
7
6
  accessKey: string;
@@ -58,27 +57,10 @@ export declare class BunS3Helper extends BaseStorageHelper {
58
57
  removeBucket(opts: {
59
58
  bucket: IBucketRef;
60
59
  }): Promise<boolean>;
61
- copyObject(opts: {
62
- bucket: IBucketRef;
63
- source: IObjectRef;
64
- destination: IObjectRef;
65
- }): Promise<void>;
66
- presignPost(opts: IObjectLocation & {
67
- maxBytes: number;
68
- contentType?: string;
69
- expiresIn?: IDuration;
70
- }): Promise<IPostPolicy>;
71
- presignPut(opts: IObjectLocation & {
72
- expiresIn?: IDuration;
73
- tagging?: Record<string, string>;
74
- contentLength?: number;
75
- contentType?: string;
76
- }): Promise<string>;
77
- presignGet(opts: IObjectLocation & {
78
- expiresIn?: IDuration;
79
- responseContentType?: string;
80
- responseContentDisposition?: string;
81
- }): Promise<string>;
60
+ copyObject(opts: ICopyObjectOptions): Promise<void>;
61
+ presignPost(opts: IPresignPostOptions): Promise<IPostPolicy>;
62
+ presignPut(opts: IPresignPutOptions): Promise<string>;
63
+ presignGet(opts: IPresignGetOptions): Promise<string>;
82
64
  getObjectTags(opts: IObjectLocation): Promise<Record<string, string>>;
83
65
  replaceObjectTags(opts: IObjectLocation & {
84
66
  tags: Record<string, string>;
@@ -88,22 +70,26 @@ export declare class BunS3Helper extends BaseStorageHelper {
88
70
  file: IUploadFile;
89
71
  }): Promise<void>;
90
72
  /** Streams without holding the object in memory. `upload` carries a `Buffer`, so it cannot; this is the path for anything large. */
91
- writeStream(opts: IObjectLocation & {
92
- source: ReadableStream<Uint8Array> | Blob | Response | Request;
93
- contentType?: string;
94
- maxFolderDepth?: number;
95
- }): Promise<void>;
73
+ writeStream(opts: IWriteStreamOptions): Promise<void>;
96
74
  /** `S3File.stream()` is lazy: it reaches the network on first read, so a `try` here never sees a 404 - the failure arrives on the stream. */
97
75
  getObject(opts: IObjectLocation & {
98
- options?: any;
76
+ options?: unknown;
99
77
  }): Promise<Readable>;
100
78
  /** The conversion-free path a `Response` body wants. `slice` makes it a ranged GET, so only the requested bytes leave S3. */
101
- getObjectStream(opts: IObjectLocation & {
102
- range?: {
103
- start: number;
104
- end?: number;
105
- };
106
- }): Promise<ReadableStream<Uint8Array>>;
79
+ getObjectStream(opts: TObjectStreamOptions): Promise<ReadableStream<Uint8Array>>;
80
+ /** The ETag with the quotes S3 sends and expects in `If-Match`. */
81
+ private static quoteEtag;
82
+ /** Signs and sends one request: the one place credentials, signing and the verb's case meet. */
83
+ private send;
84
+ /** A bucket operation is a call this process makes, so it goes to the default host. */
85
+ private bucketFetch;
86
+ /** One object-level request, addressed in the configured style on the host this process talks to. */
87
+ private signedFetch;
88
+ /** The storage error a response stands for: 412 is a changed object, 404 a missing one, any other failure the backend's own. */
89
+ private assertObjectResponse;
90
+ /** `S3File` cannot send `If-Match` or a version id, so a conditional read is a signed GET. */
91
+ private getConditionalStream;
92
+ /** A signed HEAD rather than `client.stat`, because Bun's stat does not report the version id a pin needs. */
107
93
  getStat(opts: IObjectLocation): Promise<IFileStat>;
108
94
  removeObject(opts: IObjectLocation): Promise<void>;
109
95
  removeObjects(opts: {