@bymax-one/nest-storage 1.1.18 → 1.1.20

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.
@@ -7,15 +7,24 @@ var stream = require('stream');
7
7
  var s3RequestPresigner = require('@aws-sdk/s3-request-presigner');
8
8
  var crypto = require('crypto');
9
9
 
10
+ var __defProp = Object.defineProperty;
10
11
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
12
+ var __typeError = (msg) => {
13
+ throw TypeError(msg);
14
+ };
11
15
  var __decorateClass = (decorators, target, key, kind) => {
12
16
  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
13
17
  for (var i = decorators.length - 1, decorator; i >= 0; i--)
14
18
  if (decorator = decorators[i])
15
- result = (decorator(result)) || result;
19
+ result = (kind ? decorator(target, key, result) : decorator(result)) || result;
20
+ if (kind && result) __defProp(target, key, result);
16
21
  return result;
17
22
  };
18
23
  var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
24
+ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
25
+ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
26
+ var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
27
+ var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), member.set(obj, value), value);
19
28
 
20
29
  // src/server/bymax-storage.constants.ts
21
30
  var BYMAX_STORAGE_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_STORAGE_OPTIONS");
@@ -121,7 +130,7 @@ var STORAGE_ERROR_STATUS = {
121
130
  // src/server/errors/storage-exception.ts
122
131
  var StorageException = class extends common.HttpException {
123
132
  code;
124
- constructor(code, statusCode = STORAGE_ERROR_STATUS[code], details, message = STORAGE_ERROR_MESSAGES[code]) {
133
+ constructor(code, statusCode = STORAGE_ERROR_STATUS[code], details, message = STORAGE_ERROR_MESSAGES[code], cause) {
125
134
  super(
126
135
  {
127
136
  error: {
@@ -130,7 +139,8 @@ var StorageException = class extends common.HttpException {
130
139
  ...details ? { details } : {}
131
140
  }
132
141
  },
133
- statusCode
142
+ statusCode,
143
+ { cause }
134
144
  );
135
145
  this.code = code;
136
146
  }
@@ -144,9 +154,9 @@ var HEADER_VALUE = /^[\t \x21-\x7E]*$/;
144
154
  var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
145
155
  var VALUE_REASON = "must be a string of tab, space and printable ASCII characters";
146
156
  var KEY_REASON = "every key must be a non-empty header name of letters, digits and the characters !#$%&'*+-.^_`|~";
147
- function refuse(field2, reason) {
157
+ function refuse(field, reason) {
148
158
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
149
- field: field2,
159
+ field,
150
160
  reason
151
161
  });
152
162
  }
@@ -154,9 +164,9 @@ function isHeaderValue(value) {
154
164
  return typeof value === "string" && HEADER_VALUE.test(value);
155
165
  }
156
166
  function assertHeaderValues(fields) {
157
- for (const [field2, value] of Object.entries(fields)) {
167
+ for (const [field, value] of Object.entries(fields)) {
158
168
  if (value !== void 0 && !isHeaderValue(value)) {
159
- refuse(field2, VALUE_REASON);
169
+ refuse(field, VALUE_REASON);
160
170
  }
161
171
  }
162
172
  }
@@ -174,15 +184,31 @@ function assertMetadata(metadata) {
174
184
  }
175
185
  }
176
186
 
187
+ // src/server/config/option-array-bound.ts
188
+ var MAX_OPTION_ARRAY_LENGTH = 1e3;
189
+ function isBoundedLength(length) {
190
+ return typeof length === "number" && Number.isInteger(length) && length >= 0 && length <= MAX_OPTION_ARRAY_LENGTH;
191
+ }
192
+
177
193
  // src/server/config/validate-options.ts
178
194
  var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
179
195
  var MAX_PART_SIZE_BYTES = 5 * 1024 * 1024 * 1024;
180
196
  var MAX_QUEUE_SIZE = 1e3;
181
197
  var REGION_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
198
+ var OWN_REFUSALS = /* @__PURE__ */ new WeakSet();
199
+ function isOwnRefusal(error) {
200
+ return typeof error === "object" && error !== null && OWN_REFUSALS.has(error);
201
+ }
182
202
  function invalid(reason) {
183
- return new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG, common.HttpStatus.INTERNAL_SERVER_ERROR, {
184
- reason
185
- });
203
+ const refusal = new StorageException(
204
+ STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG,
205
+ common.HttpStatus.INTERNAL_SERVER_ERROR,
206
+ {
207
+ reason
208
+ }
209
+ );
210
+ OWN_REFUSALS.add(refusal);
211
+ return refusal;
186
212
  }
187
213
  function isObject(value) {
188
214
  return typeof value === "object" && value !== null;
@@ -253,15 +279,43 @@ function assertValidationKinds(validation) {
253
279
  if (mimeWhitelist === null) {
254
280
  throw invalid("validation.mimeWhitelist must not be null; omit it to allow every type");
255
281
  }
256
- if (mimeWhitelist !== void 0 && (!Array.isArray(mimeWhitelist) || !Array.from(mimeWhitelist).every((entry) => typeof entry === "string"))) {
282
+ assertBoundedArray("mimeWhitelist", mimeWhitelist);
283
+ if (mimeWhitelist !== void 0 && !isStringArray(mimeWhitelist)) {
257
284
  throw invalid("validation.mimeWhitelist must be an array of strings");
258
285
  }
259
286
  if (customValidators === null) {
260
- throw invalid("validation.customValidators must not be null; omit it to run no custom validator");
287
+ throw invalid(
288
+ "validation.customValidators must not be null; omit it to run no custom validator"
289
+ );
261
290
  }
262
291
  if (customValidators !== void 0 && !Array.isArray(customValidators)) {
263
292
  throw invalid("validation.customValidators must be an array");
264
293
  }
294
+ assertBoundedArray("customValidators", customValidators);
295
+ if (customValidators !== void 0 && !isValidatorList(customValidators)) {
296
+ throw invalid("validation.customValidators must hold objects with a validate function");
297
+ }
298
+ }
299
+ function assertBoundedArray(name, value) {
300
+ if (Array.isArray(value) && !isBoundedLength(value.length)) {
301
+ throw invalid(`validation.${name} must hold at most ${String(MAX_OPTION_ARRAY_LENGTH)} entries`);
302
+ }
303
+ }
304
+ function isStringArray(value) {
305
+ return Array.isArray(value) && Array.from(value).every((entry) => typeof entry === "string");
306
+ }
307
+ function isValidatorList(entries) {
308
+ return Array.from(entries).every(
309
+ (entry) => isObject(entry) && typeof entry.validate === "function"
310
+ );
311
+ }
312
+ function assertGroupKinds(options) {
313
+ for (const group of ["signedUrls", "multipart", "validation"]) {
314
+ const value = options[group];
315
+ if (value !== void 0 && value !== null && (!isObject(value) || Array.isArray(value))) {
316
+ throw invalid(`options.${group} must be an object`);
317
+ }
318
+ }
265
319
  }
266
320
  function assertNumericSections(options) {
267
321
  const MAX = Number.MAX_SAFE_INTEGER;
@@ -279,6 +333,7 @@ function assertNumericSections(options) {
279
333
  assertBoundedInteger(options.multipart, "multipart", "queueSize", { min: 1, max: MAX_QUEUE_SIZE });
280
334
  }
281
335
  function assertLimitsAndEncryption(options) {
336
+ assertGroupKinds(options);
282
337
  assertNumericSections(options);
283
338
  assertValidationKinds(options.validation);
284
339
  assertScanner(options.scanner);
@@ -292,6 +347,11 @@ function assertLimitsAndEncryption(options) {
292
347
  if (options.serverSideEncryption === "aws:kms" && !options.kmsKeyId) {
293
348
  throw invalid('kmsKeyId is required when serverSideEncryption === "aws:kms"');
294
349
  }
350
+ for (const name of ["defaultPublicRead", "forcePathStyle"]) {
351
+ if (options[name] !== void 0 && typeof options[name] !== "boolean") {
352
+ throw invalid(`options.${name} must be a boolean`);
353
+ }
354
+ }
295
355
  for (const name of ["defaultCacheControl", "kmsKeyId"]) {
296
356
  if (options[name] !== void 0 && !isHeaderValue(options[name])) {
297
357
  throw invalid(`options.${name} must be a string of tab, space and printable ASCII characters`);
@@ -328,6 +388,9 @@ function validateOptions(options) {
328
388
  if (!isObject(options.credentials)) {
329
389
  throw invalid("options.credentials is required");
330
390
  }
391
+ if (Array.isArray(options.credentials)) {
392
+ throw invalid("options.credentials must be an object");
393
+ }
331
394
  assertLimitsAndEncryption(options);
332
395
  }
333
396
 
@@ -474,15 +537,10 @@ function pick(source, keys) {
474
537
  return copy;
475
538
  }
476
539
  function pickGroup(value, keys) {
477
- return isObject2(value) ? pick(value, keys) : value;
540
+ return isObject2(value) && !Array.isArray(value) ? pick(value, keys) : value;
478
541
  }
479
542
  function copyArray(value) {
480
- if (!Array.isArray(value)) return value;
481
- try {
482
- return Array.from(value);
483
- } catch {
484
- return value;
485
- }
543
+ return Array.isArray(value) && isBoundedLength(value.length) ? Array.from(value) : value;
486
544
  }
487
545
  var GROUPS = {
488
546
  credentials: CREDENTIAL_KEYS,
@@ -506,16 +564,36 @@ function snapshotOptions(options) {
506
564
  return copy;
507
565
  }
508
566
 
509
- // src/server/utils/describe-endpoint.ts
510
- function describeEndpoint(endpoint) {
567
+ // src/server/utils/absorb.ts
568
+ function absorb(call) {
511
569
  try {
512
- const url = new URL(endpoint);
513
- return `${url.protocol}//${url.host}`;
570
+ void Promise.resolve(call()).then(void 0, () => void 0);
514
571
  } catch {
515
- return "<unparseable endpoint>";
516
572
  }
517
573
  }
518
574
 
575
+ // src/server/utils/log-event.ts
576
+ function emit(sink, level, entry) {
577
+ absorb(() => sink[level](entry));
578
+ }
579
+
580
+ // src/server/utils/log-events.ts
581
+ var STORAGE_LOG_EVENTS = {
582
+ ttlClamped: "STORAGE_TTL_CLAMPED",
583
+ credentialsMissing: "STORAGE_CREDENTIALS_MISSING",
584
+ clientReady: "STORAGE_CLIENT_READY",
585
+ providerCallFailed: "STORAGE_PROVIDER_CALL_FAILED",
586
+ multipartAbortFailed: "STORAGE_MULTIPART_ABORT_FAILED",
587
+ scanInfected: "STORAGE_SCAN_INFECTED",
588
+ scanInconclusiveAccepted: "STORAGE_SCAN_INCONCLUSIVE_ACCEPTED",
589
+ scanInconclusiveRejected: "STORAGE_SCAN_INCONCLUSIVE_REJECTED",
590
+ scanFailed: "STORAGE_SCAN_FAILED",
591
+ scanTimeout: "STORAGE_SCAN_TIMEOUT",
592
+ scanCleanupFailed: "STORAGE_SCAN_CLEANUP_FAILED",
593
+ existsFailed: "STORAGE_EXISTS_FAILED",
594
+ deleteNotFound: "STORAGE_DELETE_NOT_FOUND"
595
+ };
596
+
519
597
  // src/server/providers/s3-client.provider.ts
520
598
  var S3ClientProvider = class {
521
599
  constructor(options) {
@@ -526,9 +604,10 @@ var S3ClientProvider = class {
526
604
  client;
527
605
  onModuleInit() {
528
606
  if (!this.options.hasCredentials) {
529
- this.logger.warn(
530
- "Storage credentials are missing \u2014 module is registered but operations will throw STORAGE_NOT_CONFIGURED."
531
- );
607
+ emit(this.logger, "warn", {
608
+ event: STORAGE_LOG_EVENTS.credentialsMissing,
609
+ message: "Storage credentials are missing \u2014 module is registered but operations will throw STORAGE_NOT_CONFIGURED."
610
+ });
532
611
  return;
533
612
  }
534
613
  this.resolveClient();
@@ -601,9 +680,10 @@ var S3ClientProvider = class {
601
680
  requestChecksumCalculation: this.options.requestChecksumCalculation,
602
681
  responseChecksumValidation: this.options.responseChecksumValidation
603
682
  };
604
- this.logger.log(
605
- `S3Client initialized: endpoint=${describeEndpoint(this.options.endpoint)} region=${this.options.region}`
606
- );
683
+ emit(this.logger, "log", {
684
+ event: STORAGE_LOG_EVENTS.clientReady,
685
+ message: "S3Client initialized"
686
+ });
607
687
  return new clientS3.S3Client(config);
608
688
  }
609
689
  };
@@ -672,11 +752,260 @@ KeyResolverService = __decorateClass([
672
752
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS))
673
753
  ], KeyResolverService);
674
754
 
755
+ // src/server/observability/storage-operations.ts
756
+ var STORAGE_OPERATIONS = [
757
+ "upload",
758
+ "download",
759
+ "head",
760
+ "delete",
761
+ "delete_many",
762
+ "list",
763
+ "copy",
764
+ "get_download_url",
765
+ "get_upload_url",
766
+ "get_multipart_upload_urls",
767
+ "check_bucket",
768
+ "lifecycle_get",
769
+ "lifecycle_upsert",
770
+ "lifecycle_remove"
771
+ ];
772
+ var STORAGE_OUTCOMES = ["success", "not_found", "aborted", "error"];
773
+ var SCAN_VERDICTS = ["clean", "infected", "unknown", "timeout", "error"];
774
+ function outcomeOf(error) {
775
+ if (!(error instanceof StorageException)) return "error";
776
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) return "not_found";
777
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED || error.code === STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED) {
778
+ return "aborted";
779
+ }
780
+ return "error";
781
+ }
782
+ function scanVerdictOfError(error) {
783
+ if (!(error instanceof StorageException)) return "error";
784
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_SCAN_INFECTED) return "infected";
785
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_SCAN_INCONCLUSIVE) return "unknown";
786
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_TIMEOUT) return "timeout";
787
+ return "error";
788
+ }
789
+
790
+ // src/server/observability/storage-metrics-tally.ts
791
+ function zeroed(keys) {
792
+ return Object.fromEntries(keys.map((key) => [key, 0]));
793
+ }
794
+ var _operations, _scans, _listeners, _bytesUploaded;
795
+ exports.StorageMetricsTally = class StorageMetricsTally {
796
+ constructor() {
797
+ __privateAdd(this, _operations, Object.fromEntries(
798
+ STORAGE_OPERATIONS.map((operation) => [operation, zeroed(STORAGE_OUTCOMES)])
799
+ ));
800
+ __privateAdd(this, _scans, zeroed(SCAN_VERDICTS));
801
+ __privateAdd(this, _listeners, []);
802
+ __privateAdd(this, _bytesUploaded, 0);
803
+ }
804
+ /** An operation ended as `outcome` after `seconds`. */
805
+ operation(operation, outcome, seconds) {
806
+ __privateGet(this, _operations)[operation][outcome] += 1;
807
+ for (const listener of __privateGet(this, _listeners)) absorb(() => listener(operation, seconds));
808
+ }
809
+ /**
810
+ * `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. The
811
+ * count stops at the largest finite number: a sum of two finite sizes can overflow to `Infinity`, which no
812
+ * counter accepts, and a scrape that read it would fail whole.
813
+ */
814
+ bytesUploaded(bytes) {
815
+ if (typeof bytes === "number" && Number.isFinite(bytes) && bytes > 0)
816
+ __privateSet(this, _bytesUploaded, Math.min(__privateGet(this, _bytesUploaded) + bytes, Number.MAX_VALUE));
817
+ }
818
+ /** A scan ended as `verdict`. */
819
+ scan(verdict) {
820
+ __privateGet(this, _scans)[verdict] += 1;
821
+ }
822
+ /** Calls `listener` with the duration of every operation that ends from now on. */
823
+ onDuration(listener) {
824
+ __privateGet(this, _listeners).push(listener);
825
+ }
826
+ /** The counts so far, as copies. */
827
+ snapshot() {
828
+ return {
829
+ operations: Object.fromEntries(
830
+ STORAGE_OPERATIONS.map((operation) => [operation, { ...__privateGet(this, _operations)[operation] }])
831
+ ),
832
+ bytesUploaded: __privateGet(this, _bytesUploaded),
833
+ scans: { ...__privateGet(this, _scans) }
834
+ };
835
+ }
836
+ };
837
+ _operations = new WeakMap();
838
+ _scans = new WeakMap();
839
+ _listeners = new WeakMap();
840
+ _bytesUploaded = new WeakMap();
841
+ exports.StorageMetricsTally = __decorateClass([
842
+ common.Injectable()
843
+ ], exports.StorageMetricsTally);
844
+ var STATUS_ERROR = 2;
845
+ var TRACER_NAME = "@bymax-one/nest-storage";
846
+ var LIBRARY_CODE = /^STORAGE_[A-Z_]+$/;
847
+ function codeOf(error) {
848
+ if (!(error instanceof StorageException)) return "STORAGE_ERROR";
849
+ return LIBRARY_CODE.test(error.code) ? error.code : "STORAGE_ERROR";
850
+ }
851
+ var _api;
852
+ var StorageTracing = class {
853
+ constructor() {
854
+ __privateAdd(this, _api);
855
+ }
856
+ /** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
857
+ async onModuleInit() {
858
+ try {
859
+ const loaded = await import('@opentelemetry/api');
860
+ __privateSet(this, _api, loaded);
861
+ } catch {
862
+ }
863
+ }
864
+ /** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
865
+ async traced(span, run, describe) {
866
+ let result;
867
+ try {
868
+ result = await run();
869
+ } catch (error) {
870
+ absorb(() => span.setAttributes({ "bymax.storage.outcome": outcomeOf(error) }));
871
+ absorb(() => span.setStatus({ code: STATUS_ERROR, message: codeOf(error) }));
872
+ absorb(() => span.end());
873
+ throw error;
874
+ }
875
+ absorb(() => span.setAttributes({ "bymax.storage.outcome": "success", ...describe(result) }));
876
+ absorb(() => span.end());
877
+ return result;
878
+ }
879
+ /**
880
+ * Runs `run` inside a span named `name`.
881
+ *
882
+ * The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
883
+ * throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
884
+ * otherwise, and its own result or error is what comes back.
885
+ *
886
+ * @param name - One of the library's span names.
887
+ * @param attributes - Closed-set attributes of the span.
888
+ * @param run - The operation; its result or its error passes through unchanged.
889
+ * @param describe - What the span states of a successful result; a throw of its own is the operation's own.
890
+ */
891
+ span(name, attributes, run, describe = () => ({})) {
892
+ const api = __privateGet(this, _api);
893
+ if (!api) return run();
894
+ const latch = { claimed: false };
895
+ absorb(
896
+ () => api.trace.getTracer(TRACER_NAME).startActiveSpan(name, { attributes }, (span) => {
897
+ if (!latch.claimed) {
898
+ latch.claimed = true;
899
+ latch.started = this.traced(span, run, describe);
900
+ }
901
+ return latch.started;
902
+ })
903
+ );
904
+ if (latch.started) return latch.started;
905
+ latch.claimed = true;
906
+ return run();
907
+ }
908
+ };
909
+ _api = new WeakMap();
910
+ StorageTracing = __decorateClass([
911
+ common.Injectable()
912
+ ], StorageTracing);
913
+
914
+ // src/server/observability/storage-observer.ts
915
+ function secondsSince(startedAt) {
916
+ return Number(process.hrtime.bigint() - startedAt) / 1e9;
917
+ }
918
+ var StorageObserver = class {
919
+ constructor(tally, tracing) {
920
+ this.tally = tally;
921
+ this.tracing = tracing;
922
+ }
923
+ tally;
924
+ tracing;
925
+ /**
926
+ * Runs `run`, counting how it ended and how long it took.
927
+ *
928
+ * @param operation - The operation, one of the closed set.
929
+ * @param run - The operation; its result or its error passes through unchanged.
930
+ * @param options - A span to start, and what to state of the result.
931
+ */
932
+ observe(operation, run, options = {}) {
933
+ const counted = async () => {
934
+ const startedAt = process.hrtime.bigint();
935
+ let result;
936
+ try {
937
+ result = await run();
938
+ } catch (error) {
939
+ absorb(() => {
940
+ this.tally.operation(operation, outcomeOf(error), secondsSince(startedAt));
941
+ });
942
+ throw error;
943
+ }
944
+ absorb(() => {
945
+ this.tally.operation(operation, "success", secondsSince(startedAt));
946
+ this.tally.bytesUploaded(options.bytes?.(result));
947
+ });
948
+ return result;
949
+ };
950
+ return options.span === void 0 ? counted() : this.tracing.span(options.span, options.attributes ?? {}, counted, options.describe);
951
+ }
952
+ /**
953
+ * Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
954
+ *
955
+ * @param mode - When the scan runs, `pre-upload` or `post-upload`.
956
+ * @param run - The scan; its result or its error passes through unchanged.
957
+ */
958
+ scan(mode, run) {
959
+ const counted = async () => {
960
+ try {
961
+ const result = await run();
962
+ absorb(() => {
963
+ this.tally.scan(result.status === "unknown" ? "unknown" : "clean");
964
+ });
965
+ return result;
966
+ } catch (error) {
967
+ absorb(() => {
968
+ this.tally.scan(scanVerdictOfError(error));
969
+ });
970
+ throw error;
971
+ }
972
+ };
973
+ return this.tracing.span("storage.scan", { "bymax.storage.scan_mode": mode }, counted);
974
+ }
975
+ };
976
+ StorageObserver = __decorateClass([
977
+ common.Injectable(),
978
+ __decorateParam(0, common.Inject(exports.StorageMetricsTally)),
979
+ __decorateParam(1, common.Inject(StorageTracing))
980
+ ], StorageObserver);
981
+ function Observed(operation, options = {}) {
982
+ return (_target, _key, descriptor) => {
983
+ const original = descriptor.value;
984
+ descriptor.value = function(...args) {
985
+ const run = () => original.apply(this, args);
986
+ return this.observer === void 0 ? run() : this.observer.observe(operation, run, options);
987
+ };
988
+ };
989
+ }
990
+
991
+ // src/server/utils/call-details.ts
992
+ var MAX_CALLER_TEXT_LENGTH = 1024;
993
+ function callerFields(given) {
994
+ const fields = {};
995
+ for (const [field, value] of Object.entries(given)) {
996
+ if (typeof value === "string" && value.length <= MAX_CALLER_TEXT_LENGTH) fields[field] = value;
997
+ }
998
+ return fields;
999
+ }
1000
+ function callDetails(op, given, extra = {}) {
1001
+ return { ...callerFields(given), op, ...extra };
1002
+ }
1003
+
675
1004
  // src/server/utils/call-input.ts
676
- function wrongKind(field2, needs) {
1005
+ function wrongKind(field, needs) {
677
1006
  return new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
678
- field: field2,
679
- reason: `${field2} must be ${needs}`
1007
+ field,
1008
+ reason: `${field} must be ${needs}`
680
1009
  });
681
1010
  }
682
1011
  function resolveBucket(perCall, moduleDefault) {
@@ -704,64 +1033,6 @@ function hasSignalSurface(signal) {
704
1033
  return false;
705
1034
  }
706
1035
  }
707
-
708
- // src/server/utils/describe-error.ts
709
- var NON_PRINTABLE_REJECTION = "non-printable rejection value";
710
- function describeError(value) {
711
- try {
712
- if (typeof value === "object" && value !== null) {
713
- const message = value.message;
714
- if (typeof message === "string") {
715
- return message;
716
- }
717
- }
718
- return String(value);
719
- } catch {
720
- return NON_PRINTABLE_REJECTION;
721
- }
722
- }
723
-
724
- // src/server/utils/log-value.ts
725
- var LEFT_LITERAL_BY_JSON = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
726
- function logValue(value) {
727
- const text = typeof value === "string" ? value : describeError(value);
728
- return JSON.stringify(text).replace(
729
- LEFT_LITERAL_BY_JSON,
730
- (char) => {
731
- const codePoint = Number(char.codePointAt(0));
732
- const hex = codePoint.toString(16);
733
- return codePoint > 65535 ? `\\u{${hex}}` : `\\u${hex.padStart(4, "0")}`;
734
- }
735
- );
736
- }
737
-
738
- // src/server/utils/provider-failure-log.ts
739
- var SECRET_IN_MESSAGE = /(X-Amz-(?:Signature|Credential|Security-Token)|AWSAccessKeyId|Credential|Signature)=[^&\s"']+/gi;
740
- var BARE_ACCESS_KEY_ID = /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
741
- var MAX_MESSAGE_LENGTH = 300;
742
- var logger = new common.Logger("StorageProvider");
743
- function field(value) {
744
- return typeof value === "string" || typeof value === "number" ? logValue(value) : "-";
745
- }
746
- function describeProviderFailure(err) {
747
- const failure = typeof err === "object" && err !== null ? err : {};
748
- const message = describeError(err).replace(SECRET_IN_MESSAGE, "$1=[redacted]").replace(BARE_ACCESS_KEY_ID, "[redacted-key-id]");
749
- return [
750
- `name=${field(failure.name)}`,
751
- `code=${field(failure.Code)}`,
752
- `status=${field(failure.$metadata?.httpStatusCode)}`,
753
- `requestId=${field(failure.$metadata?.requestId)}`,
754
- `message=${logValue(message.slice(0, MAX_MESSAGE_LENGTH))}`
755
- ].join(" ");
756
- }
757
- function logProviderFailure(err, context, label = "Provider call failed") {
758
- if (err?.name === "AbortError") {
759
- return;
760
- }
761
- const op = typeof context?.op === "string" ? logValue(context.op) : "-";
762
- const key = typeof context?.key === "string" ? logValue(context.key) : "-";
763
- logger.warn(`${label}: op=${op} key=${key} ${describeProviderFailure(err)}`);
764
- }
765
1036
  var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
766
1037
  "ECONNREFUSED",
767
1038
  "ECONNRESET",
@@ -828,6 +1099,106 @@ function providerFailureStatus(err) {
828
1099
  return failure === "credentials-refused" ? common.HttpStatus.INTERNAL_SERVER_ERROR : void 0;
829
1100
  }
830
1101
 
1102
+ // src/server/utils/cut-text.ts
1103
+ function cutText(text, max) {
1104
+ if (text.length <= max) return text;
1105
+ const lastKept = text.charCodeAt(max - 1);
1106
+ const splitsPair = lastKept >= 55296 && lastKept <= 56319;
1107
+ return text.slice(0, splitsPair ? max - 1 : max);
1108
+ }
1109
+
1110
+ // src/server/utils/describe-error.ts
1111
+ var NON_PRINTABLE_REJECTION = "non-printable rejection value";
1112
+ function describeError(value) {
1113
+ try {
1114
+ if (typeof value === "object" && value !== null) {
1115
+ const message = value.message;
1116
+ if (typeof message === "string") {
1117
+ return message;
1118
+ }
1119
+ }
1120
+ return String(value);
1121
+ } catch {
1122
+ return NON_PRINTABLE_REJECTION;
1123
+ }
1124
+ }
1125
+
1126
+ // src/server/utils/log-value.ts
1127
+ var LEFT_LITERAL_BY_JSON = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/gu;
1128
+ var SHORT_ESCAPES = {
1129
+ "\b": "\\b",
1130
+ "\f": "\\f",
1131
+ "\n": "\\n",
1132
+ "\r": "\\r",
1133
+ " ": "\\t"
1134
+ };
1135
+ function escapeChar(char) {
1136
+ const short = SHORT_ESCAPES[char];
1137
+ if (short !== void 0) return short;
1138
+ const codePoint = Number(char.codePointAt(0));
1139
+ const hex = codePoint.toString(16);
1140
+ return codePoint > 65535 ? `\\u{${hex}}` : `\\u${hex.padStart(4, "0")}`;
1141
+ }
1142
+ function escapeForLog(text) {
1143
+ return text.replace(LEFT_LITERAL_BY_JSON, escapeChar);
1144
+ }
1145
+
1146
+ // src/server/utils/provider-failure-log.ts
1147
+ var SECRET_IN_MESSAGE = /(X-Amz-(?:Signature|Credential|Security-Token)|AWSAccessKeyId|Credential|Signature)=[^&\s"']+/gi;
1148
+ var BARE_ACCESS_KEY_ID = /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
1149
+ var MAX_MESSAGE_LENGTH = 300;
1150
+ var logger = new common.Logger("StorageProvider");
1151
+ var MAX_FIELD_LENGTH = 128;
1152
+ function readOrUndefined(read) {
1153
+ try {
1154
+ return read();
1155
+ } catch {
1156
+ return void 0;
1157
+ }
1158
+ }
1159
+ function textField(value) {
1160
+ return typeof value === "string" ? escapeForLog(cutText(value, MAX_FIELD_LENGTH)) : void 0;
1161
+ }
1162
+ function projectProviderFailure(err) {
1163
+ const failure = typeof err === "object" && err !== null ? err : {};
1164
+ const message = describeError(err).replace(SECRET_IN_MESSAGE, "$1=[redacted]").replace(BARE_ACCESS_KEY_ID, "[redacted-key-id]");
1165
+ const status = readOrUndefined(() => failure.$metadata?.httpStatusCode);
1166
+ const name = textField(readOrUndefined(() => failure.name));
1167
+ const awsCode = textField(readOrUndefined(() => failure.Code));
1168
+ const requestId = textField(readOrUndefined(() => failure.$metadata?.requestId));
1169
+ return {
1170
+ ...name !== void 0 ? { name } : {},
1171
+ ...awsCode !== void 0 ? { awsCode } : {},
1172
+ ...typeof status === "number" ? { httpStatus: status } : {},
1173
+ ...requestId !== void 0 ? { requestId } : {},
1174
+ message: escapeForLog(cutText(message, MAX_MESSAGE_LENGTH))
1175
+ };
1176
+ }
1177
+ function failureError(err) {
1178
+ const view = projectProviderFailure(err);
1179
+ const error = new Error(view.message);
1180
+ if (view.name !== void 0) error.name = view.name;
1181
+ if (view.awsCode !== void 0)
1182
+ Object.defineProperty(error, "awsCode", { value: view.awsCode, enumerable: true });
1183
+ return error;
1184
+ }
1185
+ function logProviderFailure(err, context, label = "Provider call failed") {
1186
+ if (readOrUndefined(() => err?.name) === "AbortError") {
1187
+ return;
1188
+ }
1189
+ const view = projectProviderFailure(err);
1190
+ emit(logger, "warn", {
1191
+ event: STORAGE_LOG_EVENTS.providerCallFailed,
1192
+ message: label,
1193
+ ...typeof context?.op === "string" ? { operation: escapeForLog(context.op) } : {},
1194
+ ...view.awsCode !== void 0 ? { awsCode: view.awsCode } : {},
1195
+ ...view.httpStatus !== void 0 ? { httpStatus: view.httpStatus } : {},
1196
+ ...view.requestId !== void 0 ? { requestId: view.requestId } : {},
1197
+ reason: readOrUndefined(() => providerFailureReason(err)) ?? "rejected",
1198
+ err: failureError(err)
1199
+ });
1200
+ }
1201
+
831
1202
  // src/server/errors/aws-error-mapper.ts
832
1203
  function awsCodeOf(err) {
833
1204
  const e = err ?? {};
@@ -947,54 +1318,32 @@ function ruleInvalid(reason) {
947
1318
  reason
948
1319
  });
949
1320
  }
950
- function assertDays(field2, value) {
1321
+ function assertDays(field, value) {
951
1322
  if (!Number.isInteger(value) || value < 1) {
952
- throw ruleInvalid(`${field2} must be an integer of at least 1`);
1323
+ throw ruleInvalid(`${field} must be an integer of at least 1`);
953
1324
  }
954
1325
  }
955
1326
  exports.BucketLifecycleService = class BucketLifecycleService {
956
- constructor(options, s3Provider, keyResolver) {
1327
+ constructor(options, s3Provider, keyResolver, observer) {
957
1328
  this.options = options;
958
1329
  this.s3Provider = s3Provider;
959
1330
  this.keyResolver = keyResolver;
1331
+ this.observer = observer;
960
1332
  }
961
1333
  options;
962
1334
  s3Provider;
963
1335
  keyResolver;
964
- /**
965
- * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
966
- * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
967
- * relative to it, as `list()` returns keys, so a prefix read here can be passed
968
- * straight to `upsert()` without being prefixed twice. A rule that is not confined
969
- * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
970
- * everything else about a rule is returned as the provider stores it.
971
- *
972
- * @param options - Optional per-call bucket override.
973
- * @returns Every rule in the bucket.
974
- * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
975
- */
1336
+ observer;
976
1337
  async get(options) {
977
1338
  this.assertConfigured();
978
1339
  const bucket = this.resolveBucket(options?.bucket);
979
- return (await this.read(bucket)).rules.map((rule) => this.toView(rule));
1340
+ return (await this.read(bucket, options?.bucket)).rules.map((rule) => this.toView(rule));
980
1341
  }
981
- /**
982
- * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
983
- * the full set back. Rules with other ids are sent exactly as they were read.
984
- *
985
- * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
986
- * @param options - Optional per-call bucket override.
987
- * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
988
- * that names a rule outside `keyPrefix`;
989
- * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
990
- * @example
991
- * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
992
- */
993
1342
  async upsert(rule, options) {
994
1343
  this.assertConfigured();
995
1344
  const owned = this.toRule(rule);
996
1345
  const bucket = this.resolveBucket(options?.bucket);
997
- const snapshot = await this.read(bucket);
1346
+ const snapshot = await this.read(bucket, options?.bucket);
998
1347
  const index = snapshot.rules.findIndex((existing) => existing.ID === owned.ID);
999
1348
  this.assertOwnable(snapshot.rules[index]);
1000
1349
  const rules = [...snapshot.rules];
@@ -1003,30 +1352,20 @@ exports.BucketLifecycleService = class BucketLifecycleService {
1003
1352
  } else {
1004
1353
  rules[index] = owned;
1005
1354
  }
1006
- await this.write(bucket, rules, snapshot, "upsert");
1355
+ await this.write(bucket, options?.bucket, rules, snapshot, "upsert");
1007
1356
  }
1008
- /**
1009
- * Removes the rule with this id. When it was the last rule the configuration is
1010
- * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
1011
- *
1012
- * @param id - The rule id.
1013
- * @param options - Optional per-call bucket override.
1014
- * @returns `true` when a rule was removed, `false` when no rule had that id.
1015
- * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
1016
- * outside `keyPrefix`; a provider failure otherwise.
1017
- */
1018
1357
  async remove(id, options) {
1019
1358
  this.assertConfigured();
1020
1359
  this.assertRuleId(id);
1021
1360
  const bucket = this.resolveBucket(options?.bucket);
1022
- const snapshot = await this.read(bucket);
1361
+ const snapshot = await this.read(bucket, options?.bucket);
1023
1362
  const target = snapshot.rules.find((existing) => existing.ID === id);
1024
1363
  if (target === void 0) {
1025
1364
  return false;
1026
1365
  }
1027
1366
  this.assertOwnable(target);
1028
1367
  const rules = snapshot.rules.filter((existing) => existing.ID !== id);
1029
- await this.write(bucket, rules, snapshot, "remove");
1368
+ await this.write(bucket, options?.bucket, rules, snapshot, "remove");
1030
1369
  return true;
1031
1370
  }
1032
1371
  /**
@@ -1080,7 +1419,7 @@ exports.BucketLifecycleService = class BucketLifecycleService {
1080
1419
  };
1081
1420
  }
1082
1421
  /** Reads the configuration; "none yet" is an empty snapshot. */
1083
- async read(bucket) {
1422
+ async read(bucket, perCall) {
1084
1423
  try {
1085
1424
  const response = await this.s3Provider.getClient().send(new clientS3.GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
1086
1425
  return {
@@ -1091,7 +1430,7 @@ exports.BucketLifecycleService = class BucketLifecycleService {
1091
1430
  if (isNoLifecycleConfiguration(err)) {
1092
1431
  return { rules: [], transitionDefaultMinimumObjectSize: void 0 };
1093
1432
  }
1094
- throw mapLifecycleError(err, { bucket, op: "lifecycle.get" });
1433
+ throw mapLifecycleError(err, callDetails("lifecycle.get", { bucket: perCall }));
1095
1434
  }
1096
1435
  }
1097
1436
  /**
@@ -1099,7 +1438,7 @@ exports.BucketLifecycleService = class BucketLifecycleService {
1099
1438
  * requires at least one rule on a put. The default-minimum-object-size setting
1100
1439
  * read earlier is sent back so a write does not silently change transition behaviour.
1101
1440
  */
1102
- async write(bucket, rules, snapshot, op) {
1441
+ async write(bucket, perCall, rules, snapshot, op) {
1103
1442
  const client = this.s3Provider.getClient();
1104
1443
  try {
1105
1444
  if (rules.length === 0) {
@@ -1114,7 +1453,7 @@ exports.BucketLifecycleService = class BucketLifecycleService {
1114
1453
  })
1115
1454
  );
1116
1455
  } catch (err) {
1117
- throw mapLifecycleError(err, { bucket, op: `lifecycle.${op}` });
1456
+ throw mapLifecycleError(err, callDetails(`lifecycle.${op}`, { bucket: perCall }));
1118
1457
  }
1119
1458
  }
1120
1459
  /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
@@ -1164,11 +1503,22 @@ exports.BucketLifecycleService = class BucketLifecycleService {
1164
1503
  return resolveBucket(perCall, this.options.bucket);
1165
1504
  }
1166
1505
  };
1506
+ __decorateClass([
1507
+ Observed("lifecycle_get")
1508
+ ], exports.BucketLifecycleService.prototype, "get", 1);
1509
+ __decorateClass([
1510
+ Observed("lifecycle_upsert")
1511
+ ], exports.BucketLifecycleService.prototype, "upsert", 1);
1512
+ __decorateClass([
1513
+ Observed("lifecycle_remove")
1514
+ ], exports.BucketLifecycleService.prototype, "remove", 1);
1167
1515
  exports.BucketLifecycleService = __decorateClass([
1168
1516
  common.Injectable(),
1169
1517
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
1170
1518
  __decorateParam(1, common.Inject(S3ClientProvider)),
1171
- __decorateParam(2, common.Inject(KeyResolverService))
1519
+ __decorateParam(2, common.Inject(KeyResolverService)),
1520
+ __decorateParam(3, common.Optional()),
1521
+ __decorateParam(3, common.Inject(StorageObserver))
1172
1522
  ], exports.BucketLifecycleService);
1173
1523
  function isBufferLike(body) {
1174
1524
  return body instanceof Uint8Array;
@@ -1322,18 +1672,17 @@ function assertMimeAllowed(whitelist, contentType) {
1322
1672
  return;
1323
1673
  }
1324
1674
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
1325
- ...isHeaderValue(contentType) ? { contentType } : {},
1326
- whitelist
1675
+ ...isHeaderValue(contentType) ? { contentType } : {}
1327
1676
  });
1328
1677
  }
1329
1678
 
1330
1679
  // src/server/utils/numeric-input.ts
1331
- function assertIntegerInput(value, field2, min) {
1680
+ function assertIntegerInput(value, field, min) {
1332
1681
  if (value === void 0) return;
1333
1682
  if (!Number.isInteger(value) || value < min) {
1334
1683
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1335
- field: field2,
1336
- reason: `${field2} must be an integer of at least ${String(min)}`
1684
+ field,
1685
+ reason: `${field} must be an integer of at least ${String(min)}`
1337
1686
  });
1338
1687
  }
1339
1688
  }
@@ -1433,46 +1782,41 @@ ValidationService = __decorateClass([
1433
1782
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
1434
1783
  __decorateParam(1, common.Inject(BYMAX_STORAGE_UPLOAD_VALIDATORS))
1435
1784
  ], ValidationService);
1436
-
1437
- // src/server/utils/cut-text.ts
1438
- function cutText(text, max) {
1439
- if (text.length <= max) return text;
1440
- const lastKept = text.charCodeAt(max - 1);
1441
- const splitsPair = lastKept >= 55296 && lastKept <= 56319;
1442
- return text.slice(0, splitsPair ? max - 1 : max);
1443
- }
1444
-
1445
- // src/server/services/file-scanner.service.ts
1446
1785
  var UNSERIALISABLE = "[unserialisable]";
1447
1786
  var MAX_SCANNER_LABEL_LENGTH = 200;
1448
1787
  var MAX_SCANNER_DETAILS_LENGTH = 300;
1449
1788
  var MAX_STATUS_LOG_LENGTH = 40;
1450
1789
  function statusForLog(status) {
1451
- return typeof status === "string" ? logValue(cutText(status, MAX_STATUS_LOG_LENGTH)) : `<${typeof status}>`;
1790
+ return typeof status === "string" ? escapeForLog(cutText(status, MAX_STATUS_LOG_LENGTH)) : `<${typeof status}>`;
1452
1791
  }
1453
1792
  function scannerLabel(value) {
1454
1793
  return typeof value === "string" ? cutText(value, MAX_SCANNER_LABEL_LENGTH) : void 0;
1455
1794
  }
1795
+ function labelForLog(label) {
1796
+ return label === void 0 ? void 0 : escapeForLog(label);
1797
+ }
1456
1798
  function toJson(value) {
1457
1799
  return JSON.stringify(value);
1458
1800
  }
1459
1801
  function scannerDetailsForLog(details) {
1460
- if (details === void 0) return "";
1802
+ if (details === void 0) return {};
1461
1803
  let text;
1462
1804
  try {
1463
1805
  text = toJson(details) ?? UNSERIALISABLE;
1464
1806
  } catch {
1465
1807
  text = UNSERIALISABLE;
1466
1808
  }
1467
- return ` details=${logValue(cutText(text, MAX_SCANNER_DETAILS_LENGTH))}`;
1809
+ return { details: escapeForLog(cutText(text, MAX_SCANNER_DETAILS_LENGTH)) };
1468
1810
  }
1469
1811
  var FileScannerService = class {
1470
- constructor(options, scanner) {
1812
+ constructor(options, scanner, observer) {
1471
1813
  this.options = options;
1472
1814
  this.scanner = scanner;
1815
+ this.observer = observer;
1473
1816
  }
1474
1817
  options;
1475
1818
  scanner;
1819
+ observer;
1476
1820
  logger = new common.Logger(FileScannerService.name);
1477
1821
  /**
1478
1822
  * Returns `true` when both a scanner implementation and scanner options are
@@ -1506,19 +1850,27 @@ var FileScannerService = class {
1506
1850
  * says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
1507
1851
  *
1508
1852
  * @param input - The scan input.
1853
+ * @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
1854
+ * bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
1509
1855
  * @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
1510
1856
  * @throws Error when called without a configured scanner.
1511
1857
  * @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
1512
1858
  * @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
1513
1859
  * @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
1514
1860
  */
1515
- async scan(input) {
1861
+ async scan(input, caller = {}) {
1516
1862
  if (!this.scanner) {
1517
1863
  throw new Error(
1518
1864
  "FileScannerService.scan() called without a configured scanner \u2014 guard with isEnabled() first."
1519
1865
  );
1520
1866
  }
1521
- const result = await this.scanLogged(this.scanner, input);
1867
+ const scanner = this.scanner;
1868
+ const run = () => this.evaluate(scanner, input, caller);
1869
+ return this.observer === void 0 ? run() : this.observer.scan(input.mode, run);
1870
+ }
1871
+ /** Runs the scanner and applies the library's policy to what it answered. */
1872
+ async evaluate(scanner, input, caller) {
1873
+ const result = await this.scanLogged(scanner, input, caller);
1522
1874
  const status = result?.status;
1523
1875
  const engine = scannerLabel(result?.engine);
1524
1876
  const threat = scannerLabel(result?.threat);
@@ -1527,18 +1879,41 @@ var FileScannerService = class {
1527
1879
  return result;
1528
1880
  }
1529
1881
  if (status === "infected") {
1530
- this.logger.warn(`Infected file detected: key=${logValue(input.key)} engine=${logValue(engine)} threat=${logValue(threat ?? "unknown")}${details}`);
1882
+ emit(this.logger, "warn", {
1883
+ event: STORAGE_LOG_EVENTS.scanInfected,
1884
+ message: "Infected file detected",
1885
+ engine: labelForLog(engine),
1886
+ threat: escapeForLog(threat ?? "unknown"),
1887
+ ...details
1888
+ });
1531
1889
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_SCAN_INFECTED, void 0, {
1532
1890
  engine,
1533
1891
  threat
1534
1892
  });
1535
1893
  }
1536
1894
  if (status === "unknown" && !this.options.scanner?.rejectOnUnknown) {
1537
- this.logger.warn(`Inconclusive scan result accepted: key=${logValue(input.key)} engine=${logValue(engine)}`);
1895
+ emit(this.logger, "warn", {
1896
+ event: STORAGE_LOG_EVENTS.scanInconclusiveAccepted,
1897
+ message: "Inconclusive scan result accepted",
1898
+ engine: labelForLog(engine)
1899
+ });
1538
1900
  return result;
1539
1901
  }
1902
+ return this.rejectInconclusive(status, engine, details);
1903
+ }
1904
+ /**
1905
+ * `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
1906
+ * exactly one of the three): the object is not known to be clean, so it is not stored.
1907
+ */
1908
+ rejectInconclusive(status, engine, details) {
1540
1909
  const unrecognised = status !== "unknown";
1541
- this.logger.warn(`Inconclusive scan result rejected: key=${logValue(input.key)} engine=${logValue(engine)}${unrecognised ? ` status=${statusForLog(status)}` : ""}${details}`);
1910
+ emit(this.logger, "warn", {
1911
+ event: STORAGE_LOG_EVENTS.scanInconclusiveRejected,
1912
+ message: "Inconclusive scan result rejected",
1913
+ engine: labelForLog(engine),
1914
+ ...unrecognised ? { status: statusForLog(status) } : {},
1915
+ ...details
1916
+ });
1542
1917
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_SCAN_INCONCLUSIVE, void 0, {
1543
1918
  engine,
1544
1919
  ...unrecognised ? { reason: "unrecognised scanner status" } : {}
@@ -1548,14 +1923,16 @@ var FileScannerService = class {
1548
1923
  * Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
1549
1924
  * line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
1550
1925
  */
1551
- async scanLogged(scanner, input) {
1926
+ async scanLogged(scanner, input, caller) {
1552
1927
  try {
1553
- return await this.scanWithinDeadline(scanner, input);
1928
+ return await this.scanWithinDeadline(scanner, input, caller);
1554
1929
  } catch (err) {
1555
1930
  if (!(err instanceof StorageException)) {
1556
- this.logger.warn(
1557
- `Scanner failed: key=${logValue(input.key)} error=${logValue(cutText(describeError(err), MAX_SCANNER_DETAILS_LENGTH))}`
1558
- );
1931
+ emit(this.logger, "warn", {
1932
+ event: STORAGE_LOG_EVENTS.scanFailed,
1933
+ message: "Scanner failed",
1934
+ err: failureError(err)
1935
+ });
1559
1936
  }
1560
1937
  throw err;
1561
1938
  }
@@ -1565,17 +1942,20 @@ var FileScannerService = class {
1565
1942
  * the upload for good. The scanner is handed a signal that aborts then; one that ignores it keeps
1566
1943
  * running.
1567
1944
  */
1568
- async scanWithinDeadline(scanner, input) {
1945
+ async scanWithinDeadline(scanner, input, caller) {
1569
1946
  const timeoutMs = this.options.scanner?.timeoutMs ?? DEFAULT_SCANNER_TIMEOUT_MS;
1570
1947
  const controller = new AbortController();
1571
1948
  let timer;
1572
1949
  const deadline = new Promise((_resolve, reject) => {
1573
1950
  timer = setTimeout(() => {
1574
- this.logger.warn(`Scan timed out: key=${logValue(input.key)} timeoutMs=${String(timeoutMs)}`);
1951
+ emit(this.logger, "warn", {
1952
+ event: STORAGE_LOG_EVENTS.scanTimeout,
1953
+ message: "Scan timed out",
1954
+ timeoutMs
1955
+ });
1575
1956
  reject(
1576
1957
  new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, void 0, {
1577
- key: input.key,
1578
- bucket: input.bucket,
1958
+ ...caller,
1579
1959
  phase: "scan",
1580
1960
  timeoutMs
1581
1961
  })
@@ -1593,7 +1973,9 @@ var FileScannerService = class {
1593
1973
  FileScannerService = __decorateClass([
1594
1974
  common.Injectable(),
1595
1975
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
1596
- __decorateParam(1, common.Inject(BYMAX_STORAGE_FILE_SCANNER))
1976
+ __decorateParam(1, common.Inject(BYMAX_STORAGE_FILE_SCANNER)),
1977
+ __decorateParam(2, common.Optional()),
1978
+ __decorateParam(2, common.Inject(StorageObserver))
1597
1979
  ], FileScannerService);
1598
1980
  var SourceIdleError = class extends Error {
1599
1981
  constructor(idleMs) {
@@ -1807,7 +2189,7 @@ function cleanupErrorCode(error) {
1807
2189
  }
1808
2190
  function describeCleanupFailure(error) {
1809
2191
  if (!(error instanceof StorageException)) {
1810
- return describeError(error);
2192
+ return projectProviderFailure(error).message;
1811
2193
  }
1812
2194
  return error.code;
1813
2195
  }
@@ -1822,7 +2204,6 @@ function withCleanupFailure(scanError, keys, cleanupError) {
1822
2204
  {
1823
2205
  ...body.error?.details ?? {},
1824
2206
  key: keys.key,
1825
- storedKey: keys.storedKey,
1826
2207
  cleanup: "failed",
1827
2208
  cleanupError: cleanupErrorCode(cleanupError)
1828
2209
  }
@@ -1955,11 +2336,13 @@ async function closeMultipartUpload(client, bucket, key, uploadId, onFailure) {
1955
2336
  function closeWhenCreated(client, bucket, key, created, onFailure) {
1956
2337
  void created.then((uploadId) => closeMultipartUpload(client, bucket, key, uploadId, onFailure));
1957
2338
  }
1958
- function abortFailureLogger(logger2, key) {
2339
+ function abortFailureLogger(logger2) {
1959
2340
  return (err) => {
1960
- logger2.warn(
1961
- `Multipart abort failed, the upload stays open on the provider: ${logValue(key)} ${describeProviderFailure(err)}`
1962
- );
2341
+ emit(logger2, "warn", {
2342
+ event: STORAGE_LOG_EVENTS.multipartAbortFailed,
2343
+ message: "Multipart abort failed, the upload stays open on the provider",
2344
+ err: failureError(err)
2345
+ });
1963
2346
  };
1964
2347
  }
1965
2348
  async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
@@ -2072,9 +2455,32 @@ function buildSSE(perCall, perCallKmsKeyId, module) {
2072
2455
  return { ServerSideEncryption: sse };
2073
2456
  }
2074
2457
  function buildACL(perCall, defaultValue) {
2458
+ if (perCall !== void 0 && typeof perCall !== "boolean") {
2459
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
2460
+ field: "publicRead",
2461
+ reason: "must be a boolean"
2462
+ });
2463
+ }
2075
2464
  return perCall ?? defaultValue ? "public-read" : void 0;
2076
2465
  }
2077
2466
 
2467
+ // src/server/utils/object-metadata.ts
2468
+ function toObjectMetadata(response, key, bucket) {
2469
+ return {
2470
+ key,
2471
+ bucket,
2472
+ size: response.ContentLength ?? 0,
2473
+ contentType: response.ContentType ?? "application/octet-stream",
2474
+ etag: response.ETag ?? "",
2475
+ lastModified: response.LastModified ?? /* @__PURE__ */ new Date(0),
2476
+ metadata: response.Metadata ?? {},
2477
+ ...response.CacheControl !== void 0 ? { cacheControl: response.CacheControl } : {},
2478
+ ...response.ContentDisposition !== void 0 ? { contentDisposition: response.ContentDisposition } : {},
2479
+ ...response.StorageClass !== void 0 ? { storageClass: response.StorageClass } : {},
2480
+ ...response.VersionId !== void 0 ? { versionId: response.VersionId } : {}
2481
+ };
2482
+ }
2483
+
2078
2484
  // src/server/utils/upload-strategy.ts
2079
2485
  function pickUploadStrategy(body, declaredSize, thresholdBytes) {
2080
2486
  const size = declaredSize ?? getBodySize(body);
@@ -2103,18 +2509,18 @@ function boundStreamSize(body, declaredSize, options) {
2103
2509
  }
2104
2510
  return withSizeLimit(body, limit, declaredSize === void 0 ? "max" : "declared");
2105
2511
  }
2106
- async function bufferStreamForScan(body, finalKey, maxSizeBytes) {
2512
+ async function bufferStreamForScan(body, context, maxSizeBytes) {
2107
2513
  if (maxSizeBytes === void 0) {
2108
2514
  destroyStream(body);
2109
2515
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
2110
- key: finalKey,
2516
+ ...context,
2111
2517
  reason: "Pre-upload scanning of a stream needs validation.maxSizeBytes to bound the buffer; set it or use scanner mode post-upload"
2112
2518
  });
2113
2519
  }
2114
2520
  const buffered = await readStreamUpTo(body, maxSizeBytes);
2115
2521
  if (buffered === void 0) {
2116
2522
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
2117
- key: finalKey,
2523
+ ...context,
2118
2524
  maxSizeBytes,
2119
2525
  reason: "The stream is longer than validation.maxSizeBytes, so it cannot be scanned before upload"
2120
2526
  });
@@ -2172,6 +2578,13 @@ function baseCarriesBucket(base, bucket) {
2172
2578
  function normalizeScanBody(body) {
2173
2579
  return body;
2174
2580
  }
2581
+ function trackLoaded(uploader) {
2582
+ let loaded = 0;
2583
+ uploader.on("httpUploadProgress", (event) => {
2584
+ loaded = event.loaded ?? loaded;
2585
+ });
2586
+ return () => loaded;
2587
+ }
2175
2588
  function forwardProgress(uploader, onProgress) {
2176
2589
  if (!onProgress) return;
2177
2590
  uploader.on("httpUploadProgress", (event) => {
@@ -2198,11 +2611,14 @@ function buildUploadResult(keyResolver, options, params) {
2198
2611
  };
2199
2612
  }
2200
2613
  function emitProgress(onProgress, loaded, total, part) {
2201
- onProgress({
2202
- loaded: loaded ?? 0,
2203
- ...total !== void 0 ? { total } : {},
2204
- ...part !== void 0 ? { part } : {}
2205
- });
2614
+ const hook = onProgress;
2615
+ absorb(
2616
+ () => hook({
2617
+ loaded: loaded ?? 0,
2618
+ ...total !== void 0 ? { total } : {},
2619
+ ...part !== void 0 ? { part } : {}
2620
+ })
2621
+ );
2206
2622
  }
2207
2623
  function putObjectHeaders(options, resolved, finalKey, bucket) {
2208
2624
  return {
@@ -2241,11 +2657,10 @@ function assertMaxBytes(maxBytes) {
2241
2657
  });
2242
2658
  }
2243
2659
  }
2244
- async function readBody(stream, metadata, maxBytes) {
2660
+ async function readBody(stream, metadata, maxBytes, context) {
2245
2661
  if (maxBytes === void 0) {
2246
2662
  return readStream(stream);
2247
2663
  }
2248
- const context = { key: metadata.key, bucket: metadata.bucket };
2249
2664
  if (metadata.size > maxBytes) {
2250
2665
  destroyStream(stream);
2251
2666
  throw sizeLimitException(maxBytes, "max", { ...context, contentLength: metadata.size });
@@ -2256,15 +2671,51 @@ async function readBody(stream, metadata, maxBytes) {
2256
2671
  }
2257
2672
  return buffer;
2258
2673
  }
2259
- async function readDownloadBody(stream, metadata, maxBytes, signal) {
2674
+ async function readDownloadBody(stream, metadata, maxBytes, signal, caller) {
2675
+ const context = { ...caller, op: "downloadBuffer" };
2260
2676
  try {
2261
- return await readBody(stream, metadata, maxBytes);
2677
+ return await readBody(stream, metadata, maxBytes, context);
2262
2678
  } catch (err) {
2263
- throw mapBodyReadFailure(err, signal, {
2264
- key: metadata.key,
2265
- bucket: metadata.bucket,
2266
- op: "downloadBuffer"
2679
+ throw mapBodyReadFailure(err, signal, context);
2680
+ }
2681
+ }
2682
+
2683
+ // src/server/utils/uploaded-bytes.ts
2684
+ var SENT = /* @__PURE__ */ new WeakMap();
2685
+ function rememberUploadedBytes(result, bytes) {
2686
+ SENT.set(result, bytes);
2687
+ return result;
2688
+ }
2689
+ function uploadedBytesOf(result) {
2690
+ return result.fromIdempotencyCache ? void 0 : SENT.get(result) ?? result.size;
2691
+ }
2692
+ async function uploadSingleShot(context, options, finalKey, bucket, caller) {
2693
+ const { onProgress, contentType, abortSignal } = options;
2694
+ const total = options.size ?? getBodySize(options.body);
2695
+ const input = {
2696
+ ...putObjectHeaders(options, context.options, finalKey, bucket),
2697
+ Body: normalizeSingleShotBody(options.body),
2698
+ ContentLength: total
2699
+ };
2700
+ const watch = abortOnBodyFailure(input.Body, abortSignal);
2701
+ try {
2702
+ const response = await context.s3Provider.getClient().send(new clientS3.PutObjectCommand(input), sendOptions(watch.signal));
2703
+ if (onProgress) {
2704
+ emitProgress(onProgress, total, total);
2705
+ }
2706
+ return buildUploadResult(context.keyResolver, context.options, {
2707
+ finalKey,
2708
+ bucket,
2709
+ etag: response.ETag,
2710
+ versionId: response.VersionId,
2711
+ size: total,
2712
+ contentType,
2713
+ multipart: false
2267
2714
  });
2715
+ } catch (err) {
2716
+ const context2 = { ...caller, op: "upload-single" };
2717
+ const mapped = mapSizeLimitError(watch.failure(), context2) ?? mapAwsError(err, context2);
2718
+ throw failureOrAbort(abortSignal, context2, mapped);
2268
2719
  }
2269
2720
  }
2270
2721
 
@@ -2272,13 +2723,14 @@ async function readDownloadBody(stream, metadata, maxBytes, signal) {
2272
2723
  var MAX_LIST_KEYS = 1e3;
2273
2724
  var DELETE_BATCH_LIMIT = 1e3;
2274
2725
  exports.StorageService = class StorageService {
2275
- constructor(options, s3Provider, keyResolver, idempotencyCache, validation, scanner) {
2726
+ constructor(options, s3Provider, keyResolver, idempotencyCache, validation, scanner, observer) {
2276
2727
  this.options = options;
2277
2728
  this.s3Provider = s3Provider;
2278
2729
  this.keyResolver = keyResolver;
2279
2730
  this.idempotencyCache = idempotencyCache;
2280
2731
  this.validation = validation;
2281
2732
  this.scanner = scanner;
2733
+ this.observer = observer;
2282
2734
  }
2283
2735
  options;
2284
2736
  s3Provider;
@@ -2286,22 +2738,8 @@ exports.StorageService = class StorageService {
2286
2738
  idempotencyCache;
2287
2739
  validation;
2288
2740
  scanner;
2741
+ observer;
2289
2742
  logger = new common.Logger(exports.StorageService.name);
2290
- /**
2291
- * Uploads an object, choosing single-shot or multipart automatically. When an
2292
- * `idempotencyKey` is supplied and a matching result is cached within the TTL
2293
- * window, the cached result is returned without re-uploading.
2294
- *
2295
- * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
2296
- * upload is rejected for any reason (configuration, validation, scan, provider failure)
2297
- * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
2298
- * that nothing listens to), which releases the file handle or socket behind it; a cache hit
2299
- * destroys it unread. A stream consumed by a successful upload ends on its own.
2300
- *
2301
- * @param options - The upload request.
2302
- * @returns The upload result.
2303
- * @throws StorageException for missing configuration, body, or content type.
2304
- */
2305
2743
  async upload(options) {
2306
2744
  try {
2307
2745
  return await this.uploadOwningBody(options);
@@ -2324,7 +2762,7 @@ exports.StorageService = class StorageService {
2324
2762
  }
2325
2763
  const finalKey = this.keyResolver.normalize(options.key);
2326
2764
  const bucket = this.resolveBucket(options.bucket);
2327
- const context = { key: finalKey, bucket, op: "upload" };
2765
+ const context = callDetails("upload", { key: options.key, bucket: options.bucket });
2328
2766
  throwIfAborted(options.abortSignal, context);
2329
2767
  if (options.idempotencyKey) {
2330
2768
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
@@ -2342,7 +2780,7 @@ exports.StorageService = class StorageService {
2342
2780
  validatedOptions.size,
2343
2781
  this.options.multipart.thresholdBytes
2344
2782
  );
2345
- const result = strategy === "multipart" ? await this.uploadMultipart(validatedOptions, finalKey, bucket) : await this.uploadSingleShot(validatedOptions, finalKey, bucket);
2783
+ const result = strategy === "multipart" ? await this.uploadMultipart(validatedOptions, finalKey, bucket, context) : await uploadSingleShot(this.uploadContext, validatedOptions, finalKey, bucket, context);
2346
2784
  const stored = { ...context, stored: true };
2347
2785
  await abortable(this.runPostUploadScan(finalKey, bucket, options), options.abortSignal, stored);
2348
2786
  this.rememberUpload(options, finalKey, result);
@@ -2358,7 +2796,7 @@ exports.StorageService = class StorageService {
2358
2796
  const input = validationInput(options, finalKey);
2359
2797
  const validated = await abortable(this.validation.validate(input), signal, context);
2360
2798
  const scanned = await abortable(
2361
- this.bufferForPreUploadScan(validated.body, finalKey),
2799
+ this.bufferForPreUploadScan(validated.body, context),
2362
2800
  signal,
2363
2801
  context
2364
2802
  );
@@ -2375,28 +2813,31 @@ exports.StorageService = class StorageService {
2375
2813
  * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
2376
2814
  * buffered without limit. Other bodies and modes pass through unchanged.
2377
2815
  */
2378
- async bufferForPreUploadScan(body, finalKey) {
2816
+ async bufferForPreUploadScan(body, context) {
2379
2817
  if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload") {
2380
2818
  return body;
2381
2819
  }
2382
2820
  if (isBufferLike(body)) {
2383
2821
  return Buffer.from(body);
2384
2822
  }
2385
- return bufferStreamForScan(body, finalKey, this.options.validation?.maxSizeBytes);
2823
+ return bufferStreamForScan(body, context, this.options.validation?.maxSizeBytes);
2386
2824
  }
2387
2825
  /** Runs a pre-upload scan when configured; throws on infected. */
2388
2826
  async runPreUploadScan(body, finalKey, bucket, options) {
2389
2827
  if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload") {
2390
2828
  return;
2391
2829
  }
2392
- await this.scanner.scan({
2393
- mode: "pre-upload",
2394
- body: normalizeScanBody(body),
2395
- key: finalKey,
2396
- bucket,
2397
- contentType: options.contentType,
2398
- ...options.size !== void 0 ? { size: options.size } : {}
2399
- });
2830
+ await this.scanner.scan(
2831
+ {
2832
+ mode: "pre-upload",
2833
+ body: normalizeScanBody(body),
2834
+ key: finalKey,
2835
+ bucket,
2836
+ contentType: options.contentType,
2837
+ ...options.size !== void 0 ? { size: options.size } : {}
2838
+ },
2839
+ callerFields({ key: options.key, bucket: options.bucket })
2840
+ );
2400
2841
  }
2401
2842
  /** Remembers the result of an upload under its idempotency key, when it has one. */
2402
2843
  rememberUpload(options, finalKey, result) {
@@ -2415,47 +2856,44 @@ exports.StorageService = class StorageService {
2415
2856
  return;
2416
2857
  }
2417
2858
  try {
2418
- await this.scanner.scan({
2419
- mode: "post-upload",
2420
- key: finalKey,
2421
- bucket,
2422
- contentType: options.contentType,
2423
- ...options.size !== void 0 ? { size: options.size } : {}
2424
- });
2859
+ await this.scanner.scan(
2860
+ {
2861
+ mode: "post-upload",
2862
+ key: finalKey,
2863
+ bucket,
2864
+ contentType: options.contentType,
2865
+ ...options.size !== void 0 ? { size: options.size } : {}
2866
+ },
2867
+ callerFields({ key: options.key, bucket: options.bucket })
2868
+ );
2425
2869
  } catch (scanErr) {
2426
2870
  const key = this.keyResolver.stripPrefix(finalKey);
2427
2871
  try {
2428
2872
  await this.delete(key, { bucket, abortSignal: AbortSignal.timeout(CLEANUP_DEADLINE_MS) });
2429
2873
  } catch (deleteErr) {
2430
- this.logger.error(
2431
- `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${logValue(finalKey)}`,
2432
- logValue(describeCleanupFailure(deleteErr))
2433
- );
2434
- throw withCleanupFailure(scanErr, { key, storedKey: finalKey }, deleteErr);
2874
+ emit(this.logger, "error", {
2875
+ event: STORAGE_LOG_EVENTS.scanCleanupFailed,
2876
+ message: "The rejected object is still stored",
2877
+ storedKey: escapeForLog(finalKey),
2878
+ cleanupFailure: describeCleanupFailure(deleteErr)
2879
+ });
2880
+ throw withCleanupFailure(scanErr, { key }, deleteErr);
2435
2881
  }
2436
2882
  throw scanErr;
2437
2883
  }
2438
2884
  }
2439
- /**
2440
- * Returns metadata for an object without downloading its body.
2441
- *
2442
- * @param key - The raw object key (normalized internally).
2443
- * @param options - Optional per-call bucket override.
2444
- * @returns The object metadata.
2445
- * @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the key is absent.
2446
- */
2447
2885
  async head(key, options) {
2448
2886
  this.assertConfigured();
2449
2887
  const finalKey = this.keyResolver.normalize(key);
2450
2888
  const bucket = this.resolveBucket(options?.bucket);
2451
- const context = { key: finalKey, bucket, op: "head" };
2889
+ const context = callDetails("head", { key, bucket: options?.bucket });
2452
2890
  throwIfAborted(options?.abortSignal, context);
2453
2891
  try {
2454
2892
  const response = await this.s3Provider.getClient().send(
2455
2893
  new clientS3.HeadObjectCommand({ Bucket: bucket, Key: finalKey }),
2456
2894
  sendOptions(options?.abortSignal)
2457
2895
  );
2458
- return this.toObjectMetadata(response, finalKey, bucket);
2896
+ return toObjectMetadata(response, this.keyResolver.stripPrefix(finalKey), bucket);
2459
2897
  } catch (err) {
2460
2898
  throw failureOrAbort(options?.abortSignal, context, mapAwsError(err, context));
2461
2899
  }
@@ -2479,9 +2917,11 @@ exports.StorageService = class StorageService {
2479
2917
  if (err instanceof StorageException && err.code === STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED) {
2480
2918
  throw err;
2481
2919
  }
2482
- this.logger.warn(
2483
- `exists() \u2014 treating a non-404 error as "false": ${logValue(describeError(err))}`
2484
- );
2920
+ emit(this.logger, "warn", {
2921
+ event: STORAGE_LOG_EVENTS.existsFailed,
2922
+ message: 'exists() \u2014 treating a non-404 error as "false"',
2923
+ err: failureError(err)
2924
+ });
2485
2925
  return false;
2486
2926
  }
2487
2927
  }
@@ -2498,15 +2938,6 @@ exports.StorageService = class StorageService {
2498
2938
  const bucket = this.resolveBucket(options?.bucket);
2499
2939
  return buildPublicUrl(this.options, finalKey, bucket);
2500
2940
  }
2501
- /**
2502
- * Streams an object. The returned `stream` is a Node `Readable` consumable via
2503
- * `for await` or `.pipe()`. `range` / `ifNoneMatch` / `ifMatch` are forwarded as
2504
- * conditional/partial GET headers.
2505
- *
2506
- * @param options - The download request.
2507
- * @returns The object stream and its metadata.
2508
- * @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the body is absent.
2509
- */
2510
2941
  async download(options) {
2511
2942
  this.assertConfigured();
2512
2943
  assertHeaderValues({
@@ -2516,7 +2947,7 @@ exports.StorageService = class StorageService {
2516
2947
  });
2517
2948
  const finalKey = this.keyResolver.normalize(options.key);
2518
2949
  const bucket = this.resolveBucket(options.bucket);
2519
- const context = { key: finalKey, bucket, op: "download" };
2950
+ const context = callDetails("download", { key: options.key, bucket: options.bucket });
2520
2951
  throwIfAborted(options.abortSignal, context);
2521
2952
  try {
2522
2953
  const response = await this.s3Provider.getClient().send(
@@ -2530,10 +2961,7 @@ exports.StorageService = class StorageService {
2530
2961
  sendOptions(options.abortSignal)
2531
2962
  );
2532
2963
  if (!response.Body) {
2533
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND, void 0, {
2534
- key: finalKey,
2535
- bucket
2536
- });
2964
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND, void 0, context);
2537
2965
  }
2538
2966
  const stream = guardDownloadBody(
2539
2967
  response.Body,
@@ -2541,7 +2969,10 @@ exports.StorageService = class StorageService {
2541
2969
  context,
2542
2970
  options.abortSignal
2543
2971
  );
2544
- return { stream, metadata: this.toObjectMetadata(response, finalKey, bucket) };
2972
+ return {
2973
+ stream,
2974
+ metadata: toObjectMetadata(response, this.keyResolver.stripPrefix(finalKey), bucket)
2975
+ };
2545
2976
  } catch (err) {
2546
2977
  if (err instanceof StorageException) {
2547
2978
  throw err;
@@ -2561,21 +2992,20 @@ exports.StorageService = class StorageService {
2561
2992
  async downloadBuffer(options) {
2562
2993
  assertMaxBytes(options.maxBytes);
2563
2994
  const { stream, metadata } = await this.download(options);
2564
- const buffer = await readDownloadBody(stream, metadata, options.maxBytes, options.abortSignal);
2995
+ const buffer = await readDownloadBody(
2996
+ stream,
2997
+ metadata,
2998
+ options.maxBytes,
2999
+ options.abortSignal,
3000
+ callerFields({ key: options.key, bucket: options.bucket })
3001
+ );
2565
3002
  return { buffer, metadata };
2566
3003
  }
2567
- /**
2568
- * Deletes an object. Idempotent: a missing object is a no-op (logged as a
2569
- * warning), not an error. Any other failure is propagated.
2570
- *
2571
- * @param key - The raw object key.
2572
- * @param options - Optional per-call bucket override.
2573
- */
2574
3004
  async delete(key, options) {
2575
3005
  this.assertConfigured();
2576
3006
  const finalKey = this.keyResolver.normalize(key);
2577
3007
  const bucket = this.resolveBucket(options?.bucket);
2578
- const context = { key: finalKey, bucket, op: "delete" };
3008
+ const context = callDetails("delete", { key, bucket: options?.bucket });
2579
3009
  throwIfAborted(options?.abortSignal, context);
2580
3010
  try {
2581
3011
  await this.s3Provider.getClient().send(
@@ -2587,25 +3017,17 @@ exports.StorageService = class StorageService {
2587
3017
  if (mapped.code !== STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
2588
3018
  throw mapped;
2589
3019
  }
2590
- this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${logValue(finalKey)}`);
3020
+ emit(this.logger, "warn", {
3021
+ event: STORAGE_LOG_EVENTS.deleteNotFound,
3022
+ message: "delete() \u2014 key not found (idempotent no-op)"
3023
+ });
2591
3024
  }
2592
3025
  this.idempotencyCache.invalidate(bucket, this.keyResolver.stripPrefix(finalKey));
2593
3026
  }
2594
- /**
2595
- * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
2596
- * is reachable with these credentials and otherwise rejects with a typed code. Nothing in the
2597
- * module calls it on its own, so booting costs no request. Needs `s3:ListBucket`.
2598
- *
2599
- * @param options - Optional per-call bucket override.
2600
- * @throws StorageException `STORAGE_BUCKET_NOT_FOUND` (404), `STORAGE_BUCKET_ACCESS_DENIED` (403,
2601
- * which a provider also answers for a bucket the caller cannot see), `STORAGE_BUCKET_REGION_MISMATCH`
2602
- * (301), `STORAGE_TIMEOUT`, or `STORAGE_PROVIDER_ERROR`; `STORAGE_NOT_CONFIGURED` and
2603
- * `STORAGE_BUCKET_UNDEFINED` before any request.
2604
- */
2605
3027
  async checkBucket(options) {
2606
3028
  this.assertConfigured();
2607
3029
  const bucket = this.resolveBucket(options?.bucket);
2608
- const context = { bucket, op: "checkBucket" };
3030
+ const context = callDetails("checkBucket", { bucket: options?.bucket });
2609
3031
  throwIfAborted(options?.abortSignal, context);
2610
3032
  try {
2611
3033
  await this.s3Provider.getClient().send(new clientS3.HeadBucketCommand({ Bucket: bucket }), sendOptions(options?.abortSignal));
@@ -2613,6 +3035,10 @@ exports.StorageService = class StorageService {
2613
3035
  throw failureOrAbort(options?.abortSignal, context, mapBucketCheckError(err, context));
2614
3036
  }
2615
3037
  }
3038
+ /** What the single-shot upload needs of this service. */
3039
+ get uploadContext() {
3040
+ return { s3Provider: this.s3Provider, keyResolver: this.keyResolver, options: this.options };
3041
+ }
2616
3042
  /** Throws when the S3 client was never built (missing credentials). */
2617
3043
  assertConfigured() {
2618
3044
  if (!this.s3Provider.isConfigured()) {
@@ -2623,58 +3049,13 @@ exports.StorageService = class StorageService {
2623
3049
  resolveBucket(perCall) {
2624
3050
  return resolveBucket(perCall, this.options.bucket);
2625
3051
  }
2626
- /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
2627
- toObjectMetadata(response, finalKey, bucket) {
2628
- return {
2629
- key: this.keyResolver.stripPrefix(finalKey),
2630
- bucket,
2631
- size: response.ContentLength ?? 0,
2632
- contentType: response.ContentType ?? "application/octet-stream",
2633
- etag: response.ETag ?? "",
2634
- lastModified: response.LastModified ?? /* @__PURE__ */ new Date(0),
2635
- metadata: response.Metadata ?? {},
2636
- ...response.CacheControl !== void 0 ? { cacheControl: response.CacheControl } : {},
2637
- ...response.ContentDisposition !== void 0 ? { contentDisposition: response.ContentDisposition } : {},
2638
- ...response.StorageClass !== void 0 ? { storageClass: response.StorageClass } : {},
2639
- ...response.VersionId !== void 0 ? { versionId: response.VersionId } : {}
2640
- };
2641
- }
2642
- /** Single `PutObject` upload for bodies below the multipart threshold. */
2643
- async uploadSingleShot(options, finalKey, bucket) {
2644
- const total = options.size ?? getBodySize(options.body);
2645
- const input = {
2646
- ...putObjectHeaders(options, this.options, finalKey, bucket),
2647
- Body: normalizeSingleShotBody(options.body),
2648
- ContentLength: total
2649
- };
2650
- const watch = abortOnBodyFailure(input.Body, options.abortSignal);
2651
- try {
2652
- const response = await this.s3Provider.getClient().send(new clientS3.PutObjectCommand(input), sendOptions(watch.signal));
2653
- if (options.onProgress) {
2654
- emitProgress(options.onProgress, total, total);
2655
- }
2656
- return buildUploadResult(this.keyResolver, this.options, {
2657
- finalKey,
2658
- bucket,
2659
- etag: response.ETag,
2660
- versionId: response.VersionId,
2661
- size: total,
2662
- contentType: options.contentType,
2663
- multipart: false
2664
- });
2665
- } catch (err) {
2666
- const context = { key: finalKey, bucket, op: "upload-single" };
2667
- const mapped = mapSizeLimitError(watch.failure(), context) ?? mapAwsError(err, context);
2668
- throw failureOrAbort(options.abortSignal, context, mapped);
2669
- }
2670
- }
2671
3052
  /**
2672
3053
  * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
2673
3054
  * (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
2674
3055
  * abort replaced the failure that caused it, and a failed `CompleteMultipartUpload` was never
2675
3056
  * aborted. This method aborts the upload itself and reports the outcome in the error details.
2676
3057
  */
2677
- async uploadMultipart(options, finalKey, bucket) {
3058
+ async uploadMultipart(options, finalKey, bucket, caller) {
2678
3059
  const params = {
2679
3060
  ...putObjectHeaders(options, this.options, finalKey, bucket),
2680
3061
  Body: guardIdleBody(options.body, this.options.uploadIdleTimeoutMs)
@@ -2688,6 +3069,7 @@ exports.StorageService = class StorageService {
2688
3069
  partSize: this.options.multipart.partSizeBytes,
2689
3070
  leavePartsOnError: true
2690
3071
  });
3072
+ const sent = trackLoaded(uploader);
2691
3073
  forwardProgress(uploader, options.onProgress);
2692
3074
  const abortUpload = () => {
2693
3075
  void uploader.abort();
@@ -2695,17 +3077,20 @@ exports.StorageService = class StorageService {
2695
3077
  signal?.addEventListener("abort", abortUpload, { once: true });
2696
3078
  try {
2697
3079
  const response = await uploader.done();
2698
- return buildUploadResult(this.keyResolver, this.options, {
2699
- finalKey,
2700
- bucket,
2701
- etag: response.ETag,
2702
- versionId: response.VersionId,
2703
- size: options.size,
2704
- contentType: options.contentType,
2705
- multipart: true
2706
- });
3080
+ return rememberUploadedBytes(
3081
+ buildUploadResult(this.keyResolver, this.options, {
3082
+ finalKey,
3083
+ bucket,
3084
+ etag: response.ETag,
3085
+ versionId: response.VersionId,
3086
+ size: options.size,
3087
+ contentType: options.contentType,
3088
+ multipart: true
3089
+ }),
3090
+ sent()
3091
+ );
2707
3092
  } catch (err) {
2708
- return await this.failMultipart(err, finalKey, bucket, {
3093
+ return await this.failMultipart(err, finalKey, bucket, caller, {
2709
3094
  uploadId: uploader.uploadId,
2710
3095
  signal,
2711
3096
  createdUploadId: bound?.createdUploadId
@@ -2720,7 +3105,7 @@ exports.StorageService = class StorageService {
2720
3105
  * real failure into one. An upload id the provider answered late is waited for, within the cleanup
2721
3106
  * deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
2722
3107
  */
2723
- async failMultipart(err, finalKey, bucket, upload) {
3108
+ async failMultipart(err, finalKey, bucket, caller, upload) {
2724
3109
  const abortedBy = upload.signal?.aborted === true ? upload.signal : void 0;
2725
3110
  const client = this.s3Provider.getClient();
2726
3111
  const lookup = abortedBy ? upload.createdUploadId?.() : void 0;
@@ -2728,7 +3113,7 @@ exports.StorageService = class StorageService {
2728
3113
  if (uploadId === void 0 && lookup) {
2729
3114
  uploadId = await within(lookup, CLEANUP_DEADLINE_MS);
2730
3115
  if (uploadId === void 0) {
2731
- closeWhenCreated(client, bucket, finalKey, lookup, abortFailureLogger(this.logger, finalKey));
3116
+ closeWhenCreated(client, bucket, finalKey, lookup, abortFailureLogger(this.logger));
2732
3117
  }
2733
3118
  }
2734
3119
  const abort = await closeMultipartUpload(
@@ -2736,27 +3121,18 @@ exports.StorageService = class StorageService {
2736
3121
  bucket,
2737
3122
  finalKey,
2738
3123
  uploadId,
2739
- abortFailureLogger(this.logger, finalKey)
3124
+ abortFailureLogger(this.logger)
2740
3125
  );
2741
- const context = { key: finalKey, bucket, op: "upload-multipart", ...abort };
3126
+ const context = { ...caller, op: "upload-multipart", ...abort };
2742
3127
  throw abortedBy ? requestAborted(abortedBy, context) : mapMultipartError(err, context);
2743
3128
  }
2744
- /**
2745
- * Lists objects in the bucket as a single page. Applies the global key prefix
2746
- * to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
2747
- * the continuation token, and strips the global prefix from every returned key.
2748
- *
2749
- * @param options - The listing request.
2750
- * @returns One page of objects plus `commonPrefixes`, truncation, and the next token.
2751
- * @throws StorageException mapped from any AWS failure.
2752
- */
2753
3129
  async list(options) {
2754
3130
  this.assertConfigured();
2755
3131
  const bucket = this.resolveBucket(options.bucket);
2756
3132
  assertIntegerInput(options.maxKeys, "maxKeys", 1);
2757
3133
  const maxKeys = Math.min(options.maxKeys ?? MAX_LIST_KEYS, MAX_LIST_KEYS);
2758
3134
  const prefix = options.prefix ? this.keyResolver.normalize(options.prefix) : this.keyResolver.getPrefix();
2759
- const context = { bucket, prefix, op: "list" };
3135
+ const context = callDetails("list", { bucket: options.bucket, prefix: options.prefix });
2760
3136
  throwIfAborted(options.abortSignal, context);
2761
3137
  try {
2762
3138
  const response = await this.s3Provider.getClient().send(
@@ -2774,14 +3150,6 @@ exports.StorageService = class StorageService {
2774
3150
  throw failureOrAbort(options.abortSignal, context, mapAwsError(err, context));
2775
3151
  }
2776
3152
  }
2777
- /**
2778
- * Server-side copy of an object (no bytes flow through the app). Supports both
2779
- * same-bucket and cross-bucket copies and preserves the source metadata.
2780
- *
2781
- * @param options - Source/destination keys and buckets plus copy overrides.
2782
- * @returns The new object's ETag.
2783
- * @throws StorageException mapped from any AWS failure.
2784
- */
2785
3153
  async copy(options) {
2786
3154
  this.assertConfigured();
2787
3155
  assertHeaderValues({ cacheControl: options.cacheControl });
@@ -2789,6 +3157,7 @@ exports.StorageService = class StorageService {
2789
3157
  const destKey = this.keyResolver.normalize(options.destinationKey);
2790
3158
  const sourceBucket = this.resolveBucket(options.sourceBucket);
2791
3159
  const destBucket = this.resolveBucket(options.destinationBucket);
3160
+ const acl = buildACL(options.publicRead, this.options.defaultPublicRead);
2792
3161
  try {
2793
3162
  const response = await this.s3Provider.getClient().send(
2794
3163
  new clientS3.CopyObjectCommand({
@@ -2799,25 +3168,18 @@ exports.StorageService = class StorageService {
2799
3168
  CopySource: `/${sourceBucket}/${sourceKey.split("/").map(encodeURIComponent).join("/")}`,
2800
3169
  CacheControl: options.cacheControl ?? this.options.defaultCacheControl,
2801
3170
  // ACLs are a no-op on modern S3 (Object Ownership) and R2; see header-utils.
2802
- ACL: buildACL(options.publicRead, this.options.defaultPublicRead),
3171
+ ACL: acl,
2803
3172
  MetadataDirective: "COPY"
2804
3173
  })
2805
3174
  );
2806
3175
  return { etag: response.CopyObjectResult?.ETag ?? "" };
2807
3176
  } catch (err) {
2808
- throw mapAwsError(err, { sourceKey, destKey, op: "copy" });
3177
+ throw mapAwsError(
3178
+ err,
3179
+ callDetails("copy", { sourceKey: options.sourceKey, destKey: options.destinationKey })
3180
+ );
2809
3181
  }
2810
3182
  }
2811
- /**
2812
- * Deletes many objects, chunking the input at the S3 hard limit of 1000 keys
2813
- * per request. Reports both successes and per-key failures; a whole-chunk send
2814
- * failure marks every key in that chunk as failed. Returned keys are stripped of
2815
- * the global prefix.
2816
- *
2817
- * @param keys - The raw object keys to delete.
2818
- * @param options - Optional per-call bucket override.
2819
- * @returns The deleted keys and the per-key failures.
2820
- */
2821
3183
  async deleteMany(keys, options) {
2822
3184
  this.assertConfigured();
2823
3185
  if (keys.length === 0) {
@@ -2844,6 +3206,34 @@ exports.StorageService = class StorageService {
2844
3206
  return { deleted, failed };
2845
3207
  }
2846
3208
  };
3209
+ __decorateClass([
3210
+ Observed("upload", {
3211
+ span: "storage.upload",
3212
+ describe: (result) => ({ "bymax.storage.multipart": result.multipart ? "true" : "false" }),
3213
+ bytes: uploadedBytesOf
3214
+ })
3215
+ ], exports.StorageService.prototype, "upload", 1);
3216
+ __decorateClass([
3217
+ Observed("head")
3218
+ ], exports.StorageService.prototype, "head", 1);
3219
+ __decorateClass([
3220
+ Observed("download")
3221
+ ], exports.StorageService.prototype, "download", 1);
3222
+ __decorateClass([
3223
+ Observed("delete")
3224
+ ], exports.StorageService.prototype, "delete", 1);
3225
+ __decorateClass([
3226
+ Observed("check_bucket")
3227
+ ], exports.StorageService.prototype, "checkBucket", 1);
3228
+ __decorateClass([
3229
+ Observed("list")
3230
+ ], exports.StorageService.prototype, "list", 1);
3231
+ __decorateClass([
3232
+ Observed("copy")
3233
+ ], exports.StorageService.prototype, "copy", 1);
3234
+ __decorateClass([
3235
+ Observed("delete_many")
3236
+ ], exports.StorageService.prototype, "deleteMany", 1);
2847
3237
  exports.StorageService = __decorateClass([
2848
3238
  common.Injectable(),
2849
3239
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
@@ -2851,7 +3241,9 @@ exports.StorageService = __decorateClass([
2851
3241
  __decorateParam(2, common.Inject(KeyResolverService)),
2852
3242
  __decorateParam(3, common.Inject(BYMAX_STORAGE_IDEMPOTENCY_CACHE)),
2853
3243
  __decorateParam(4, common.Inject(ValidationService)),
2854
- __decorateParam(5, common.Inject(FileScannerService))
3244
+ __decorateParam(5, common.Inject(FileScannerService)),
3245
+ __decorateParam(6, common.Optional()),
3246
+ __decorateParam(6, common.Inject(StorageObserver))
2855
3247
  ], exports.StorageService);
2856
3248
 
2857
3249
  // src/server/utils/ttl-clamp.ts
@@ -2871,25 +3263,16 @@ function clampTtl(ttlSeconds, defaultTtl, maxTtl) {
2871
3263
  // src/server/services/signed-url.service.ts
2872
3264
  var MAX_MULTIPART_PARTS = 1e4;
2873
3265
  exports.SignedUrlService = class SignedUrlService {
2874
- constructor(options, s3Provider, keyResolver) {
3266
+ constructor(options, s3Provider, keyResolver, observer) {
2875
3267
  this.options = options;
2876
3268
  this.s3Provider = s3Provider;
2877
3269
  this.keyResolver = keyResolver;
3270
+ this.observer = observer;
2878
3271
  }
2879
3272
  options;
2880
3273
  s3Provider;
2881
3274
  keyResolver;
2882
- /**
2883
- * Issues a presigned GET URL for downloading an object.
2884
- *
2885
- * SECURITY: The returned URL is a temporary credential. NEVER log it, store it
2886
- * in a database, or cache it across users. Issue a fresh URL per request.
2887
- *
2888
- * @param options - The download URL options.
2889
- * @returns The presigned URL and its expiry metadata.
2890
- * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
2891
- * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
2892
- */
3275
+ observer;
2893
3276
  async getDownloadUrl(options) {
2894
3277
  this.assertConfigured();
2895
3278
  assertHeaderValues({
@@ -2914,36 +3297,9 @@ exports.SignedUrlService = class SignedUrlService {
2914
3297
  return { url, expiresAt: new Date(Date.now() + ttl * 1e3), method: "GET", requiredHeaders: {} };
2915
3298
  } catch (err) {
2916
3299
  if (err instanceof StorageException) throw err;
2917
- throw mapAwsError(err, { key: finalKey, bucket, op: "getDownloadUrl" });
3300
+ throw mapAwsError(err, callDetails("getDownloadUrl", { key: options.key, bucket: options.bucket }));
2918
3301
  }
2919
3302
  }
2920
- /**
2921
- * Issues a presigned PUT URL for uploading an object. The client MUST send
2922
- * every header listed in `requiredHeaders` verbatim — each one is part of the
2923
- * URL signature, so an omitted header yields `SignatureDoesNotMatch`. The map
2924
- * always carries `Content-Type` and additionally lists `x-amz-acl` when an ACL
2925
- * is signed and an `x-amz-meta-<key>` entry per metadata pair. The `Content-Type`
2926
- * is signed (`X-Amz-SignedHeaders` lists `content-type`), so a PUT that sends any
2927
- * other type is refused by the provider and nothing is stored.
2928
- *
2929
- * SECURITY: The returned URL is a temporary credential — NEVER log it. A signed
2930
- * PUT bypasses the server-side MIME/size validation pipeline. Size limits are
2931
- * NOT enforced at presign time: a SigV4 PUT signature can only pin an exact
2932
- * `Content-Length`, never a maximum, so binding one would reject valid smaller
2933
- * uploads. Enforce size after the fact via a post-upload HEAD/size check plus
2934
- * the post-upload scanner path for defence-in-depth.
2935
- *
2936
- * ACL caveat: `publicRead` emits `ACL: public-read`, which returns HTTP 400
2937
- * `AccessControlListNotSupported` on modern AWS S3 buckets (Object Ownership
2938
- * = "Bucket owner enforced") and is a no-op on Cloudflare R2. Prefer a bucket
2939
- * policy, CDN, or signed GET URL for public delivery.
2940
- *
2941
- * @param options - The upload URL options.
2942
- * @returns The presigned URL, its expiry metadata, and required headers.
2943
- * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
2944
- * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
2945
- * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` when `validation.mimeWhitelist` is set and excludes `contentType`.
2946
- */
2947
3303
  async getUploadUrl(options) {
2948
3304
  this.assertConfigured();
2949
3305
  assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
@@ -2977,7 +3333,7 @@ exports.SignedUrlService = class SignedUrlService {
2977
3333
  };
2978
3334
  } catch (err) {
2979
3335
  if (err instanceof StorageException) throw err;
2980
- throw mapAwsError(err, { key: finalKey, bucket, op: "getUploadUrl" });
3336
+ throw mapAwsError(err, callDetails("getUploadUrl", { key: options.key, bucket: options.bucket }));
2981
3337
  }
2982
3338
  }
2983
3339
  /**
@@ -2998,21 +3354,6 @@ exports.SignedUrlService = class SignedUrlService {
2998
3354
  }
2999
3355
  return headers;
3000
3356
  }
3001
- /**
3002
- * Presigns a multipart upload: creates the upload session on S3, then returns
3003
- * N presigned `UploadPart` URLs (1-indexed) and a presigned `CompleteMultipart`
3004
- * URL. The client uploads parts directly to S3 and then calls the complete URL.
3005
- *
3006
- * SECURITY: All returned URLs are temporary credentials — NEVER log them.
3007
- *
3008
- * @param options - The multipart URL options.
3009
- * @returns `uploadId`, `partUrls`, and `completeUrl`.
3010
- * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
3011
- * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
3012
- * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
3013
- * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
3014
- * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` when `validation.mimeWhitelist` is set and excludes `contentType`.
3015
- */
3016
3357
  async getMultipartUploadUrls(options) {
3017
3358
  this.assertConfigured();
3018
3359
  assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
@@ -3042,14 +3383,16 @@ exports.SignedUrlService = class SignedUrlService {
3042
3383
  if (!uploadId) {
3043
3384
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR, void 0, {
3044
3385
  reason: "CreateMultipartUpload returned no UploadId",
3045
- key: finalKey,
3046
- bucket
3386
+ ...callerFields({ key: options.key, bucket: options.bucket })
3047
3387
  });
3048
3388
  }
3049
3389
  return await this.presignMultipartParts({ finalKey, bucket, uploadId, parts: options.parts, ttl });
3050
3390
  } catch (err) {
3051
3391
  if (err instanceof StorageException) throw err;
3052
- throw mapAwsError(err, { key: finalKey, bucket, op: "getMultipartUploadUrls" });
3392
+ throw mapAwsError(
3393
+ err,
3394
+ callDetails("getMultipartUploadUrls", { key: options.key, bucket: options.bucket })
3395
+ );
3053
3396
  }
3054
3397
  }
3055
3398
  /** Presigns all part URLs and the complete URL in parallel. */
@@ -3080,11 +3423,22 @@ exports.SignedUrlService = class SignedUrlService {
3080
3423
  return resolveBucket(perCall, this.options.bucket);
3081
3424
  }
3082
3425
  };
3426
+ __decorateClass([
3427
+ Observed("get_download_url", { span: "storage.download_url" })
3428
+ ], exports.SignedUrlService.prototype, "getDownloadUrl", 1);
3429
+ __decorateClass([
3430
+ Observed("get_upload_url")
3431
+ ], exports.SignedUrlService.prototype, "getUploadUrl", 1);
3432
+ __decorateClass([
3433
+ Observed("get_multipart_upload_urls")
3434
+ ], exports.SignedUrlService.prototype, "getMultipartUploadUrls", 1);
3083
3435
  exports.SignedUrlService = __decorateClass([
3084
3436
  common.Injectable(),
3085
3437
  __decorateParam(0, common.Inject(BYMAX_STORAGE_OPTIONS)),
3086
3438
  __decorateParam(1, common.Inject(S3ClientProvider)),
3087
- __decorateParam(2, common.Inject(KeyResolverService))
3439
+ __decorateParam(2, common.Inject(KeyResolverService)),
3440
+ __decorateParam(3, common.Optional()),
3441
+ __decorateParam(3, common.Inject(StorageObserver))
3088
3442
  ], exports.SignedUrlService);
3089
3443
  var IdempotencyCache = class {
3090
3444
  /**
@@ -3188,15 +3542,42 @@ var IdempotencyCache = class {
3188
3542
  };
3189
3543
 
3190
3544
  // src/server/bymax-storage.module.ts
3545
+ function refuseUnreadable(error) {
3546
+ if (isOwnRefusal(error)) throw error;
3547
+ throw new StorageException(
3548
+ STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG,
3549
+ void 0,
3550
+ { reason: "the options could not be read" },
3551
+ void 0,
3552
+ error
3553
+ );
3554
+ }
3191
3555
  function resolveAsyncOptions(raw) {
3556
+ try {
3557
+ return resolveOptions(raw);
3558
+ } catch (error) {
3559
+ return refuseUnreadable(error);
3560
+ }
3561
+ }
3562
+ async function resolveProducedOptions(produce) {
3563
+ try {
3564
+ return resolveOptions(await produce());
3565
+ } catch (error) {
3566
+ return refuseUnreadable(error);
3567
+ }
3568
+ }
3569
+ function resolveOptions(raw) {
3192
3570
  const options = snapshotOptions(raw);
3193
3571
  validateOptions(options);
3194
3572
  const resolved = applyDefaults(options);
3195
3573
  const configured = options.signedUrls?.maxTtlSeconds;
3196
3574
  if (configured !== void 0 && configured > resolved.signedUrls.maxTtlSeconds) {
3197
- new common.Logger(exports.BymaxStorageModule.name).warn(
3198
- `signedUrls.maxTtlSeconds=${String(configured)} exceeds the SigV4 presigned-URL limit; using ${String(resolved.signedUrls.maxTtlSeconds)} seconds (7 days) instead.`
3199
- );
3575
+ emit(new common.Logger(exports.BymaxStorageModule.name), "warn", {
3576
+ event: STORAGE_LOG_EVENTS.ttlClamped,
3577
+ message: "signedUrls.maxTtlSeconds exceeds the SigV4 presigned-URL limit; the limit is used instead",
3578
+ configuredSeconds: configured,
3579
+ appliedSeconds: resolved.signedUrls.maxTtlSeconds
3580
+ });
3200
3581
  }
3201
3582
  return resolved;
3202
3583
  }
@@ -3294,6 +3675,10 @@ exports.BymaxStorageModule = class BymaxStorageModule {
3294
3675
  DEFAULT_IDEMPOTENCY_CACHE_TTL_MS
3295
3676
  )
3296
3677
  },
3678
+ // The counts and the span seam the services report to; the optional `observability` subpath reads the tally.
3679
+ exports.StorageMetricsTally,
3680
+ StorageTracing,
3681
+ StorageObserver,
3297
3682
  exports.StorageService,
3298
3683
  exports.SignedUrlService,
3299
3684
  exports.BucketLifecycleService,
@@ -3320,6 +3705,7 @@ exports.BymaxStorageModule = class BymaxStorageModule {
3320
3705
  exports.StorageService,
3321
3706
  exports.SignedUrlService,
3322
3707
  exports.BucketLifecycleService,
3708
+ exports.StorageMetricsTally,
3323
3709
  BYMAX_STORAGE_OPTIONS,
3324
3710
  BYMAX_STORAGE_S3_CLIENT,
3325
3711
  BYMAX_STORAGE_UPLOAD_VALIDATORS,
@@ -3343,7 +3729,7 @@ exports.BymaxStorageModule = class BymaxStorageModule {
3343
3729
  if (useFactory) {
3344
3730
  return {
3345
3731
  provide: BYMAX_STORAGE_OPTIONS,
3346
- useFactory: async (...args) => resolveAsyncOptions(await useFactory(...args)),
3732
+ useFactory: (...args) => resolveProducedOptions(() => useFactory(...args)),
3347
3733
  inject: [...asyncOptions.inject ?? []]
3348
3734
  };
3349
3735
  }
@@ -3351,13 +3737,11 @@ exports.BymaxStorageModule = class BymaxStorageModule {
3351
3737
  if (factoryToken) {
3352
3738
  return {
3353
3739
  provide: BYMAX_STORAGE_OPTIONS,
3354
- useFactory: async (factory) => resolveAsyncOptions(await factory.createStorageOptions()),
3740
+ useFactory: (factory) => resolveProducedOptions(() => factory.createStorageOptions()),
3355
3741
  inject: [factoryToken]
3356
3742
  };
3357
3743
  }
3358
- throw new Error(
3359
- "BymaxStorageModule.forRootAsync requires useFactory, useClass, or useExisting"
3360
- );
3744
+ throw new Error("BymaxStorageModule.forRootAsync requires useFactory, useClass, or useExisting");
3361
3745
  }
3362
3746
  };
3363
3747
  exports.BymaxStorageModule = __decorateClass([
@@ -3488,6 +3872,9 @@ exports.BYMAX_STORAGE_S3_CLIENT = BYMAX_STORAGE_S3_CLIENT;
3488
3872
  exports.BYMAX_STORAGE_UPLOAD_VALIDATORS = BYMAX_STORAGE_UPLOAD_VALIDATORS;
3489
3873
  exports.NoOpFileScanner = NoOpFileScanner;
3490
3874
  exports.NoOpUploadValidator = NoOpUploadValidator;
3875
+ exports.SCAN_VERDICTS = SCAN_VERDICTS;
3491
3876
  exports.STORAGE_ERROR_CODES = STORAGE_ERROR_CODES;
3877
+ exports.STORAGE_OPERATIONS = STORAGE_OPERATIONS;
3878
+ exports.STORAGE_OUTCOMES = STORAGE_OUTCOMES;
3492
3879
  exports.StorageException = StorageException;
3493
3880
  exports.providerRecipes = providerRecipes;