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