@bymax-one/nest-storage 1.1.17 → 1.1.19

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");
@@ -142,9 +151,9 @@ var HEADER_VALUE = /^[\t \x21-\x7E]*$/;
142
151
  var HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
143
152
  var VALUE_REASON = "must be a string of tab, space and printable ASCII characters";
144
153
  var KEY_REASON = "every key must be a non-empty header name of letters, digits and the characters !#$%&'*+-.^_`|~";
145
- function refuse(field2, reason) {
154
+ function refuse(field, reason) {
146
155
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
147
- field: field2,
156
+ field,
148
157
  reason
149
158
  });
150
159
  }
@@ -152,9 +161,9 @@ function isHeaderValue(value) {
152
161
  return typeof value === "string" && HEADER_VALUE.test(value);
153
162
  }
154
163
  function assertHeaderValues(fields) {
155
- for (const [field2, value] of Object.entries(fields)) {
164
+ for (const [field, value] of Object.entries(fields)) {
156
165
  if (value !== void 0 && !isHeaderValue(value)) {
157
- refuse(field2, VALUE_REASON);
166
+ refuse(field, VALUE_REASON);
158
167
  }
159
168
  }
160
169
  }
@@ -176,6 +185,7 @@ function assertMetadata(metadata) {
176
185
  var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
177
186
  var MAX_PART_SIZE_BYTES = 5 * 1024 * 1024 * 1024;
178
187
  var MAX_QUEUE_SIZE = 1e3;
188
+ var REGION_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
179
189
  function invalid(reason) {
180
190
  return new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_CONFIG, HttpStatus.INTERNAL_SERVER_ERROR, {
181
191
  reason
@@ -226,7 +236,8 @@ function assertBoundedInteger(section, group, key, range) {
226
236
  }
227
237
  }
228
238
  function assertScanner(scanner) {
229
- if (scanner === void 0 || scanner === null) return;
239
+ if (scanner === void 0) return;
240
+ if (scanner === null) throw invalid("scanner must not be null; omit it for no scanner");
230
241
  if (!isObject(scanner)) throw invalid("scanner must be an object");
231
242
  const impl = scanner.impl;
232
243
  if (!isObject(impl) || typeof impl.scan !== "function") {
@@ -240,6 +251,50 @@ function assertScanner(scanner) {
240
251
  throw invalid("scanner.rejectOnUnknown must be a boolean");
241
252
  }
242
253
  }
254
+ function assertValidationKinds(validation) {
255
+ if (!isObject(validation)) return;
256
+ const { maxSizeBytes, mimeWhitelist, customValidators } = validation;
257
+ if (maxSizeBytes === null) {
258
+ throw invalid("validation.maxSizeBytes must not be null; omit it for no size limit");
259
+ }
260
+ if (mimeWhitelist === null) {
261
+ throw invalid("validation.mimeWhitelist must not be null; omit it to allow every type");
262
+ }
263
+ if (mimeWhitelist !== void 0 && !isStringArray(mimeWhitelist)) {
264
+ throw invalid("validation.mimeWhitelist must be an array of strings");
265
+ }
266
+ if (customValidators === null) {
267
+ throw invalid("validation.customValidators must not be null; omit it to run no custom validator");
268
+ }
269
+ if (customValidators !== void 0 && !Array.isArray(customValidators)) {
270
+ throw invalid("validation.customValidators must be an array");
271
+ }
272
+ if (customValidators !== void 0 && !isValidatorList(customValidators)) {
273
+ throw invalid("validation.customValidators must hold objects with a validate function");
274
+ }
275
+ }
276
+ function isStringArray(value) {
277
+ try {
278
+ return Array.isArray(value) && Array.from(value).every((entry) => typeof entry === "string");
279
+ } catch {
280
+ return false;
281
+ }
282
+ }
283
+ function isValidatorList(entries) {
284
+ try {
285
+ return Array.from(entries).every((entry) => isObject(entry) && typeof entry.validate === "function");
286
+ } catch {
287
+ return false;
288
+ }
289
+ }
290
+ function assertGroupKinds(options) {
291
+ for (const group of ["signedUrls", "multipart", "validation"]) {
292
+ const value = options[group];
293
+ if (value !== void 0 && value !== null && (!isObject(value) || Array.isArray(value))) {
294
+ throw invalid(`options.${group} must be an object`);
295
+ }
296
+ }
297
+ }
243
298
  function assertNumericSections(options) {
244
299
  const MAX = Number.MAX_SAFE_INTEGER;
245
300
  assertBoundedInteger(options.validation, "validation", "maxSizeBytes", { min: 1, max: MAX });
@@ -256,7 +311,9 @@ function assertNumericSections(options) {
256
311
  assertBoundedInteger(options.multipart, "multipart", "queueSize", { min: 1, max: MAX_QUEUE_SIZE });
257
312
  }
258
313
  function assertLimitsAndEncryption(options) {
314
+ assertGroupKinds(options);
259
315
  assertNumericSections(options);
316
+ assertValidationKinds(options.validation);
260
317
  assertScanner(options.scanner);
261
318
  const maxAttempts = options.maxAttempts;
262
319
  if (maxAttempts !== void 0 && (typeof maxAttempts !== "number" || !Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > Number.MAX_SAFE_INTEGER)) {
@@ -290,12 +347,23 @@ function validateOptions(options) {
290
347
  if (!isNonEmptyString(options.region)) {
291
348
  throw invalid("options.region must be a non-empty string");
292
349
  }
350
+ if (!REGION_SHAPE.test(options.region)) {
351
+ throw invalid(
352
+ "options.region must be 1 to 63 letters, digits, '.', '_' or '-', starting with a letter or digit"
353
+ );
354
+ }
293
355
  if (!isNonEmptyString(options.bucket)) {
294
356
  throw invalid("options.bucket must be a non-empty string");
295
357
  }
358
+ if (options.keyPrefix !== void 0 && options.keyPrefix !== null && typeof options.keyPrefix !== "string") {
359
+ throw invalid("options.keyPrefix must be a string");
360
+ }
296
361
  if (!isObject(options.credentials)) {
297
362
  throw invalid("options.credentials is required");
298
363
  }
364
+ if (Array.isArray(options.credentials)) {
365
+ throw invalid("options.credentials must be an object");
366
+ }
299
367
  assertLimitsAndEncryption(options);
300
368
  }
301
369
 
@@ -339,6 +407,41 @@ var DEFAULT_MULTIPART = {
339
407
  var DEFAULT_IDEMPOTENCY_CACHE_MAX_ENTRIES = 1e3;
340
408
  var DEFAULT_IDEMPOTENCY_CACHE_TTL_MS = 864e5;
341
409
 
410
+ // src/server/config/option-keys.ts
411
+ function keysOf() {
412
+ return (keys) => keys;
413
+ }
414
+ var OPTION_KEYS = keysOf()([
415
+ "endpoint",
416
+ "region",
417
+ "bucket",
418
+ "credentials",
419
+ "forcePathStyle",
420
+ "publicBaseUrl",
421
+ "cdnBaseUrl",
422
+ "defaultPublicRead",
423
+ "keyPrefix",
424
+ "defaultCacheControl",
425
+ "defaultContentDisposition",
426
+ "signedUrls",
427
+ "multipart",
428
+ "validation",
429
+ "scanner",
430
+ "serverSideEncryption",
431
+ "kmsKeyId",
432
+ "requestChecksumCalculation",
433
+ "responseChecksumValidation",
434
+ "maxAttempts",
435
+ "requestTimeoutMs",
436
+ "uploadIdleTimeoutMs",
437
+ "bodyIdleTimeoutMs"
438
+ ]);
439
+ var CREDENTIAL_KEYS = keysOf()(["accessKeyId", "secretAccessKey", "sessionToken"]);
440
+ var SIGNED_URL_KEYS = keysOf()(["defaultGetTtlSeconds", "defaultPutTtlSeconds", "maxTtlSeconds"]);
441
+ var MULTIPART_KEYS = keysOf()(["thresholdBytes", "partSizeBytes", "queueSize"]);
442
+ var VALIDATION_KEYS = keysOf()(["mimeWhitelist", "maxSizeBytes", "customValidators"]);
443
+ var SCANNER_KEYS = keysOf()(["impl", "mode", "rejectOnUnknown", "timeoutMs"]);
444
+
342
445
  // src/server/config/apply-defaults.ts
343
446
  function definedOnly(group, keys) {
344
447
  const picked = {};
@@ -348,10 +451,6 @@ function definedOnly(group, keys) {
348
451
  }
349
452
  return picked;
350
453
  }
351
- var SIGNED_URL_KEYS = ["defaultGetTtlSeconds", "defaultPutTtlSeconds", "maxTtlSeconds"];
352
- var MULTIPART_KEYS = ["thresholdBytes", "partSizeBytes", "queueSize"];
353
- var VALIDATION_KEYS = ["mimeWhitelist", "maxSizeBytes", "customValidators"];
354
- var SCANNER_KEYS = ["impl", "mode", "rejectOnUnknown", "timeoutMs"];
355
454
  function resolveSignedUrls(configured) {
356
455
  const merged = { ...DEFAULT_SIGNED_URLS, ...definedOnly(configured, SIGNED_URL_KEYS) };
357
456
  return { ...merged, maxTtlSeconds: Math.min(merged.maxTtlSeconds, MAX_SIGNED_URL_TTL_SECONDS) };
@@ -382,7 +481,7 @@ function applyDefaults(options) {
382
481
  signedUrls: resolveSignedUrls(options.signedUrls),
383
482
  multipart: { ...DEFAULT_MULTIPART, ...definedOnly(options.multipart, MULTIPART_KEYS) },
384
483
  ...options.validation !== void 0 ? { validation: definedOnly(options.validation, VALIDATION_KEYS) } : {},
385
- // `null` is no scanner, as `undefined` is: a group is an object or it is not configured.
484
+ // A group is an object or it is not configured. `forRoot` refuses a `null` scanner before this runs; if one reaches here it adds no scanner.
386
485
  ...options.scanner ? { scanner: definedOnly(options.scanner, SCANNER_KEYS) } : {},
387
486
  ...options.serverSideEncryption !== void 0 ? { serverSideEncryption: options.serverSideEncryption } : {},
388
487
  ...options.kmsKeyId !== void 0 ? { kmsKeyId: options.kmsKeyId } : {},
@@ -398,16 +497,81 @@ function applyDefaults(options) {
398
497
  return resolved;
399
498
  }
400
499
 
401
- // src/server/utils/describe-endpoint.ts
402
- function describeEndpoint(endpoint) {
500
+ // src/server/config/snapshot-options.ts
501
+ function isObject2(value) {
502
+ return typeof value === "object" && value !== null;
503
+ }
504
+ function pick(source, keys) {
505
+ const copy = {};
506
+ for (const key of keys) {
507
+ const value = source[key];
508
+ if (value !== void 0) copy[key] = value;
509
+ }
510
+ return copy;
511
+ }
512
+ function pickGroup(value, keys) {
513
+ return isObject2(value) && !Array.isArray(value) ? pick(value, keys) : value;
514
+ }
515
+ function copyArray(value) {
516
+ if (!Array.isArray(value)) return value;
517
+ try {
518
+ return Array.from(value);
519
+ } catch {
520
+ return value;
521
+ }
522
+ }
523
+ var GROUPS = {
524
+ credentials: CREDENTIAL_KEYS,
525
+ signedUrls: SIGNED_URL_KEYS,
526
+ multipart: MULTIPART_KEYS,
527
+ validation: VALIDATION_KEYS,
528
+ scanner: SCANNER_KEYS
529
+ };
530
+ function snapshotOptions(options) {
531
+ if (!isObject2(options)) return options;
532
+ const copy = pick(options, OPTION_KEYS);
533
+ for (const [group, keys] of Object.entries(GROUPS)) {
534
+ if (group in copy) copy[group] = pickGroup(copy[group], keys);
535
+ }
536
+ const validation = copy.validation;
537
+ if (isObject2(validation)) {
538
+ for (const key of ["mimeWhitelist", "customValidators"]) {
539
+ if (key in validation) validation[key] = copyArray(validation[key]);
540
+ }
541
+ }
542
+ return copy;
543
+ }
544
+
545
+ // src/server/utils/absorb.ts
546
+ function absorb(call) {
403
547
  try {
404
- const url = new URL(endpoint);
405
- return `${url.protocol}//${url.host}`;
548
+ void Promise.resolve(call()).then(void 0, () => void 0);
406
549
  } catch {
407
- return "<unparseable endpoint>";
408
550
  }
409
551
  }
410
552
 
553
+ // src/server/utils/log-event.ts
554
+ function emit(sink, level, entry) {
555
+ absorb(() => sink[level](entry));
556
+ }
557
+
558
+ // src/server/utils/log-events.ts
559
+ var STORAGE_LOG_EVENTS = {
560
+ ttlClamped: "STORAGE_TTL_CLAMPED",
561
+ credentialsMissing: "STORAGE_CREDENTIALS_MISSING",
562
+ clientReady: "STORAGE_CLIENT_READY",
563
+ providerCallFailed: "STORAGE_PROVIDER_CALL_FAILED",
564
+ multipartAbortFailed: "STORAGE_MULTIPART_ABORT_FAILED",
565
+ scanInfected: "STORAGE_SCAN_INFECTED",
566
+ scanInconclusiveAccepted: "STORAGE_SCAN_INCONCLUSIVE_ACCEPTED",
567
+ scanInconclusiveRejected: "STORAGE_SCAN_INCONCLUSIVE_REJECTED",
568
+ scanFailed: "STORAGE_SCAN_FAILED",
569
+ scanTimeout: "STORAGE_SCAN_TIMEOUT",
570
+ scanCleanupFailed: "STORAGE_SCAN_CLEANUP_FAILED",
571
+ existsFailed: "STORAGE_EXISTS_FAILED",
572
+ deleteNotFound: "STORAGE_DELETE_NOT_FOUND"
573
+ };
574
+
411
575
  // src/server/providers/s3-client.provider.ts
412
576
  var S3ClientProvider = class {
413
577
  constructor(options) {
@@ -418,9 +582,10 @@ var S3ClientProvider = class {
418
582
  client;
419
583
  onModuleInit() {
420
584
  if (!this.options.hasCredentials) {
421
- this.logger.warn(
422
- "Storage credentials are missing \u2014 module is registered but operations will throw STORAGE_NOT_CONFIGURED."
423
- );
585
+ emit(this.logger, "warn", {
586
+ event: STORAGE_LOG_EVENTS.credentialsMissing,
587
+ message: "Storage credentials are missing \u2014 module is registered but operations will throw STORAGE_NOT_CONFIGURED."
588
+ });
424
589
  return;
425
590
  }
426
591
  this.resolveClient();
@@ -493,9 +658,10 @@ var S3ClientProvider = class {
493
658
  requestChecksumCalculation: this.options.requestChecksumCalculation,
494
659
  responseChecksumValidation: this.options.responseChecksumValidation
495
660
  };
496
- this.logger.log(
497
- `S3Client initialized: endpoint=${describeEndpoint(this.options.endpoint)} region=${this.options.region}`
498
- );
661
+ emit(this.logger, "log", {
662
+ event: STORAGE_LOG_EVENTS.clientReady,
663
+ message: "S3Client initialized"
664
+ });
499
665
  return new S3Client(config);
500
666
  }
501
667
  };
@@ -564,62 +730,282 @@ KeyResolverService = __decorateClass([
564
730
  __decorateParam(0, Inject(BYMAX_STORAGE_OPTIONS))
565
731
  ], KeyResolverService);
566
732
 
567
- // src/server/utils/describe-error.ts
568
- var NON_PRINTABLE_REJECTION = "non-printable rejection value";
569
- function describeError(value) {
570
- try {
571
- if (typeof value === "object" && value !== null) {
572
- const message = value.message;
573
- if (typeof message === "string") {
574
- return message;
575
- }
733
+ // src/server/observability/storage-operations.ts
734
+ var STORAGE_OPERATIONS = [
735
+ "upload",
736
+ "download",
737
+ "head",
738
+ "delete",
739
+ "delete_many",
740
+ "list",
741
+ "copy",
742
+ "get_download_url",
743
+ "get_upload_url",
744
+ "get_multipart_upload_urls",
745
+ "check_bucket",
746
+ "lifecycle_get",
747
+ "lifecycle_upsert",
748
+ "lifecycle_remove"
749
+ ];
750
+ var STORAGE_OUTCOMES = ["success", "not_found", "aborted", "error"];
751
+ var SCAN_VERDICTS = ["clean", "infected", "unknown", "timeout", "error"];
752
+ function outcomeOf(error) {
753
+ if (!(error instanceof StorageException)) return "error";
754
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) return "not_found";
755
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED || error.code === STORAGE_ERROR_CODES.STORAGE_MULTIPART_ABORTED) {
756
+ return "aborted";
757
+ }
758
+ return "error";
759
+ }
760
+ function scanVerdictOfError(error) {
761
+ if (!(error instanceof StorageException)) return "error";
762
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_SCAN_INFECTED) return "infected";
763
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_SCAN_INCONCLUSIVE) return "unknown";
764
+ if (error.code === STORAGE_ERROR_CODES.STORAGE_TIMEOUT) return "timeout";
765
+ return "error";
766
+ }
767
+
768
+ // src/server/observability/storage-metrics-tally.ts
769
+ function zeroed(keys) {
770
+ return Object.fromEntries(keys.map((key) => [key, 0]));
771
+ }
772
+ var _operations, _scans, _listeners, _bytesUploaded;
773
+ var StorageMetricsTally = class {
774
+ constructor() {
775
+ __privateAdd(this, _operations, Object.fromEntries(
776
+ STORAGE_OPERATIONS.map((operation) => [operation, zeroed(STORAGE_OUTCOMES)])
777
+ ));
778
+ __privateAdd(this, _scans, zeroed(SCAN_VERDICTS));
779
+ __privateAdd(this, _listeners, []);
780
+ __privateAdd(this, _bytesUploaded, 0);
781
+ }
782
+ /** An operation ended as `outcome` after `seconds`. */
783
+ operation(operation, outcome, seconds) {
784
+ __privateGet(this, _operations)[operation][outcome] += 1;
785
+ for (const listener of __privateGet(this, _listeners)) absorb(() => listener(operation, seconds));
786
+ }
787
+ /** `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. */
788
+ bytesUploaded(bytes) {
789
+ if (typeof bytes === "number" && Number.isFinite(bytes) && bytes > 0)
790
+ __privateSet(this, _bytesUploaded, __privateGet(this, _bytesUploaded) + bytes);
791
+ }
792
+ /** A scan ended as `verdict`. */
793
+ scan(verdict) {
794
+ __privateGet(this, _scans)[verdict] += 1;
795
+ }
796
+ /** Calls `listener` with the duration of every operation that ends from now on. */
797
+ onDuration(listener) {
798
+ __privateGet(this, _listeners).push(listener);
799
+ }
800
+ /** The counts so far, as copies. */
801
+ snapshot() {
802
+ return {
803
+ operations: Object.fromEntries(
804
+ STORAGE_OPERATIONS.map((operation) => [operation, { ...__privateGet(this, _operations)[operation] }])
805
+ ),
806
+ bytesUploaded: __privateGet(this, _bytesUploaded),
807
+ scans: { ...__privateGet(this, _scans) }
808
+ };
809
+ }
810
+ };
811
+ _operations = new WeakMap();
812
+ _scans = new WeakMap();
813
+ _listeners = new WeakMap();
814
+ _bytesUploaded = new WeakMap();
815
+ StorageMetricsTally = __decorateClass([
816
+ Injectable()
817
+ ], StorageMetricsTally);
818
+ var STATUS_ERROR = 2;
819
+ var TRACER_NAME = "@bymax-one/nest-storage";
820
+ var LIBRARY_CODE = /^STORAGE_[A-Z_]+$/;
821
+ function codeOf(error) {
822
+ if (!(error instanceof StorageException)) return "STORAGE_ERROR";
823
+ return LIBRARY_CODE.test(error.code) ? error.code : "STORAGE_ERROR";
824
+ }
825
+ var _api;
826
+ var StorageTracing = class {
827
+ constructor() {
828
+ __privateAdd(this, _api);
829
+ }
830
+ /** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
831
+ async onModuleInit() {
832
+ try {
833
+ const loaded = await import('@opentelemetry/api');
834
+ __privateSet(this, _api, loaded);
835
+ } catch {
576
836
  }
577
- return String(value);
578
- } catch {
579
- return NON_PRINTABLE_REJECTION;
580
837
  }
838
+ /** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
839
+ async traced(span, run, describe) {
840
+ let result;
841
+ try {
842
+ result = await run();
843
+ } catch (error) {
844
+ absorb(() => span.setAttributes({ "bymax.storage.outcome": outcomeOf(error) }));
845
+ absorb(() => span.setStatus({ code: STATUS_ERROR, message: codeOf(error) }));
846
+ absorb(() => span.end());
847
+ throw error;
848
+ }
849
+ absorb(() => span.setAttributes({ "bymax.storage.outcome": "success", ...describe(result) }));
850
+ absorb(() => span.end());
851
+ return result;
852
+ }
853
+ /**
854
+ * Runs `run` inside a span named `name`.
855
+ *
856
+ * The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
857
+ * throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
858
+ * otherwise, and its own result or error is what comes back.
859
+ *
860
+ * @param name - One of the library's span names.
861
+ * @param attributes - Closed-set attributes of the span.
862
+ * @param run - The operation; its result or its error passes through unchanged.
863
+ * @param describe - What the span states of a successful result; a throw of its own is the operation's own.
864
+ */
865
+ span(name, attributes, run, describe = () => ({})) {
866
+ const api = __privateGet(this, _api);
867
+ if (!api) return run();
868
+ const latch = { claimed: false };
869
+ absorb(
870
+ () => api.trace.getTracer(TRACER_NAME).startActiveSpan(name, { attributes }, (span) => {
871
+ if (!latch.claimed) {
872
+ latch.claimed = true;
873
+ latch.started = this.traced(span, run, describe);
874
+ }
875
+ return latch.started;
876
+ })
877
+ );
878
+ if (latch.started) return latch.started;
879
+ latch.claimed = true;
880
+ return run();
881
+ }
882
+ };
883
+ _api = new WeakMap();
884
+ StorageTracing = __decorateClass([
885
+ Injectable()
886
+ ], StorageTracing);
887
+
888
+ // src/server/observability/storage-observer.ts
889
+ function secondsSince(startedAt) {
890
+ return Number(process.hrtime.bigint() - startedAt) / 1e9;
891
+ }
892
+ var StorageObserver = class {
893
+ constructor(tally, tracing) {
894
+ this.tally = tally;
895
+ this.tracing = tracing;
896
+ }
897
+ tally;
898
+ tracing;
899
+ /**
900
+ * Runs `run`, counting how it ended and how long it took.
901
+ *
902
+ * @param operation - The operation, one of the closed set.
903
+ * @param run - The operation; its result or its error passes through unchanged.
904
+ * @param options - A span to start, and what to state of the result.
905
+ */
906
+ observe(operation, run, options = {}) {
907
+ const counted = async () => {
908
+ const startedAt = process.hrtime.bigint();
909
+ let result;
910
+ try {
911
+ result = await run();
912
+ } catch (error) {
913
+ absorb(() => {
914
+ this.tally.operation(operation, outcomeOf(error), secondsSince(startedAt));
915
+ });
916
+ throw error;
917
+ }
918
+ absorb(() => {
919
+ this.tally.operation(operation, "success", secondsSince(startedAt));
920
+ this.tally.bytesUploaded(options.bytes?.(result));
921
+ });
922
+ return result;
923
+ };
924
+ return options.span === void 0 ? counted() : this.tracing.span(options.span, options.attributes ?? {}, counted, options.describe);
925
+ }
926
+ /**
927
+ * Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
928
+ *
929
+ * @param mode - When the scan runs, `pre-upload` or `post-upload`.
930
+ * @param run - The scan; its result or its error passes through unchanged.
931
+ */
932
+ scan(mode, run) {
933
+ const counted = async () => {
934
+ try {
935
+ const result = await run();
936
+ absorb(() => {
937
+ this.tally.scan(result.status === "unknown" ? "unknown" : "clean");
938
+ });
939
+ return result;
940
+ } catch (error) {
941
+ absorb(() => {
942
+ this.tally.scan(scanVerdictOfError(error));
943
+ });
944
+ throw error;
945
+ }
946
+ };
947
+ return this.tracing.span("storage.scan", { "bymax.storage.scan_mode": mode }, counted);
948
+ }
949
+ };
950
+ StorageObserver = __decorateClass([
951
+ Injectable(),
952
+ __decorateParam(0, Inject(StorageMetricsTally)),
953
+ __decorateParam(1, Inject(StorageTracing))
954
+ ], StorageObserver);
955
+ function Observed(operation, options = {}) {
956
+ return (_target, _key, descriptor) => {
957
+ const original = descriptor.value;
958
+ descriptor.value = function(...args) {
959
+ const run = () => original.apply(this, args);
960
+ return this.observer === void 0 ? run() : this.observer.observe(operation, run, options);
961
+ };
962
+ };
581
963
  }
582
964
 
583
- // src/server/utils/log-value.ts
584
- var LEFT_LITERAL_BY_JSON = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
585
- function logValue(value) {
586
- const text = typeof value === "string" ? value : describeError(value);
587
- return JSON.stringify(text).replace(
588
- LEFT_LITERAL_BY_JSON,
589
- (char) => {
590
- const codePoint = Number(char.codePointAt(0));
591
- const hex = codePoint.toString(16);
592
- return codePoint > 65535 ? `\\u{${hex}}` : `\\u${hex.padStart(4, "0")}`;
593
- }
594
- );
965
+ // src/server/utils/call-details.ts
966
+ var MAX_CALLER_TEXT_LENGTH = 1024;
967
+ function callerFields(given) {
968
+ const fields = {};
969
+ for (const [field, value] of Object.entries(given)) {
970
+ if (typeof value === "string" && value.length <= MAX_CALLER_TEXT_LENGTH) fields[field] = value;
971
+ }
972
+ return fields;
973
+ }
974
+ function callDetails(op, given, extra = {}) {
975
+ return { ...callerFields(given), op, ...extra };
595
976
  }
596
977
 
597
- // src/server/utils/provider-failure-log.ts
598
- var SECRET_IN_MESSAGE = /(X-Amz-(?:Signature|Credential|Security-Token)|AWSAccessKeyId|Credential|Signature)=[^&\s"']+/gi;
599
- var BARE_ACCESS_KEY_ID = /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
600
- var MAX_MESSAGE_LENGTH = 300;
601
- var logger = new Logger("StorageProvider");
602
- function field(value) {
603
- return typeof value === "string" || typeof value === "number" ? logValue(value) : "-";
978
+ // src/server/utils/call-input.ts
979
+ function wrongKind(field, needs) {
980
+ return new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
981
+ field,
982
+ reason: `${field} must be ${needs}`
983
+ });
604
984
  }
605
- function describeProviderFailure(err) {
606
- const failure = typeof err === "object" && err !== null ? err : {};
607
- const message = describeError(err).replace(SECRET_IN_MESSAGE, "$1=[redacted]").replace(BARE_ACCESS_KEY_ID, "[redacted-key-id]");
608
- return [
609
- `name=${field(failure.name)}`,
610
- `code=${field(failure.Code)}`,
611
- `status=${field(failure.$metadata?.httpStatusCode)}`,
612
- `requestId=${field(failure.$metadata?.requestId)}`,
613
- `message=${logValue(message.slice(0, MAX_MESSAGE_LENGTH))}`
614
- ].join(" ");
985
+ function resolveBucket(perCall, moduleDefault) {
986
+ if (perCall !== void 0 && perCall !== null && typeof perCall !== "string") {
987
+ throw wrongKind("bucket", "a string");
988
+ }
989
+ const bucket = perCall ?? moduleDefault;
990
+ if (!bucket) {
991
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED);
992
+ }
993
+ return bucket;
615
994
  }
616
- function logProviderFailure(err, context, label = "Provider call failed") {
617
- if (err?.name === "AbortError") {
618
- return;
995
+ function assertAbortSignal(signal) {
996
+ if (signal === void 0 || signal === null) return;
997
+ if (!hasSignalSurface(signal)) {
998
+ throw wrongKind("abortSignal", "an AbortSignal");
999
+ }
1000
+ }
1001
+ function hasSignalSurface(signal) {
1002
+ if (typeof signal !== "object") return false;
1003
+ const candidate = signal;
1004
+ try {
1005
+ return typeof candidate.aborted === "boolean" && typeof candidate.addEventListener === "function";
1006
+ } catch {
1007
+ return false;
619
1008
  }
620
- const op = typeof context?.op === "string" ? logValue(context.op) : "-";
621
- const key = typeof context?.key === "string" ? logValue(context.key) : "-";
622
- logger.warn(`${label}: op=${op} key=${key} ${describeProviderFailure(err)}`);
623
1009
  }
624
1010
  var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
625
1011
  "ECONNREFUSED",
@@ -687,6 +1073,106 @@ function providerFailureStatus(err) {
687
1073
  return failure === "credentials-refused" ? HttpStatus.INTERNAL_SERVER_ERROR : void 0;
688
1074
  }
689
1075
 
1076
+ // src/server/utils/cut-text.ts
1077
+ function cutText(text, max) {
1078
+ if (text.length <= max) return text;
1079
+ const lastKept = text.charCodeAt(max - 1);
1080
+ const splitsPair = lastKept >= 55296 && lastKept <= 56319;
1081
+ return text.slice(0, splitsPair ? max - 1 : max);
1082
+ }
1083
+
1084
+ // src/server/utils/describe-error.ts
1085
+ var NON_PRINTABLE_REJECTION = "non-printable rejection value";
1086
+ function describeError(value) {
1087
+ try {
1088
+ if (typeof value === "object" && value !== null) {
1089
+ const message = value.message;
1090
+ if (typeof message === "string") {
1091
+ return message;
1092
+ }
1093
+ }
1094
+ return String(value);
1095
+ } catch {
1096
+ return NON_PRINTABLE_REJECTION;
1097
+ }
1098
+ }
1099
+
1100
+ // src/server/utils/log-value.ts
1101
+ var LEFT_LITERAL_BY_JSON = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
1102
+ var SHORT_ESCAPES = {
1103
+ "\b": "\\b",
1104
+ "\f": "\\f",
1105
+ "\n": "\\n",
1106
+ "\r": "\\r",
1107
+ " ": "\\t"
1108
+ };
1109
+ function escapeChar(char) {
1110
+ const short = SHORT_ESCAPES[char];
1111
+ if (short !== void 0) return short;
1112
+ const codePoint = Number(char.codePointAt(0));
1113
+ const hex = codePoint.toString(16);
1114
+ return codePoint > 65535 ? `\\u{${hex}}` : `\\u${hex.padStart(4, "0")}`;
1115
+ }
1116
+ function escapeForLog(text) {
1117
+ return text.replace(LEFT_LITERAL_BY_JSON, escapeChar);
1118
+ }
1119
+
1120
+ // src/server/utils/provider-failure-log.ts
1121
+ var SECRET_IN_MESSAGE = /(X-Amz-(?:Signature|Credential|Security-Token)|AWSAccessKeyId|Credential|Signature)=[^&\s"']+/gi;
1122
+ var BARE_ACCESS_KEY_ID = /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
1123
+ var MAX_MESSAGE_LENGTH = 300;
1124
+ var logger = new Logger("StorageProvider");
1125
+ var MAX_FIELD_LENGTH = 128;
1126
+ function readOrUndefined(read) {
1127
+ try {
1128
+ return read();
1129
+ } catch {
1130
+ return void 0;
1131
+ }
1132
+ }
1133
+ function textField(value) {
1134
+ return typeof value === "string" ? escapeForLog(cutText(value, MAX_FIELD_LENGTH)) : void 0;
1135
+ }
1136
+ function projectProviderFailure(err) {
1137
+ const failure = typeof err === "object" && err !== null ? err : {};
1138
+ const message = describeError(err).replace(SECRET_IN_MESSAGE, "$1=[redacted]").replace(BARE_ACCESS_KEY_ID, "[redacted-key-id]");
1139
+ const status = readOrUndefined(() => failure.$metadata?.httpStatusCode);
1140
+ const name = textField(readOrUndefined(() => failure.name));
1141
+ const awsCode = textField(readOrUndefined(() => failure.Code));
1142
+ const requestId = textField(readOrUndefined(() => failure.$metadata?.requestId));
1143
+ return {
1144
+ ...name !== void 0 ? { name } : {},
1145
+ ...awsCode !== void 0 ? { awsCode } : {},
1146
+ ...typeof status === "number" ? { httpStatus: status } : {},
1147
+ ...requestId !== void 0 ? { requestId } : {},
1148
+ message: escapeForLog(cutText(message, MAX_MESSAGE_LENGTH))
1149
+ };
1150
+ }
1151
+ function failureError(err) {
1152
+ const view = projectProviderFailure(err);
1153
+ const error = new Error(view.message);
1154
+ if (view.name !== void 0) error.name = view.name;
1155
+ if (view.awsCode !== void 0)
1156
+ Object.defineProperty(error, "awsCode", { value: view.awsCode, enumerable: true });
1157
+ return error;
1158
+ }
1159
+ function logProviderFailure(err, context, label = "Provider call failed") {
1160
+ if (readOrUndefined(() => err?.name) === "AbortError") {
1161
+ return;
1162
+ }
1163
+ const view = projectProviderFailure(err);
1164
+ emit(logger, "warn", {
1165
+ event: STORAGE_LOG_EVENTS.providerCallFailed,
1166
+ message: label,
1167
+ ...typeof context?.op === "string" ? { operation: escapeForLog(context.op) } : {},
1168
+ ...view.awsCode !== void 0 ? { awsCode: view.awsCode } : {},
1169
+ ...view.httpStatus !== void 0 ? { httpStatus: view.httpStatus } : {},
1170
+ ...view.requestId !== void 0 ? { requestId: view.requestId } : {},
1171
+ reason: readOrUndefined(() => providerFailureReason(err)) ?? "rejected",
1172
+ err: failureError(err)
1173
+ });
1174
+ }
1175
+
690
1176
  // src/server/errors/aws-error-mapper.ts
691
1177
  function awsCodeOf(err) {
692
1178
  const e = err ?? {};
@@ -806,54 +1292,32 @@ function ruleInvalid(reason) {
806
1292
  reason
807
1293
  });
808
1294
  }
809
- function assertDays(field2, value) {
1295
+ function assertDays(field, value) {
810
1296
  if (!Number.isInteger(value) || value < 1) {
811
- throw ruleInvalid(`${field2} must be an integer of at least 1`);
1297
+ throw ruleInvalid(`${field} must be an integer of at least 1`);
812
1298
  }
813
1299
  }
814
1300
  var BucketLifecycleService = class {
815
- constructor(options, s3Provider, keyResolver) {
1301
+ constructor(options, s3Provider, keyResolver, observer) {
816
1302
  this.options = options;
817
1303
  this.s3Provider = s3Provider;
818
1304
  this.keyResolver = keyResolver;
1305
+ this.observer = observer;
819
1306
  }
820
1307
  options;
821
1308
  s3Provider;
822
1309
  keyResolver;
823
- /**
824
- * Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
825
- * yields an empty array. Key prefixes inside the module's `keyPrefix` come back
826
- * relative to it, as `list()` returns keys, so a prefix read here can be passed
827
- * straight to `upsert()` without being prefixed twice. A rule that is not confined
828
- * to `keyPrefix` is returned exactly as stored, flagged `isOutsideKeyPrefix: true`;
829
- * everything else about a rule is returned as the provider stores it.
830
- *
831
- * @param options - Optional per-call bucket override.
832
- * @returns Every rule in the bucket.
833
- * @throws StorageException for missing configuration, an unsupported provider, or a provider error.
834
- */
1310
+ observer;
835
1311
  async get(options) {
836
1312
  this.assertConfigured();
837
1313
  const bucket = this.resolveBucket(options?.bucket);
838
- return (await this.read(bucket)).rules.map((rule) => this.toView(rule));
1314
+ return (await this.read(bucket, options?.bucket)).rules.map((rule) => this.toView(rule));
839
1315
  }
840
- /**
841
- * Adds the expiration or multipart-abort rule, or replaces the rule with the same id, and writes
842
- * the full set back. Rules with other ids are sent exactly as they were read.
843
- *
844
- * @param rule - The rule id, key prefix and either `expirationDays` or `abortIncompleteMultipartDays`.
845
- * @param options - Optional per-call bucket override.
846
- * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id, prefix or day count, or an id
847
- * that names a rule outside `keyPrefix`;
848
- * `STORAGE_LIFECYCLE_UNSUPPORTED` / `STORAGE_LIFECYCLE_REJECTED` from the provider.
849
- * @example
850
- * await lifecycle.upsert({ id: 'expire-tmp', prefix: 'expiring/', expirationDays: 7 })
851
- */
852
1316
  async upsert(rule, options) {
853
1317
  this.assertConfigured();
854
1318
  const owned = this.toRule(rule);
855
1319
  const bucket = this.resolveBucket(options?.bucket);
856
- const snapshot = await this.read(bucket);
1320
+ const snapshot = await this.read(bucket, options?.bucket);
857
1321
  const index = snapshot.rules.findIndex((existing) => existing.ID === owned.ID);
858
1322
  this.assertOwnable(snapshot.rules[index]);
859
1323
  const rules = [...snapshot.rules];
@@ -862,30 +1326,20 @@ var BucketLifecycleService = class {
862
1326
  } else {
863
1327
  rules[index] = owned;
864
1328
  }
865
- await this.write(bucket, rules, snapshot, "upsert");
1329
+ await this.write(bucket, options?.bucket, rules, snapshot, "upsert");
866
1330
  }
867
- /**
868
- * Removes the rule with this id. When it was the last rule the configuration is
869
- * deleted, because S3 rejects a write with no rules. An unknown id changes nothing.
870
- *
871
- * @param id - The rule id.
872
- * @param options - Optional per-call bucket override.
873
- * @returns `true` when a rule was removed, `false` when no rule had that id.
874
- * @throws StorageException `STORAGE_LIFECYCLE_RULE_INVALID` for a bad id or an id that names a rule
875
- * outside `keyPrefix`; a provider failure otherwise.
876
- */
877
1331
  async remove(id, options) {
878
1332
  this.assertConfigured();
879
1333
  this.assertRuleId(id);
880
1334
  const bucket = this.resolveBucket(options?.bucket);
881
- const snapshot = await this.read(bucket);
1335
+ const snapshot = await this.read(bucket, options?.bucket);
882
1336
  const target = snapshot.rules.find((existing) => existing.ID === id);
883
1337
  if (target === void 0) {
884
1338
  return false;
885
1339
  }
886
1340
  this.assertOwnable(target);
887
1341
  const rules = snapshot.rules.filter((existing) => existing.ID !== id);
888
- await this.write(bucket, rules, snapshot, "remove");
1342
+ await this.write(bucket, options?.bucket, rules, snapshot, "remove");
889
1343
  return true;
890
1344
  }
891
1345
  /**
@@ -939,7 +1393,7 @@ var BucketLifecycleService = class {
939
1393
  };
940
1394
  }
941
1395
  /** Reads the configuration; "none yet" is an empty snapshot. */
942
- async read(bucket) {
1396
+ async read(bucket, perCall) {
943
1397
  try {
944
1398
  const response = await this.s3Provider.getClient().send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
945
1399
  return {
@@ -950,7 +1404,7 @@ var BucketLifecycleService = class {
950
1404
  if (isNoLifecycleConfiguration(err)) {
951
1405
  return { rules: [], transitionDefaultMinimumObjectSize: void 0 };
952
1406
  }
953
- throw mapLifecycleError(err, { bucket, op: "lifecycle.get" });
1407
+ throw mapLifecycleError(err, callDetails("lifecycle.get", { bucket: perCall }));
954
1408
  }
955
1409
  }
956
1410
  /**
@@ -958,7 +1412,7 @@ var BucketLifecycleService = class {
958
1412
  * requires at least one rule on a put. The default-minimum-object-size setting
959
1413
  * read earlier is sent back so a write does not silently change transition behaviour.
960
1414
  */
961
- async write(bucket, rules, snapshot, op) {
1415
+ async write(bucket, perCall, rules, snapshot, op) {
962
1416
  const client = this.s3Provider.getClient();
963
1417
  try {
964
1418
  if (rules.length === 0) {
@@ -973,7 +1427,7 @@ var BucketLifecycleService = class {
973
1427
  })
974
1428
  );
975
1429
  } catch (err) {
976
- throw mapLifecycleError(err, { bucket, op: `lifecycle.${op}` });
1430
+ throw mapLifecycleError(err, callDetails(`lifecycle.${op}`, { bucket: perCall }));
977
1431
  }
978
1432
  }
979
1433
  /** Validates the input and builds the rule, an expiration or a multipart-abort rule. */
@@ -1020,18 +1474,25 @@ var BucketLifecycleService = class {
1020
1474
  }
1021
1475
  }
1022
1476
  resolveBucket(perCall) {
1023
- const bucket = perCall ?? this.options.bucket;
1024
- if (!bucket) {
1025
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED);
1026
- }
1027
- return bucket;
1477
+ return resolveBucket(perCall, this.options.bucket);
1028
1478
  }
1029
1479
  };
1480
+ __decorateClass([
1481
+ Observed("lifecycle_get")
1482
+ ], BucketLifecycleService.prototype, "get", 1);
1483
+ __decorateClass([
1484
+ Observed("lifecycle_upsert")
1485
+ ], BucketLifecycleService.prototype, "upsert", 1);
1486
+ __decorateClass([
1487
+ Observed("lifecycle_remove")
1488
+ ], BucketLifecycleService.prototype, "remove", 1);
1030
1489
  BucketLifecycleService = __decorateClass([
1031
1490
  Injectable(),
1032
1491
  __decorateParam(0, Inject(BYMAX_STORAGE_OPTIONS)),
1033
1492
  __decorateParam(1, Inject(S3ClientProvider)),
1034
- __decorateParam(2, Inject(KeyResolverService))
1493
+ __decorateParam(2, Inject(KeyResolverService)),
1494
+ __decorateParam(3, Optional()),
1495
+ __decorateParam(3, Inject(StorageObserver))
1035
1496
  ], BucketLifecycleService);
1036
1497
  function isBufferLike(body) {
1037
1498
  return body instanceof Uint8Array;
@@ -1144,7 +1605,7 @@ function toUploadBody(body) {
1144
1605
  return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
1145
1606
  }
1146
1607
  const stream = body;
1147
- const readable = typeof stream?.pipe === "function" && typeof stream.on === "function" && typeof stream.once === "function";
1608
+ const readable = typeof stream?.pipe === "function" && typeof stream.on === "function" && typeof stream.once === "function" && typeof stream.pause === "function" && typeof stream.resume === "function";
1148
1609
  if (!(body instanceof Uint8Array) && !readable) {
1149
1610
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1150
1611
  field: "body",
@@ -1185,18 +1646,17 @@ function assertMimeAllowed(whitelist, contentType) {
1185
1646
  return;
1186
1647
  }
1187
1648
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_MIME_NOT_ALLOWED, void 0, {
1188
- ...isHeaderValue(contentType) ? { contentType } : {},
1189
- whitelist
1649
+ ...isHeaderValue(contentType) ? { contentType } : {}
1190
1650
  });
1191
1651
  }
1192
1652
 
1193
1653
  // src/server/utils/numeric-input.ts
1194
- function assertIntegerInput(value, field2, min) {
1654
+ function assertIntegerInput(value, field, min) {
1195
1655
  if (value === void 0) return;
1196
1656
  if (!Number.isInteger(value) || value < min) {
1197
1657
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1198
- field: field2,
1199
- reason: `${field2} must be an integer of at least ${String(min)}`
1658
+ field,
1659
+ reason: `${field} must be an integer of at least ${String(min)}`
1200
1660
  });
1201
1661
  }
1202
1662
  }
@@ -1301,31 +1761,36 @@ var MAX_SCANNER_LABEL_LENGTH = 200;
1301
1761
  var MAX_SCANNER_DETAILS_LENGTH = 300;
1302
1762
  var MAX_STATUS_LOG_LENGTH = 40;
1303
1763
  function statusForLog(status) {
1304
- return typeof status === "string" ? logValue(status.slice(0, MAX_STATUS_LOG_LENGTH)) : `<${typeof status}>`;
1764
+ return typeof status === "string" ? escapeForLog(cutText(status, MAX_STATUS_LOG_LENGTH)) : `<${typeof status}>`;
1305
1765
  }
1306
1766
  function scannerLabel(value) {
1307
- return typeof value === "string" ? value.slice(0, MAX_SCANNER_LABEL_LENGTH) : void 0;
1767
+ return typeof value === "string" ? cutText(value, MAX_SCANNER_LABEL_LENGTH) : void 0;
1768
+ }
1769
+ function labelForLog(label) {
1770
+ return label === void 0 ? void 0 : escapeForLog(label);
1308
1771
  }
1309
1772
  function toJson(value) {
1310
1773
  return JSON.stringify(value);
1311
1774
  }
1312
1775
  function scannerDetailsForLog(details) {
1313
- if (details === void 0) return "";
1776
+ if (details === void 0) return {};
1314
1777
  let text;
1315
1778
  try {
1316
1779
  text = toJson(details) ?? UNSERIALISABLE;
1317
1780
  } catch {
1318
1781
  text = UNSERIALISABLE;
1319
1782
  }
1320
- return ` details=${logValue(text.slice(0, MAX_SCANNER_DETAILS_LENGTH))}`;
1783
+ return { details: escapeForLog(cutText(text, MAX_SCANNER_DETAILS_LENGTH)) };
1321
1784
  }
1322
1785
  var FileScannerService = class {
1323
- constructor(options, scanner) {
1786
+ constructor(options, scanner, observer) {
1324
1787
  this.options = options;
1325
1788
  this.scanner = scanner;
1789
+ this.observer = observer;
1326
1790
  }
1327
1791
  options;
1328
1792
  scanner;
1793
+ observer;
1329
1794
  logger = new Logger(FileScannerService.name);
1330
1795
  /**
1331
1796
  * Returns `true` when both a scanner implementation and scanner options are
@@ -1359,19 +1824,27 @@ var FileScannerService = class {
1359
1824
  * says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
1360
1825
  *
1361
1826
  * @param input - The scan input.
1827
+ * @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
1828
+ * bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
1362
1829
  * @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
1363
1830
  * @throws Error when called without a configured scanner.
1364
1831
  * @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
1365
1832
  * @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
1366
1833
  * @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
1367
1834
  */
1368
- async scan(input) {
1835
+ async scan(input, caller = {}) {
1369
1836
  if (!this.scanner) {
1370
1837
  throw new Error(
1371
1838
  "FileScannerService.scan() called without a configured scanner \u2014 guard with isEnabled() first."
1372
1839
  );
1373
1840
  }
1374
- const result = await this.scanLogged(this.scanner, input);
1841
+ const scanner = this.scanner;
1842
+ const run = () => this.evaluate(scanner, input, caller);
1843
+ return this.observer === void 0 ? run() : this.observer.scan(input.mode, run);
1844
+ }
1845
+ /** Runs the scanner and applies the library's policy to what it answered. */
1846
+ async evaluate(scanner, input, caller) {
1847
+ const result = await this.scanLogged(scanner, input, caller);
1375
1848
  const status = result?.status;
1376
1849
  const engine = scannerLabel(result?.engine);
1377
1850
  const threat = scannerLabel(result?.threat);
@@ -1380,18 +1853,41 @@ var FileScannerService = class {
1380
1853
  return result;
1381
1854
  }
1382
1855
  if (status === "infected") {
1383
- this.logger.warn(`Infected file detected: key=${logValue(input.key)} engine=${logValue(engine)} threat=${logValue(threat ?? "unknown")}${details}`);
1856
+ emit(this.logger, "warn", {
1857
+ event: STORAGE_LOG_EVENTS.scanInfected,
1858
+ message: "Infected file detected",
1859
+ engine: labelForLog(engine),
1860
+ threat: escapeForLog(threat ?? "unknown"),
1861
+ ...details
1862
+ });
1384
1863
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_SCAN_INFECTED, void 0, {
1385
1864
  engine,
1386
1865
  threat
1387
1866
  });
1388
1867
  }
1389
1868
  if (status === "unknown" && !this.options.scanner?.rejectOnUnknown) {
1390
- this.logger.warn(`Inconclusive scan result accepted: key=${logValue(input.key)} engine=${logValue(engine)}`);
1869
+ emit(this.logger, "warn", {
1870
+ event: STORAGE_LOG_EVENTS.scanInconclusiveAccepted,
1871
+ message: "Inconclusive scan result accepted",
1872
+ engine: labelForLog(engine)
1873
+ });
1391
1874
  return result;
1392
1875
  }
1876
+ return this.rejectInconclusive(status, engine, details);
1877
+ }
1878
+ /**
1879
+ * `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
1880
+ * exactly one of the three): the object is not known to be clean, so it is not stored.
1881
+ */
1882
+ rejectInconclusive(status, engine, details) {
1393
1883
  const unrecognised = status !== "unknown";
1394
- this.logger.warn(`Inconclusive scan result rejected: key=${logValue(input.key)} engine=${logValue(engine)}${unrecognised ? ` status=${statusForLog(status)}` : ""}${details}`);
1884
+ emit(this.logger, "warn", {
1885
+ event: STORAGE_LOG_EVENTS.scanInconclusiveRejected,
1886
+ message: "Inconclusive scan result rejected",
1887
+ engine: labelForLog(engine),
1888
+ ...unrecognised ? { status: statusForLog(status) } : {},
1889
+ ...details
1890
+ });
1395
1891
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_SCAN_INCONCLUSIVE, void 0, {
1396
1892
  engine,
1397
1893
  ...unrecognised ? { reason: "unrecognised scanner status" } : {}
@@ -1401,14 +1897,16 @@ var FileScannerService = class {
1401
1897
  * Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
1402
1898
  * line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
1403
1899
  */
1404
- async scanLogged(scanner, input) {
1900
+ async scanLogged(scanner, input, caller) {
1405
1901
  try {
1406
- return await this.scanWithinDeadline(scanner, input);
1902
+ return await this.scanWithinDeadline(scanner, input, caller);
1407
1903
  } catch (err) {
1408
1904
  if (!(err instanceof StorageException)) {
1409
- this.logger.warn(
1410
- `Scanner failed: key=${logValue(input.key)} error=${logValue(describeError(err).slice(0, MAX_SCANNER_DETAILS_LENGTH))}`
1411
- );
1905
+ emit(this.logger, "warn", {
1906
+ event: STORAGE_LOG_EVENTS.scanFailed,
1907
+ message: "Scanner failed",
1908
+ err: failureError(err)
1909
+ });
1412
1910
  }
1413
1911
  throw err;
1414
1912
  }
@@ -1418,16 +1916,20 @@ var FileScannerService = class {
1418
1916
  * the upload for good. The scanner is handed a signal that aborts then; one that ignores it keeps
1419
1917
  * running.
1420
1918
  */
1421
- async scanWithinDeadline(scanner, input) {
1919
+ async scanWithinDeadline(scanner, input, caller) {
1422
1920
  const timeoutMs = this.options.scanner?.timeoutMs ?? DEFAULT_SCANNER_TIMEOUT_MS;
1423
1921
  const controller = new AbortController();
1424
1922
  let timer;
1425
1923
  const deadline = new Promise((_resolve, reject) => {
1426
1924
  timer = setTimeout(() => {
1925
+ emit(this.logger, "warn", {
1926
+ event: STORAGE_LOG_EVENTS.scanTimeout,
1927
+ message: "Scan timed out",
1928
+ timeoutMs
1929
+ });
1427
1930
  reject(
1428
1931
  new StorageException(STORAGE_ERROR_CODES.STORAGE_TIMEOUT, void 0, {
1429
- key: input.key,
1430
- bucket: input.bucket,
1932
+ ...caller,
1431
1933
  phase: "scan",
1432
1934
  timeoutMs
1433
1935
  })
@@ -1445,7 +1947,9 @@ var FileScannerService = class {
1445
1947
  FileScannerService = __decorateClass([
1446
1948
  Injectable(),
1447
1949
  __decorateParam(0, Inject(BYMAX_STORAGE_OPTIONS)),
1448
- __decorateParam(1, Inject(BYMAX_STORAGE_FILE_SCANNER))
1950
+ __decorateParam(1, Inject(BYMAX_STORAGE_FILE_SCANNER)),
1951
+ __decorateParam(2, Optional()),
1952
+ __decorateParam(2, Inject(StorageObserver))
1449
1953
  ], FileScannerService);
1450
1954
  var SourceIdleError = class extends Error {
1451
1955
  constructor(idleMs) {
@@ -1457,7 +1961,11 @@ var SourceIdleError = class extends Error {
1457
1961
  };
1458
1962
  function isError(value) {
1459
1963
  const candidate = value;
1460
- return typeof candidate?.name === "string" && typeof candidate.message === "string";
1964
+ try {
1965
+ return typeof candidate?.name === "string" && typeof candidate.message === "string";
1966
+ } catch {
1967
+ return false;
1968
+ }
1461
1969
  }
1462
1970
  function withinIdleTime(next, idleMs) {
1463
1971
  return new Promise((resolve, reject) => {
@@ -1655,7 +2163,7 @@ function cleanupErrorCode(error) {
1655
2163
  }
1656
2164
  function describeCleanupFailure(error) {
1657
2165
  if (!(error instanceof StorageException)) {
1658
- return describeError(error);
2166
+ return projectProviderFailure(error).message;
1659
2167
  }
1660
2168
  return error.code;
1661
2169
  }
@@ -1670,7 +2178,6 @@ function withCleanupFailure(scanError, keys, cleanupError) {
1670
2178
  {
1671
2179
  ...body.error?.details ?? {},
1672
2180
  key: keys.key,
1673
- storedKey: keys.storedKey,
1674
2181
  cleanup: "failed",
1675
2182
  cleanupError: cleanupErrorCode(cleanupError)
1676
2183
  }
@@ -1691,6 +2198,7 @@ function requestAborted(signal, context) {
1691
2198
  });
1692
2199
  }
1693
2200
  function throwIfAborted(signal, context) {
2201
+ assertAbortSignal(signal);
1694
2202
  if (signal?.aborted) {
1695
2203
  throw requestAborted(signal, context);
1696
2204
  }
@@ -1802,11 +2310,13 @@ async function closeMultipartUpload(client, bucket, key, uploadId, onFailure) {
1802
2310
  function closeWhenCreated(client, bucket, key, created, onFailure) {
1803
2311
  void created.then((uploadId) => closeMultipartUpload(client, bucket, key, uploadId, onFailure));
1804
2312
  }
1805
- function abortFailureLogger(logger2, key) {
2313
+ function abortFailureLogger(logger2) {
1806
2314
  return (err) => {
1807
- logger2.warn(
1808
- `Multipart abort failed, the upload stays open on the provider: ${logValue(key)} ${describeProviderFailure(err)}`
1809
- );
2315
+ emit(logger2, "warn", {
2316
+ event: STORAGE_LOG_EVENTS.multipartAbortFailed,
2317
+ message: "Multipart abort failed, the upload stays open on the provider",
2318
+ err: failureError(err)
2319
+ });
1810
2320
  };
1811
2321
  }
1812
2322
  async function deleteObjectsChunk(client, bucket, chunk, stripPrefix) {
@@ -1922,6 +2432,23 @@ function buildACL(perCall, defaultValue) {
1922
2432
  return perCall ?? defaultValue ? "public-read" : void 0;
1923
2433
  }
1924
2434
 
2435
+ // src/server/utils/object-metadata.ts
2436
+ function toObjectMetadata(response, key, bucket) {
2437
+ return {
2438
+ key,
2439
+ bucket,
2440
+ size: response.ContentLength ?? 0,
2441
+ contentType: response.ContentType ?? "application/octet-stream",
2442
+ etag: response.ETag ?? "",
2443
+ lastModified: response.LastModified ?? /* @__PURE__ */ new Date(0),
2444
+ metadata: response.Metadata ?? {},
2445
+ ...response.CacheControl !== void 0 ? { cacheControl: response.CacheControl } : {},
2446
+ ...response.ContentDisposition !== void 0 ? { contentDisposition: response.ContentDisposition } : {},
2447
+ ...response.StorageClass !== void 0 ? { storageClass: response.StorageClass } : {},
2448
+ ...response.VersionId !== void 0 ? { versionId: response.VersionId } : {}
2449
+ };
2450
+ }
2451
+
1925
2452
  // src/server/utils/upload-strategy.ts
1926
2453
  function pickUploadStrategy(body, declaredSize, thresholdBytes) {
1927
2454
  const size = declaredSize ?? getBodySize(body);
@@ -1950,18 +2477,18 @@ function boundStreamSize(body, declaredSize, options) {
1950
2477
  }
1951
2478
  return withSizeLimit(body, limit, declaredSize === void 0 ? "max" : "declared");
1952
2479
  }
1953
- async function bufferStreamForScan(body, finalKey, maxSizeBytes) {
2480
+ async function bufferStreamForScan(body, context, maxSizeBytes) {
1954
2481
  if (maxSizeBytes === void 0) {
1955
2482
  destroyStream(body);
1956
2483
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1957
- key: finalKey,
2484
+ ...context,
1958
2485
  reason: "Pre-upload scanning of a stream needs validation.maxSizeBytes to bound the buffer; set it or use scanner mode post-upload"
1959
2486
  });
1960
2487
  }
1961
2488
  const buffered = await readStreamUpTo(body, maxSizeBytes);
1962
2489
  if (buffered === void 0) {
1963
2490
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_VALIDATION_FAILED, void 0, {
1964
- key: finalKey,
2491
+ ...context,
1965
2492
  maxSizeBytes,
1966
2493
  reason: "The stream is longer than validation.maxSizeBytes, so it cannot be scanned before upload"
1967
2494
  });
@@ -2019,6 +2546,13 @@ function baseCarriesBucket(base, bucket) {
2019
2546
  function normalizeScanBody(body) {
2020
2547
  return body;
2021
2548
  }
2549
+ function trackLoaded(uploader) {
2550
+ let loaded = 0;
2551
+ uploader.on("httpUploadProgress", (event) => {
2552
+ loaded = event.loaded ?? loaded;
2553
+ });
2554
+ return () => loaded;
2555
+ }
2022
2556
  function forwardProgress(uploader, onProgress) {
2023
2557
  if (!onProgress) return;
2024
2558
  uploader.on("httpUploadProgress", (event) => {
@@ -2088,11 +2622,10 @@ function assertMaxBytes(maxBytes) {
2088
2622
  });
2089
2623
  }
2090
2624
  }
2091
- async function readBody(stream, metadata, maxBytes) {
2625
+ async function readBody(stream, metadata, maxBytes, context) {
2092
2626
  if (maxBytes === void 0) {
2093
2627
  return readStream(stream);
2094
2628
  }
2095
- const context = { key: metadata.key, bucket: metadata.bucket };
2096
2629
  if (metadata.size > maxBytes) {
2097
2630
  destroyStream(stream);
2098
2631
  throw sizeLimitException(maxBytes, "max", { ...context, contentLength: metadata.size });
@@ -2103,15 +2636,50 @@ async function readBody(stream, metadata, maxBytes) {
2103
2636
  }
2104
2637
  return buffer;
2105
2638
  }
2106
- async function readDownloadBody(stream, metadata, maxBytes, signal) {
2639
+ async function readDownloadBody(stream, metadata, maxBytes, signal, caller) {
2640
+ const context = { ...caller, op: "downloadBuffer" };
2107
2641
  try {
2108
- return await readBody(stream, metadata, maxBytes);
2642
+ return await readBody(stream, metadata, maxBytes, context);
2109
2643
  } catch (err) {
2110
- throw mapBodyReadFailure(err, signal, {
2111
- key: metadata.key,
2112
- bucket: metadata.bucket,
2113
- op: "downloadBuffer"
2644
+ throw mapBodyReadFailure(err, signal, context);
2645
+ }
2646
+ }
2647
+
2648
+ // src/server/utils/uploaded-bytes.ts
2649
+ var SENT = /* @__PURE__ */ new WeakMap();
2650
+ function rememberUploadedBytes(result, bytes) {
2651
+ SENT.set(result, bytes);
2652
+ return result;
2653
+ }
2654
+ function uploadedBytesOf(result) {
2655
+ return result.fromIdempotencyCache ? void 0 : SENT.get(result) ?? result.size;
2656
+ }
2657
+ async function uploadSingleShot(context, options, finalKey, bucket, caller) {
2658
+ const total = options.size ?? getBodySize(options.body);
2659
+ const input = {
2660
+ ...putObjectHeaders(options, context.options, finalKey, bucket),
2661
+ Body: normalizeSingleShotBody(options.body),
2662
+ ContentLength: total
2663
+ };
2664
+ const watch = abortOnBodyFailure(input.Body, options.abortSignal);
2665
+ try {
2666
+ const response = await context.s3Provider.getClient().send(new PutObjectCommand(input), sendOptions(watch.signal));
2667
+ if (options.onProgress) {
2668
+ emitProgress(options.onProgress, total, total);
2669
+ }
2670
+ return buildUploadResult(context.keyResolver, context.options, {
2671
+ finalKey,
2672
+ bucket,
2673
+ etag: response.ETag,
2674
+ versionId: response.VersionId,
2675
+ size: total,
2676
+ contentType: options.contentType,
2677
+ multipart: false
2114
2678
  });
2679
+ } catch (err) {
2680
+ const context2 = { ...caller, op: "upload-single" };
2681
+ const mapped = mapSizeLimitError(watch.failure(), context2) ?? mapAwsError(err, context2);
2682
+ throw failureOrAbort(options.abortSignal, context2, mapped);
2115
2683
  }
2116
2684
  }
2117
2685
 
@@ -2119,13 +2687,14 @@ async function readDownloadBody(stream, metadata, maxBytes, signal) {
2119
2687
  var MAX_LIST_KEYS = 1e3;
2120
2688
  var DELETE_BATCH_LIMIT = 1e3;
2121
2689
  var StorageService = class {
2122
- constructor(options, s3Provider, keyResolver, idempotencyCache, validation, scanner) {
2690
+ constructor(options, s3Provider, keyResolver, idempotencyCache, validation, scanner, observer) {
2123
2691
  this.options = options;
2124
2692
  this.s3Provider = s3Provider;
2125
2693
  this.keyResolver = keyResolver;
2126
2694
  this.idempotencyCache = idempotencyCache;
2127
2695
  this.validation = validation;
2128
2696
  this.scanner = scanner;
2697
+ this.observer = observer;
2129
2698
  }
2130
2699
  options;
2131
2700
  s3Provider;
@@ -2133,22 +2702,8 @@ var StorageService = class {
2133
2702
  idempotencyCache;
2134
2703
  validation;
2135
2704
  scanner;
2705
+ observer;
2136
2706
  logger = new Logger(StorageService.name);
2137
- /**
2138
- * Uploads an object, choosing single-shot or multipart automatically. When an
2139
- * `idempotencyKey` is supplied and a matching result is cached within the TTL
2140
- * window, the cached result is returned without re-uploading.
2141
- *
2142
- * The library takes ownership of a `Readable` body, as `stream.pipeline` does: when the
2143
- * upload is rejected for any reason (configuration, validation, scan, provider failure)
2144
- * the stream is destroyed (without an error: the SDK forwards a stream's error to wrappers
2145
- * that nothing listens to), which releases the file handle or socket behind it; a cache hit
2146
- * destroys it unread. A stream consumed by a successful upload ends on its own.
2147
- *
2148
- * @param options - The upload request.
2149
- * @returns The upload result.
2150
- * @throws StorageException for missing configuration, body, or content type.
2151
- */
2152
2707
  async upload(options) {
2153
2708
  try {
2154
2709
  return await this.uploadOwningBody(options);
@@ -2171,7 +2726,7 @@ var StorageService = class {
2171
2726
  }
2172
2727
  const finalKey = this.keyResolver.normalize(options.key);
2173
2728
  const bucket = this.resolveBucket(options.bucket);
2174
- const context = { key: finalKey, bucket, op: "upload" };
2729
+ const context = callDetails("upload", { key: options.key, bucket: options.bucket });
2175
2730
  throwIfAborted(options.abortSignal, context);
2176
2731
  if (options.idempotencyKey) {
2177
2732
  const cacheKey = this.idempotencyCache.computeKey(options.idempotencyKey, finalKey);
@@ -2189,7 +2744,7 @@ var StorageService = class {
2189
2744
  validatedOptions.size,
2190
2745
  this.options.multipart.thresholdBytes
2191
2746
  );
2192
- const result = strategy === "multipart" ? await this.uploadMultipart(validatedOptions, finalKey, bucket) : await this.uploadSingleShot(validatedOptions, finalKey, bucket);
2747
+ const result = strategy === "multipart" ? await this.uploadMultipart(validatedOptions, finalKey, bucket, context) : await uploadSingleShot(this.uploadContext, validatedOptions, finalKey, bucket, context);
2193
2748
  const stored = { ...context, stored: true };
2194
2749
  await abortable(this.runPostUploadScan(finalKey, bucket, options), options.abortSignal, stored);
2195
2750
  this.rememberUpload(options, finalKey, result);
@@ -2205,7 +2760,7 @@ var StorageService = class {
2205
2760
  const input = validationInput(options, finalKey);
2206
2761
  const validated = await abortable(this.validation.validate(input), signal, context);
2207
2762
  const scanned = await abortable(
2208
- this.bufferForPreUploadScan(validated.body, finalKey),
2763
+ this.bufferForPreUploadScan(validated.body, context),
2209
2764
  signal,
2210
2765
  context
2211
2766
  );
@@ -2222,28 +2777,31 @@ var StorageService = class {
2222
2777
  * `validation.maxSizeBytes`, and a stream with no bound is refused rather than
2223
2778
  * buffered without limit. Other bodies and modes pass through unchanged.
2224
2779
  */
2225
- async bufferForPreUploadScan(body, finalKey) {
2780
+ async bufferForPreUploadScan(body, context) {
2226
2781
  if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload") {
2227
2782
  return body;
2228
2783
  }
2229
2784
  if (isBufferLike(body)) {
2230
2785
  return Buffer.from(body);
2231
2786
  }
2232
- return bufferStreamForScan(body, finalKey, this.options.validation?.maxSizeBytes);
2787
+ return bufferStreamForScan(body, context, this.options.validation?.maxSizeBytes);
2233
2788
  }
2234
2789
  /** Runs a pre-upload scan when configured; throws on infected. */
2235
2790
  async runPreUploadScan(body, finalKey, bucket, options) {
2236
2791
  if (!this.scanner.isEnabled() || this.scanner.getMode() !== "pre-upload") {
2237
2792
  return;
2238
2793
  }
2239
- await this.scanner.scan({
2240
- mode: "pre-upload",
2241
- body: normalizeScanBody(body),
2242
- key: finalKey,
2243
- bucket,
2244
- contentType: options.contentType,
2245
- ...options.size !== void 0 ? { size: options.size } : {}
2246
- });
2794
+ await this.scanner.scan(
2795
+ {
2796
+ mode: "pre-upload",
2797
+ body: normalizeScanBody(body),
2798
+ key: finalKey,
2799
+ bucket,
2800
+ contentType: options.contentType,
2801
+ ...options.size !== void 0 ? { size: options.size } : {}
2802
+ },
2803
+ callerFields({ key: options.key, bucket: options.bucket })
2804
+ );
2247
2805
  }
2248
2806
  /** Remembers the result of an upload under its idempotency key, when it has one. */
2249
2807
  rememberUpload(options, finalKey, result) {
@@ -2262,47 +2820,44 @@ var StorageService = class {
2262
2820
  return;
2263
2821
  }
2264
2822
  try {
2265
- await this.scanner.scan({
2266
- mode: "post-upload",
2267
- key: finalKey,
2268
- bucket,
2269
- contentType: options.contentType,
2270
- ...options.size !== void 0 ? { size: options.size } : {}
2271
- });
2823
+ await this.scanner.scan(
2824
+ {
2825
+ mode: "post-upload",
2826
+ key: finalKey,
2827
+ bucket,
2828
+ contentType: options.contentType,
2829
+ ...options.size !== void 0 ? { size: options.size } : {}
2830
+ },
2831
+ callerFields({ key: options.key, bucket: options.bucket })
2832
+ );
2272
2833
  } catch (scanErr) {
2273
2834
  const key = this.keyResolver.stripPrefix(finalKey);
2274
2835
  try {
2275
2836
  await this.delete(key, { bucket, abortSignal: AbortSignal.timeout(CLEANUP_DEADLINE_MS) });
2276
2837
  } catch (deleteErr) {
2277
- this.logger.error(
2278
- `STORAGE_SCAN_CLEANUP_FAILED: the rejected object is still stored: ${logValue(finalKey)}`,
2279
- logValue(describeCleanupFailure(deleteErr))
2280
- );
2281
- throw withCleanupFailure(scanErr, { key, storedKey: finalKey }, deleteErr);
2838
+ emit(this.logger, "error", {
2839
+ event: STORAGE_LOG_EVENTS.scanCleanupFailed,
2840
+ message: "The rejected object is still stored",
2841
+ storedKey: escapeForLog(finalKey),
2842
+ cleanupFailure: describeCleanupFailure(deleteErr)
2843
+ });
2844
+ throw withCleanupFailure(scanErr, { key }, deleteErr);
2282
2845
  }
2283
2846
  throw scanErr;
2284
2847
  }
2285
2848
  }
2286
- /**
2287
- * Returns metadata for an object without downloading its body.
2288
- *
2289
- * @param key - The raw object key (normalized internally).
2290
- * @param options - Optional per-call bucket override.
2291
- * @returns The object metadata.
2292
- * @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the key is absent.
2293
- */
2294
2849
  async head(key, options) {
2295
2850
  this.assertConfigured();
2296
2851
  const finalKey = this.keyResolver.normalize(key);
2297
2852
  const bucket = this.resolveBucket(options?.bucket);
2298
- const context = { key: finalKey, bucket, op: "head" };
2853
+ const context = callDetails("head", { key, bucket: options?.bucket });
2299
2854
  throwIfAborted(options?.abortSignal, context);
2300
2855
  try {
2301
2856
  const response = await this.s3Provider.getClient().send(
2302
2857
  new HeadObjectCommand({ Bucket: bucket, Key: finalKey }),
2303
2858
  sendOptions(options?.abortSignal)
2304
2859
  );
2305
- return this.toObjectMetadata(response, finalKey, bucket);
2860
+ return toObjectMetadata(response, this.keyResolver.stripPrefix(finalKey), bucket);
2306
2861
  } catch (err) {
2307
2862
  throw failureOrAbort(options?.abortSignal, context, mapAwsError(err, context));
2308
2863
  }
@@ -2326,9 +2881,11 @@ var StorageService = class {
2326
2881
  if (err instanceof StorageException && err.code === STORAGE_ERROR_CODES.STORAGE_REQUEST_ABORTED) {
2327
2882
  throw err;
2328
2883
  }
2329
- this.logger.warn(
2330
- `exists() \u2014 treating a non-404 error as "false": ${logValue(describeError(err))}`
2331
- );
2884
+ emit(this.logger, "warn", {
2885
+ event: STORAGE_LOG_EVENTS.existsFailed,
2886
+ message: 'exists() \u2014 treating a non-404 error as "false"',
2887
+ err: failureError(err)
2888
+ });
2332
2889
  return false;
2333
2890
  }
2334
2891
  }
@@ -2345,15 +2902,6 @@ var StorageService = class {
2345
2902
  const bucket = this.resolveBucket(options?.bucket);
2346
2903
  return buildPublicUrl(this.options, finalKey, bucket);
2347
2904
  }
2348
- /**
2349
- * Streams an object. The returned `stream` is a Node `Readable` consumable via
2350
- * `for await` or `.pipe()`. `range` / `ifNoneMatch` / `ifMatch` are forwarded as
2351
- * conditional/partial GET headers.
2352
- *
2353
- * @param options - The download request.
2354
- * @returns The object stream and its metadata.
2355
- * @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the body is absent.
2356
- */
2357
2905
  async download(options) {
2358
2906
  this.assertConfigured();
2359
2907
  assertHeaderValues({
@@ -2363,7 +2911,7 @@ var StorageService = class {
2363
2911
  });
2364
2912
  const finalKey = this.keyResolver.normalize(options.key);
2365
2913
  const bucket = this.resolveBucket(options.bucket);
2366
- const context = { key: finalKey, bucket, op: "download" };
2914
+ const context = callDetails("download", { key: options.key, bucket: options.bucket });
2367
2915
  throwIfAborted(options.abortSignal, context);
2368
2916
  try {
2369
2917
  const response = await this.s3Provider.getClient().send(
@@ -2377,10 +2925,7 @@ var StorageService = class {
2377
2925
  sendOptions(options.abortSignal)
2378
2926
  );
2379
2927
  if (!response.Body) {
2380
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND, void 0, {
2381
- key: finalKey,
2382
- bucket
2383
- });
2928
+ throw new StorageException(STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND, void 0, context);
2384
2929
  }
2385
2930
  const stream = guardDownloadBody(
2386
2931
  response.Body,
@@ -2388,7 +2933,10 @@ var StorageService = class {
2388
2933
  context,
2389
2934
  options.abortSignal
2390
2935
  );
2391
- return { stream, metadata: this.toObjectMetadata(response, finalKey, bucket) };
2936
+ return {
2937
+ stream,
2938
+ metadata: toObjectMetadata(response, this.keyResolver.stripPrefix(finalKey), bucket)
2939
+ };
2392
2940
  } catch (err) {
2393
2941
  if (err instanceof StorageException) {
2394
2942
  throw err;
@@ -2408,21 +2956,20 @@ var StorageService = class {
2408
2956
  async downloadBuffer(options) {
2409
2957
  assertMaxBytes(options.maxBytes);
2410
2958
  const { stream, metadata } = await this.download(options);
2411
- const buffer = await readDownloadBody(stream, metadata, options.maxBytes, options.abortSignal);
2959
+ const buffer = await readDownloadBody(
2960
+ stream,
2961
+ metadata,
2962
+ options.maxBytes,
2963
+ options.abortSignal,
2964
+ callerFields({ key: options.key, bucket: options.bucket })
2965
+ );
2412
2966
  return { buffer, metadata };
2413
2967
  }
2414
- /**
2415
- * Deletes an object. Idempotent: a missing object is a no-op (logged as a
2416
- * warning), not an error. Any other failure is propagated.
2417
- *
2418
- * @param key - The raw object key.
2419
- * @param options - Optional per-call bucket override.
2420
- */
2421
2968
  async delete(key, options) {
2422
2969
  this.assertConfigured();
2423
2970
  const finalKey = this.keyResolver.normalize(key);
2424
2971
  const bucket = this.resolveBucket(options?.bucket);
2425
- const context = { key: finalKey, bucket, op: "delete" };
2972
+ const context = callDetails("delete", { key, bucket: options?.bucket });
2426
2973
  throwIfAborted(options?.abortSignal, context);
2427
2974
  try {
2428
2975
  await this.s3Provider.getClient().send(
@@ -2434,25 +2981,17 @@ var StorageService = class {
2434
2981
  if (mapped.code !== STORAGE_ERROR_CODES.STORAGE_OBJECT_NOT_FOUND) {
2435
2982
  throw mapped;
2436
2983
  }
2437
- this.logger.warn(`delete() \u2014 key not found (idempotent no-op): ${logValue(finalKey)}`);
2984
+ emit(this.logger, "warn", {
2985
+ event: STORAGE_LOG_EVENTS.deleteNotFound,
2986
+ message: "delete() \u2014 key not found (idempotent no-op)"
2987
+ });
2438
2988
  }
2439
2989
  this.idempotencyCache.invalidate(bucket, this.keyResolver.stripPrefix(finalKey));
2440
2990
  }
2441
- /**
2442
- * Probes the bucket with one `HeadBucket`, for a readiness check: it resolves when the bucket
2443
- * is reachable with these credentials and otherwise rejects with a typed code. Nothing in the
2444
- * module calls it on its own, so booting costs no request. Needs `s3:ListBucket`.
2445
- *
2446
- * @param options - Optional per-call bucket override.
2447
- * @throws StorageException `STORAGE_BUCKET_NOT_FOUND` (404), `STORAGE_BUCKET_ACCESS_DENIED` (403,
2448
- * which a provider also answers for a bucket the caller cannot see), `STORAGE_BUCKET_REGION_MISMATCH`
2449
- * (301), `STORAGE_TIMEOUT`, or `STORAGE_PROVIDER_ERROR`; `STORAGE_NOT_CONFIGURED` and
2450
- * `STORAGE_BUCKET_UNDEFINED` before any request.
2451
- */
2452
2991
  async checkBucket(options) {
2453
2992
  this.assertConfigured();
2454
2993
  const bucket = this.resolveBucket(options?.bucket);
2455
- const context = { bucket, op: "checkBucket" };
2994
+ const context = callDetails("checkBucket", { bucket: options?.bucket });
2456
2995
  throwIfAborted(options?.abortSignal, context);
2457
2996
  try {
2458
2997
  await this.s3Provider.getClient().send(new HeadBucketCommand({ Bucket: bucket }), sendOptions(options?.abortSignal));
@@ -2460,6 +2999,10 @@ var StorageService = class {
2460
2999
  throw failureOrAbort(options?.abortSignal, context, mapBucketCheckError(err, context));
2461
3000
  }
2462
3001
  }
3002
+ /** What the single-shot upload needs of this service. */
3003
+ get uploadContext() {
3004
+ return { s3Provider: this.s3Provider, keyResolver: this.keyResolver, options: this.options };
3005
+ }
2463
3006
  /** Throws when the S3 client was never built (missing credentials). */
2464
3007
  assertConfigured() {
2465
3008
  if (!this.s3Provider.isConfigured()) {
@@ -2468,56 +3011,7 @@ var StorageService = class {
2468
3011
  }
2469
3012
  /** Resolves the target bucket from a per-call override or the module default. */
2470
3013
  resolveBucket(perCall) {
2471
- const bucket = perCall ?? this.options.bucket;
2472
- if (!bucket) {
2473
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED);
2474
- }
2475
- return bucket;
2476
- }
2477
- /** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
2478
- toObjectMetadata(response, finalKey, bucket) {
2479
- return {
2480
- key: this.keyResolver.stripPrefix(finalKey),
2481
- bucket,
2482
- size: response.ContentLength ?? 0,
2483
- contentType: response.ContentType ?? "application/octet-stream",
2484
- etag: response.ETag ?? "",
2485
- lastModified: response.LastModified ?? /* @__PURE__ */ new Date(0),
2486
- metadata: response.Metadata ?? {},
2487
- ...response.CacheControl !== void 0 ? { cacheControl: response.CacheControl } : {},
2488
- ...response.ContentDisposition !== void 0 ? { contentDisposition: response.ContentDisposition } : {},
2489
- ...response.StorageClass !== void 0 ? { storageClass: response.StorageClass } : {},
2490
- ...response.VersionId !== void 0 ? { versionId: response.VersionId } : {}
2491
- };
2492
- }
2493
- /** Single `PutObject` upload for bodies below the multipart threshold. */
2494
- async uploadSingleShot(options, finalKey, bucket) {
2495
- const total = options.size ?? getBodySize(options.body);
2496
- const input = {
2497
- ...putObjectHeaders(options, this.options, finalKey, bucket),
2498
- Body: normalizeSingleShotBody(options.body),
2499
- ContentLength: total
2500
- };
2501
- const watch = abortOnBodyFailure(input.Body, options.abortSignal);
2502
- try {
2503
- const response = await this.s3Provider.getClient().send(new PutObjectCommand(input), sendOptions(watch.signal));
2504
- if (options.onProgress) {
2505
- emitProgress(options.onProgress, total, total);
2506
- }
2507
- return buildUploadResult(this.keyResolver, this.options, {
2508
- finalKey,
2509
- bucket,
2510
- etag: response.ETag,
2511
- versionId: response.VersionId,
2512
- size: total,
2513
- contentType: options.contentType,
2514
- multipart: false
2515
- });
2516
- } catch (err) {
2517
- const context = { key: finalKey, bucket, op: "upload-single" };
2518
- const mapped = mapSizeLimitError(watch.failure(), context) ?? mapAwsError(err, context);
2519
- throw failureOrAbort(options.abortSignal, context, mapped);
2520
- }
3014
+ return resolveBucket(perCall, this.options.bucket);
2521
3015
  }
2522
3016
  /**
2523
3017
  * Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
@@ -2525,7 +3019,7 @@ var StorageService = class {
2525
3019
  * abort replaced the failure that caused it, and a failed `CompleteMultipartUpload` was never
2526
3020
  * aborted. This method aborts the upload itself and reports the outcome in the error details.
2527
3021
  */
2528
- async uploadMultipart(options, finalKey, bucket) {
3022
+ async uploadMultipart(options, finalKey, bucket, caller) {
2529
3023
  const params = {
2530
3024
  ...putObjectHeaders(options, this.options, finalKey, bucket),
2531
3025
  Body: guardIdleBody(options.body, this.options.uploadIdleTimeoutMs)
@@ -2539,6 +3033,7 @@ var StorageService = class {
2539
3033
  partSize: this.options.multipart.partSizeBytes,
2540
3034
  leavePartsOnError: true
2541
3035
  });
3036
+ const sent = trackLoaded(uploader);
2542
3037
  forwardProgress(uploader, options.onProgress);
2543
3038
  const abortUpload = () => {
2544
3039
  void uploader.abort();
@@ -2546,17 +3041,20 @@ var StorageService = class {
2546
3041
  signal?.addEventListener("abort", abortUpload, { once: true });
2547
3042
  try {
2548
3043
  const response = await uploader.done();
2549
- return buildUploadResult(this.keyResolver, this.options, {
2550
- finalKey,
2551
- bucket,
2552
- etag: response.ETag,
2553
- versionId: response.VersionId,
2554
- size: options.size,
2555
- contentType: options.contentType,
2556
- multipart: true
2557
- });
3044
+ return rememberUploadedBytes(
3045
+ buildUploadResult(this.keyResolver, this.options, {
3046
+ finalKey,
3047
+ bucket,
3048
+ etag: response.ETag,
3049
+ versionId: response.VersionId,
3050
+ size: options.size,
3051
+ contentType: options.contentType,
3052
+ multipart: true
3053
+ }),
3054
+ sent()
3055
+ );
2558
3056
  } catch (err) {
2559
- return await this.failMultipart(err, finalKey, bucket, {
3057
+ return await this.failMultipart(err, finalKey, bucket, caller, {
2560
3058
  uploadId: uploader.uploadId,
2561
3059
  signal,
2562
3060
  createdUploadId: bound?.createdUploadId
@@ -2571,7 +3069,7 @@ var StorageService = class {
2571
3069
  * real failure into one. An upload id the provider answered late is waited for, within the cleanup
2572
3070
  * deadline, so that an abort during `CreateMultipartUpload` still aborts the upload it created.
2573
3071
  */
2574
- async failMultipart(err, finalKey, bucket, upload) {
3072
+ async failMultipart(err, finalKey, bucket, caller, upload) {
2575
3073
  const abortedBy = upload.signal?.aborted === true ? upload.signal : void 0;
2576
3074
  const client = this.s3Provider.getClient();
2577
3075
  const lookup = abortedBy ? upload.createdUploadId?.() : void 0;
@@ -2579,7 +3077,7 @@ var StorageService = class {
2579
3077
  if (uploadId === void 0 && lookup) {
2580
3078
  uploadId = await within(lookup, CLEANUP_DEADLINE_MS);
2581
3079
  if (uploadId === void 0) {
2582
- closeWhenCreated(client, bucket, finalKey, lookup, abortFailureLogger(this.logger, finalKey));
3080
+ closeWhenCreated(client, bucket, finalKey, lookup, abortFailureLogger(this.logger));
2583
3081
  }
2584
3082
  }
2585
3083
  const abort = await closeMultipartUpload(
@@ -2587,27 +3085,18 @@ var StorageService = class {
2587
3085
  bucket,
2588
3086
  finalKey,
2589
3087
  uploadId,
2590
- abortFailureLogger(this.logger, finalKey)
3088
+ abortFailureLogger(this.logger)
2591
3089
  );
2592
- const context = { key: finalKey, bucket, op: "upload-multipart", ...abort };
3090
+ const context = { ...caller, op: "upload-multipart", ...abort };
2593
3091
  throw abortedBy ? requestAborted(abortedBy, context) : mapMultipartError(err, context);
2594
3092
  }
2595
- /**
2596
- * Lists objects in the bucket as a single page. Applies the global key prefix
2597
- * to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
2598
- * the continuation token, and strips the global prefix from every returned key.
2599
- *
2600
- * @param options - The listing request.
2601
- * @returns One page of objects plus `commonPrefixes`, truncation, and the next token.
2602
- * @throws StorageException mapped from any AWS failure.
2603
- */
2604
3093
  async list(options) {
2605
3094
  this.assertConfigured();
2606
3095
  const bucket = this.resolveBucket(options.bucket);
2607
3096
  assertIntegerInput(options.maxKeys, "maxKeys", 1);
2608
3097
  const maxKeys = Math.min(options.maxKeys ?? MAX_LIST_KEYS, MAX_LIST_KEYS);
2609
3098
  const prefix = options.prefix ? this.keyResolver.normalize(options.prefix) : this.keyResolver.getPrefix();
2610
- const context = { bucket, prefix, op: "list" };
3099
+ const context = callDetails("list", { bucket: options.bucket, prefix: options.prefix });
2611
3100
  throwIfAborted(options.abortSignal, context);
2612
3101
  try {
2613
3102
  const response = await this.s3Provider.getClient().send(
@@ -2625,14 +3114,6 @@ var StorageService = class {
2625
3114
  throw failureOrAbort(options.abortSignal, context, mapAwsError(err, context));
2626
3115
  }
2627
3116
  }
2628
- /**
2629
- * Server-side copy of an object (no bytes flow through the app). Supports both
2630
- * same-bucket and cross-bucket copies and preserves the source metadata.
2631
- *
2632
- * @param options - Source/destination keys and buckets plus copy overrides.
2633
- * @returns The new object's ETag.
2634
- * @throws StorageException mapped from any AWS failure.
2635
- */
2636
3117
  async copy(options) {
2637
3118
  this.assertConfigured();
2638
3119
  assertHeaderValues({ cacheControl: options.cacheControl });
@@ -2656,19 +3137,12 @@ var StorageService = class {
2656
3137
  );
2657
3138
  return { etag: response.CopyObjectResult?.ETag ?? "" };
2658
3139
  } catch (err) {
2659
- throw mapAwsError(err, { sourceKey, destKey, op: "copy" });
3140
+ throw mapAwsError(
3141
+ err,
3142
+ callDetails("copy", { sourceKey: options.sourceKey, destKey: options.destinationKey })
3143
+ );
2660
3144
  }
2661
3145
  }
2662
- /**
2663
- * Deletes many objects, chunking the input at the S3 hard limit of 1000 keys
2664
- * per request. Reports both successes and per-key failures; a whole-chunk send
2665
- * failure marks every key in that chunk as failed. Returned keys are stripped of
2666
- * the global prefix.
2667
- *
2668
- * @param keys - The raw object keys to delete.
2669
- * @param options - Optional per-call bucket override.
2670
- * @returns The deleted keys and the per-key failures.
2671
- */
2672
3146
  async deleteMany(keys, options) {
2673
3147
  this.assertConfigured();
2674
3148
  if (keys.length === 0) {
@@ -2695,6 +3169,34 @@ var StorageService = class {
2695
3169
  return { deleted, failed };
2696
3170
  }
2697
3171
  };
3172
+ __decorateClass([
3173
+ Observed("upload", {
3174
+ span: "storage.upload",
3175
+ describe: (result) => ({ "bymax.storage.multipart": String(result.multipart) }),
3176
+ bytes: uploadedBytesOf
3177
+ })
3178
+ ], StorageService.prototype, "upload", 1);
3179
+ __decorateClass([
3180
+ Observed("head")
3181
+ ], StorageService.prototype, "head", 1);
3182
+ __decorateClass([
3183
+ Observed("download")
3184
+ ], StorageService.prototype, "download", 1);
3185
+ __decorateClass([
3186
+ Observed("delete")
3187
+ ], StorageService.prototype, "delete", 1);
3188
+ __decorateClass([
3189
+ Observed("check_bucket")
3190
+ ], StorageService.prototype, "checkBucket", 1);
3191
+ __decorateClass([
3192
+ Observed("list")
3193
+ ], StorageService.prototype, "list", 1);
3194
+ __decorateClass([
3195
+ Observed("copy")
3196
+ ], StorageService.prototype, "copy", 1);
3197
+ __decorateClass([
3198
+ Observed("delete_many")
3199
+ ], StorageService.prototype, "deleteMany", 1);
2698
3200
  StorageService = __decorateClass([
2699
3201
  Injectable(),
2700
3202
  __decorateParam(0, Inject(BYMAX_STORAGE_OPTIONS)),
@@ -2702,7 +3204,9 @@ StorageService = __decorateClass([
2702
3204
  __decorateParam(2, Inject(KeyResolverService)),
2703
3205
  __decorateParam(3, Inject(BYMAX_STORAGE_IDEMPOTENCY_CACHE)),
2704
3206
  __decorateParam(4, Inject(ValidationService)),
2705
- __decorateParam(5, Inject(FileScannerService))
3207
+ __decorateParam(5, Inject(FileScannerService)),
3208
+ __decorateParam(6, Optional()),
3209
+ __decorateParam(6, Inject(StorageObserver))
2706
3210
  ], StorageService);
2707
3211
 
2708
3212
  // src/server/utils/ttl-clamp.ts
@@ -2722,25 +3226,16 @@ function clampTtl(ttlSeconds, defaultTtl, maxTtl) {
2722
3226
  // src/server/services/signed-url.service.ts
2723
3227
  var MAX_MULTIPART_PARTS = 1e4;
2724
3228
  var SignedUrlService = class {
2725
- constructor(options, s3Provider, keyResolver) {
3229
+ constructor(options, s3Provider, keyResolver, observer) {
2726
3230
  this.options = options;
2727
3231
  this.s3Provider = s3Provider;
2728
3232
  this.keyResolver = keyResolver;
3233
+ this.observer = observer;
2729
3234
  }
2730
3235
  options;
2731
3236
  s3Provider;
2732
3237
  keyResolver;
2733
- /**
2734
- * Issues a presigned GET URL for downloading an object.
2735
- *
2736
- * SECURITY: The returned URL is a temporary credential. NEVER log it, store it
2737
- * in a database, or cache it across users. Issue a fresh URL per request.
2738
- *
2739
- * @param options - The download URL options.
2740
- * @returns The presigned URL and its expiry metadata.
2741
- * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
2742
- * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
2743
- */
3238
+ observer;
2744
3239
  async getDownloadUrl(options) {
2745
3240
  this.assertConfigured();
2746
3241
  assertHeaderValues({
@@ -2765,36 +3260,9 @@ var SignedUrlService = class {
2765
3260
  return { url, expiresAt: new Date(Date.now() + ttl * 1e3), method: "GET", requiredHeaders: {} };
2766
3261
  } catch (err) {
2767
3262
  if (err instanceof StorageException) throw err;
2768
- throw mapAwsError(err, { key: finalKey, bucket, op: "getDownloadUrl" });
3263
+ throw mapAwsError(err, callDetails("getDownloadUrl", { key: options.key, bucket: options.bucket }));
2769
3264
  }
2770
3265
  }
2771
- /**
2772
- * Issues a presigned PUT URL for uploading an object. The client MUST send
2773
- * every header listed in `requiredHeaders` verbatim — each one is part of the
2774
- * URL signature, so an omitted header yields `SignatureDoesNotMatch`. The map
2775
- * always carries `Content-Type` and additionally lists `x-amz-acl` when an ACL
2776
- * is signed and an `x-amz-meta-<key>` entry per metadata pair. The `Content-Type`
2777
- * is signed (`X-Amz-SignedHeaders` lists `content-type`), so a PUT that sends any
2778
- * other type is refused by the provider and nothing is stored.
2779
- *
2780
- * SECURITY: The returned URL is a temporary credential — NEVER log it. A signed
2781
- * PUT bypasses the server-side MIME/size validation pipeline. Size limits are
2782
- * NOT enforced at presign time: a SigV4 PUT signature can only pin an exact
2783
- * `Content-Length`, never a maximum, so binding one would reject valid smaller
2784
- * uploads. Enforce size after the fact via a post-upload HEAD/size check plus
2785
- * the post-upload scanner path for defence-in-depth.
2786
- *
2787
- * ACL caveat: `publicRead` emits `ACL: public-read`, which returns HTTP 400
2788
- * `AccessControlListNotSupported` on modern AWS S3 buckets (Object Ownership
2789
- * = "Bucket owner enforced") and is a no-op on Cloudflare R2. Prefer a bucket
2790
- * policy, CDN, or signed GET URL for public delivery.
2791
- *
2792
- * @param options - The upload URL options.
2793
- * @returns The presigned URL, its expiry metadata, and required headers.
2794
- * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
2795
- * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
2796
- * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` when `validation.mimeWhitelist` is set and excludes `contentType`.
2797
- */
2798
3266
  async getUploadUrl(options) {
2799
3267
  this.assertConfigured();
2800
3268
  assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
@@ -2828,7 +3296,7 @@ var SignedUrlService = class {
2828
3296
  };
2829
3297
  } catch (err) {
2830
3298
  if (err instanceof StorageException) throw err;
2831
- throw mapAwsError(err, { key: finalKey, bucket, op: "getUploadUrl" });
3299
+ throw mapAwsError(err, callDetails("getUploadUrl", { key: options.key, bucket: options.bucket }));
2832
3300
  }
2833
3301
  }
2834
3302
  /**
@@ -2849,21 +3317,6 @@ var SignedUrlService = class {
2849
3317
  }
2850
3318
  return headers;
2851
3319
  }
2852
- /**
2853
- * Presigns a multipart upload: creates the upload session on S3, then returns
2854
- * N presigned `UploadPart` URLs (1-indexed) and a presigned `CompleteMultipart`
2855
- * URL. The client uploads parts directly to S3 and then calls the complete URL.
2856
- *
2857
- * SECURITY: All returned URLs are temporary credentials — NEVER log them.
2858
- *
2859
- * @param options - The multipart URL options.
2860
- * @returns `uploadId`, `partUrls`, and `completeUrl`.
2861
- * @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
2862
- * @throws StorageException `STORAGE_INVALID_PART_COUNT` when `parts` is not an integer from 1 to 10 000.
2863
- * @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
2864
- * @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
2865
- * @throws StorageException `STORAGE_MIME_NOT_ALLOWED` when `validation.mimeWhitelist` is set and excludes `contentType`.
2866
- */
2867
3320
  async getMultipartUploadUrls(options) {
2868
3321
  this.assertConfigured();
2869
3322
  assertMimeAllowed(this.options.validation?.mimeWhitelist, options.contentType);
@@ -2871,7 +3324,8 @@ var SignedUrlService = class {
2871
3324
  if (!Number.isInteger(options.parts) || options.parts < 1 || options.parts > MAX_MULTIPART_PARTS) {
2872
3325
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_INVALID_PART_COUNT, void 0, {
2873
3326
  reason: `parts must be an integer from 1 to ${String(MAX_MULTIPART_PARTS)}`,
2874
- provided: options.parts
3327
+ // Only a number is repeated: any other value is the caller's to keep.
3328
+ ...Number.isFinite(options.parts) ? { provided: options.parts } : {}
2875
3329
  });
2876
3330
  }
2877
3331
  const finalKey = this.keyResolver.normalize(options.key);
@@ -2892,14 +3346,16 @@ var SignedUrlService = class {
2892
3346
  if (!uploadId) {
2893
3347
  throw new StorageException(STORAGE_ERROR_CODES.STORAGE_PROVIDER_ERROR, void 0, {
2894
3348
  reason: "CreateMultipartUpload returned no UploadId",
2895
- key: finalKey,
2896
- bucket
3349
+ ...callerFields({ key: options.key, bucket: options.bucket })
2897
3350
  });
2898
3351
  }
2899
3352
  return await this.presignMultipartParts({ finalKey, bucket, uploadId, parts: options.parts, ttl });
2900
3353
  } catch (err) {
2901
3354
  if (err instanceof StorageException) throw err;
2902
- throw mapAwsError(err, { key: finalKey, bucket, op: "getMultipartUploadUrls" });
3355
+ throw mapAwsError(
3356
+ err,
3357
+ callDetails("getMultipartUploadUrls", { key: options.key, bucket: options.bucket })
3358
+ );
2903
3359
  }
2904
3360
  }
2905
3361
  /** Presigns all part URLs and the complete URL in parallel. */
@@ -2927,18 +3383,25 @@ var SignedUrlService = class {
2927
3383
  }
2928
3384
  /** Resolves the target bucket from a per-call override or the module default. */
2929
3385
  resolveBucket(perCall) {
2930
- const bucket = perCall ?? this.options.bucket;
2931
- if (!bucket) {
2932
- throw new StorageException(STORAGE_ERROR_CODES.STORAGE_BUCKET_UNDEFINED);
2933
- }
2934
- return bucket;
3386
+ return resolveBucket(perCall, this.options.bucket);
2935
3387
  }
2936
3388
  };
3389
+ __decorateClass([
3390
+ Observed("get_download_url", { span: "storage.download_url" })
3391
+ ], SignedUrlService.prototype, "getDownloadUrl", 1);
3392
+ __decorateClass([
3393
+ Observed("get_upload_url")
3394
+ ], SignedUrlService.prototype, "getUploadUrl", 1);
3395
+ __decorateClass([
3396
+ Observed("get_multipart_upload_urls")
3397
+ ], SignedUrlService.prototype, "getMultipartUploadUrls", 1);
2937
3398
  SignedUrlService = __decorateClass([
2938
3399
  Injectable(),
2939
3400
  __decorateParam(0, Inject(BYMAX_STORAGE_OPTIONS)),
2940
3401
  __decorateParam(1, Inject(S3ClientProvider)),
2941
- __decorateParam(2, Inject(KeyResolverService))
3402
+ __decorateParam(2, Inject(KeyResolverService)),
3403
+ __decorateParam(3, Optional()),
3404
+ __decorateParam(3, Inject(StorageObserver))
2942
3405
  ], SignedUrlService);
2943
3406
  var IdempotencyCache = class {
2944
3407
  /**
@@ -3042,14 +3505,18 @@ var IdempotencyCache = class {
3042
3505
  };
3043
3506
 
3044
3507
  // src/server/bymax-storage.module.ts
3045
- function resolveAsyncOptions(options) {
3508
+ function resolveAsyncOptions(raw) {
3509
+ const options = snapshotOptions(raw);
3046
3510
  validateOptions(options);
3047
3511
  const resolved = applyDefaults(options);
3048
3512
  const configured = options.signedUrls?.maxTtlSeconds;
3049
3513
  if (configured !== void 0 && configured > resolved.signedUrls.maxTtlSeconds) {
3050
- new Logger(BymaxStorageModule.name).warn(
3051
- `signedUrls.maxTtlSeconds=${String(configured)} exceeds the SigV4 presigned-URL limit; using ${String(resolved.signedUrls.maxTtlSeconds)} seconds (7 days) instead.`
3052
- );
3514
+ emit(new Logger(BymaxStorageModule.name), "warn", {
3515
+ event: STORAGE_LOG_EVENTS.ttlClamped,
3516
+ message: "signedUrls.maxTtlSeconds exceeds the SigV4 presigned-URL limit; the limit is used instead",
3517
+ configuredSeconds: configured,
3518
+ appliedSeconds: resolved.signedUrls.maxTtlSeconds
3519
+ });
3053
3520
  }
3054
3521
  return resolved;
3055
3522
  }
@@ -3147,6 +3614,10 @@ var BymaxStorageModule = class {
3147
3614
  DEFAULT_IDEMPOTENCY_CACHE_TTL_MS
3148
3615
  )
3149
3616
  },
3617
+ // The counts and the span seam the services report to; the optional `observability` subpath reads the tally.
3618
+ StorageMetricsTally,
3619
+ StorageTracing,
3620
+ StorageObserver,
3150
3621
  StorageService,
3151
3622
  SignedUrlService,
3152
3623
  BucketLifecycleService,
@@ -3173,6 +3644,7 @@ var BymaxStorageModule = class {
3173
3644
  StorageService,
3174
3645
  SignedUrlService,
3175
3646
  BucketLifecycleService,
3647
+ StorageMetricsTally,
3176
3648
  BYMAX_STORAGE_OPTIONS,
3177
3649
  BYMAX_STORAGE_S3_CLIENT,
3178
3650
  BYMAX_STORAGE_UPLOAD_VALIDATORS,
@@ -3335,4 +3807,4 @@ var providerRecipes = {
3335
3807
  }
3336
3808
  };
3337
3809
 
3338
- 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 };
3810
+ 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 };