@bymax-one/nest-storage 1.1.18 → 1.1.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +145 -1
- package/README.md +184 -16
- package/dist/observability/index.cjs +151 -0
- package/dist/observability/index.d.cts +72 -0
- package/dist/observability/index.d.ts +72 -0
- package/dist/observability/index.mjs +145 -0
- package/dist/server/index.cjs +831 -444
- package/dist/server/index.d.cts +151 -12
- package/dist/server/index.d.ts +151 -12
- package/dist/server/index.mjs +831 -447
- package/package.json +32 -5
package/dist/server/index.d.cts
CHANGED
|
@@ -669,6 +669,132 @@ declare class ValidationService {
|
|
|
669
669
|
private runCustomValidators;
|
|
670
670
|
}
|
|
671
671
|
|
|
672
|
+
/** The operations the library counts and times. */
|
|
673
|
+
declare const STORAGE_OPERATIONS: readonly ["upload", "download", "head", "delete", "delete_many", "list", "copy", "get_download_url", "get_upload_url", "get_multipart_upload_urls", "check_bucket", "lifecycle_get", "lifecycle_upsert", "lifecycle_remove"];
|
|
674
|
+
/** What an operation ended as. */
|
|
675
|
+
declare const STORAGE_OUTCOMES: readonly ["success", "not_found", "aborted", "error"];
|
|
676
|
+
/** What a scan ended as. */
|
|
677
|
+
declare const SCAN_VERDICTS: readonly ["clean", "infected", "unknown", "timeout", "error"];
|
|
678
|
+
/** One of {@link STORAGE_OPERATIONS}. */
|
|
679
|
+
type StorageOperation = (typeof STORAGE_OPERATIONS)[number];
|
|
680
|
+
/** One of {@link STORAGE_OUTCOMES}. */
|
|
681
|
+
type StorageOutcome = (typeof STORAGE_OUTCOMES)[number];
|
|
682
|
+
/** One of {@link SCAN_VERDICTS}. */
|
|
683
|
+
type ScanVerdict = (typeof SCAN_VERDICTS)[number];
|
|
684
|
+
|
|
685
|
+
/** Told how long an operation took, once it ended. Typed to return a value: a listener typed `void` can still return a promise. */
|
|
686
|
+
type DurationListener = (operation: StorageOperation, seconds: number) => unknown;
|
|
687
|
+
/**
|
|
688
|
+
* Counts what the storage operations do. Each count is keyed by a closed set (see `storage-operations`), so no
|
|
689
|
+
* label can grow with the traffic, and nothing a caller or a host supplied is ever a key. The optional
|
|
690
|
+
* `observability` subpath reads these numbers when it is scraped, and feeds a duration histogram through
|
|
691
|
+
* {@link StorageMetricsTally.onDuration}.
|
|
692
|
+
*/
|
|
693
|
+
declare class StorageMetricsTally {
|
|
694
|
+
#private;
|
|
695
|
+
/** An operation ended as `outcome` after `seconds`. */
|
|
696
|
+
operation(operation: StorageOperation, outcome: StorageOutcome, seconds: number): void;
|
|
697
|
+
/**
|
|
698
|
+
* `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. The
|
|
699
|
+
* count stops at the largest finite number: a sum of two finite sizes can overflow to `Infinity`, which no
|
|
700
|
+
* counter accepts, and a scrape that read it would fail whole.
|
|
701
|
+
*/
|
|
702
|
+
bytesUploaded(bytes: number | undefined): void;
|
|
703
|
+
/** A scan ended as `verdict`. */
|
|
704
|
+
scan(verdict: ScanVerdict): void;
|
|
705
|
+
/** Calls `listener` with the duration of every operation that ends from now on. */
|
|
706
|
+
onDuration(listener: DurationListener): void;
|
|
707
|
+
/** The counts so far, as copies. */
|
|
708
|
+
snapshot(): {
|
|
709
|
+
readonly operations: Readonly<Record<StorageOperation, Readonly<Record<StorageOutcome, number>>>>;
|
|
710
|
+
readonly bytesUploaded: number;
|
|
711
|
+
readonly scans: Readonly<Record<ScanVerdict, number>>;
|
|
712
|
+
};
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
/** The span names the library starts. */
|
|
716
|
+
type StorageSpanName = 'storage.upload' | 'storage.download_url' | 'storage.scan';
|
|
717
|
+
/**
|
|
718
|
+
* The attributes a span carries, named one by one: the outcome, whether an upload was multipart, and when a scan
|
|
719
|
+
* runs. A key, a bucket or a payload has no member, so a call site cannot add one.
|
|
720
|
+
*/
|
|
721
|
+
interface StorageSpanAttributes {
|
|
722
|
+
readonly 'bymax.storage.outcome'?: StorageOutcome;
|
|
723
|
+
readonly 'bymax.storage.multipart'?: 'true' | 'false';
|
|
724
|
+
readonly 'bymax.storage.scan_mode'?: 'pre-upload' | 'post-upload';
|
|
725
|
+
}
|
|
726
|
+
/** What a span states of a result, once the operation succeeded. */
|
|
727
|
+
type ResultAttributes<T> = (result: T) => StorageSpanAttributes;
|
|
728
|
+
/**
|
|
729
|
+
* Starts a span around an operation when `@opentelemetry/api` is installed, and runs it bare otherwise.
|
|
730
|
+
*
|
|
731
|
+
* The peer is optional, so it is loaded with a dynamic `import()` that a missing package turns into a no-op:
|
|
732
|
+
* the server bundle never names it statically, and an application that does not trace installs nothing. With
|
|
733
|
+
* the API present and no SDK registered the API itself is a no-op. A span carries a closed set of attributes
|
|
734
|
+
* and, on failure, the library error code and nothing of the message.
|
|
735
|
+
*/
|
|
736
|
+
declare class StorageTracing implements OnModuleInit {
|
|
737
|
+
#private;
|
|
738
|
+
/** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
|
|
739
|
+
onModuleInit(): Promise<void>;
|
|
740
|
+
/** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
|
|
741
|
+
private traced;
|
|
742
|
+
/**
|
|
743
|
+
* Runs `run` inside a span named `name`.
|
|
744
|
+
*
|
|
745
|
+
* The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
|
|
746
|
+
* throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
|
|
747
|
+
* otherwise, and its own result or error is what comes back.
|
|
748
|
+
*
|
|
749
|
+
* @param name - One of the library's span names.
|
|
750
|
+
* @param attributes - Closed-set attributes of the span.
|
|
751
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
752
|
+
* @param describe - What the span states of a successful result; a throw of its own is the operation's own.
|
|
753
|
+
*/
|
|
754
|
+
span<T>(name: StorageSpanName, attributes: StorageSpanAttributes, run: () => Promise<T>, describe?: ResultAttributes<T>): Promise<T>;
|
|
755
|
+
}
|
|
756
|
+
|
|
757
|
+
/** What an observed operation adds to the plain count and timing. */
|
|
758
|
+
interface ObservedOptions<T> {
|
|
759
|
+
/** The span to start around the operation. */
|
|
760
|
+
readonly span?: StorageSpanName;
|
|
761
|
+
/** Attributes the span starts with. */
|
|
762
|
+
readonly attributes?: StorageSpanAttributes;
|
|
763
|
+
/** What the span states of a successful result. */
|
|
764
|
+
readonly describe?: (result: T) => StorageSpanAttributes;
|
|
765
|
+
/** The bytes of a successful result that reached the provider, for the upload counter. */
|
|
766
|
+
readonly bytes?: (result: T) => number | undefined;
|
|
767
|
+
}
|
|
768
|
+
/**
|
|
769
|
+
* Observes the operations of the library.
|
|
770
|
+
*
|
|
771
|
+
* It is a seam between the services and two optional consumers: the tally the `observability` subpath
|
|
772
|
+
* publishes from, and the span the host's OpenTelemetry SDK records. A service that is built without one
|
|
773
|
+
* (a unit test, say) runs its operations bare.
|
|
774
|
+
*/
|
|
775
|
+
declare class StorageObserver {
|
|
776
|
+
private readonly tally;
|
|
777
|
+
private readonly tracing;
|
|
778
|
+
constructor(tally: StorageMetricsTally, tracing: StorageTracing);
|
|
779
|
+
/**
|
|
780
|
+
* Runs `run`, counting how it ended and how long it took.
|
|
781
|
+
*
|
|
782
|
+
* @param operation - The operation, one of the closed set.
|
|
783
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
784
|
+
* @param options - A span to start, and what to state of the result.
|
|
785
|
+
*/
|
|
786
|
+
observe<T>(operation: StorageOperation, run: () => Promise<T>, options?: ObservedOptions<T>): Promise<T>;
|
|
787
|
+
/**
|
|
788
|
+
* Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
|
|
789
|
+
*
|
|
790
|
+
* @param mode - When the scan runs, `pre-upload` or `post-upload`.
|
|
791
|
+
* @param run - The scan; its result or its error passes through unchanged.
|
|
792
|
+
*/
|
|
793
|
+
scan<T extends {
|
|
794
|
+
readonly status: string;
|
|
795
|
+
}>(mode: 'pre-upload' | 'post-upload', run: () => Promise<T>): Promise<T>;
|
|
796
|
+
}
|
|
797
|
+
|
|
672
798
|
/** Input shape for a scan request. */
|
|
673
799
|
interface ScanInput {
|
|
674
800
|
mode: 'pre-upload' | 'post-upload';
|
|
@@ -681,8 +807,9 @@ interface ScanInput {
|
|
|
681
807
|
declare class FileScannerService {
|
|
682
808
|
private readonly options;
|
|
683
809
|
private readonly scanner;
|
|
810
|
+
private readonly observer?;
|
|
684
811
|
private readonly logger;
|
|
685
|
-
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
|
|
812
|
+
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null, observer?: StorageObserver | undefined);
|
|
686
813
|
/**
|
|
687
814
|
* Returns `true` when both a scanner implementation and scanner options are
|
|
688
815
|
* configured.
|
|
@@ -708,13 +835,22 @@ declare class FileScannerService {
|
|
|
708
835
|
* says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
|
|
709
836
|
*
|
|
710
837
|
* @param input - The scan input.
|
|
838
|
+
* @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
|
|
839
|
+
* bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
|
|
711
840
|
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
712
841
|
* @throws Error when called without a configured scanner.
|
|
713
842
|
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
714
843
|
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
|
|
715
844
|
* @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
|
|
716
845
|
*/
|
|
717
|
-
scan(input: ScanInput): Promise<FileScanResult>;
|
|
846
|
+
scan(input: ScanInput, caller?: Record<string, unknown>): Promise<FileScanResult>;
|
|
847
|
+
/** Runs the scanner and applies the library's policy to what it answered. */
|
|
848
|
+
private evaluate;
|
|
849
|
+
/**
|
|
850
|
+
* `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
|
|
851
|
+
* exactly one of the three): the object is not known to be clean, so it is not stored.
|
|
852
|
+
*/
|
|
853
|
+
private rejectInconclusive;
|
|
718
854
|
/**
|
|
719
855
|
* Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
|
|
720
856
|
* line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
|
|
@@ -813,8 +949,9 @@ declare class StorageService {
|
|
|
813
949
|
private readonly idempotencyCache;
|
|
814
950
|
private readonly validation;
|
|
815
951
|
private readonly scanner;
|
|
952
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
816
953
|
private readonly logger;
|
|
817
|
-
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
|
|
954
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService, observer?: StorageObserver | undefined);
|
|
818
955
|
/**
|
|
819
956
|
* Uploads an object, choosing single-shot or multipart automatically. When an
|
|
820
957
|
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
@@ -929,14 +1066,12 @@ declare class StorageService {
|
|
|
929
1066
|
* `STORAGE_BUCKET_UNDEFINED` before any request.
|
|
930
1067
|
*/
|
|
931
1068
|
checkBucket(options?: BucketScopedOptions): Promise<void>;
|
|
1069
|
+
/** What the single-shot upload needs of this service. */
|
|
1070
|
+
private get uploadContext();
|
|
932
1071
|
/** Throws when the S3 client was never built (missing credentials). */
|
|
933
1072
|
private assertConfigured;
|
|
934
1073
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
935
1074
|
private resolveBucket;
|
|
936
|
-
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
937
|
-
private toObjectMetadata;
|
|
938
|
-
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
939
|
-
private uploadSingleShot;
|
|
940
1075
|
/**
|
|
941
1076
|
* Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
|
|
942
1077
|
* (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
|
|
@@ -1060,7 +1195,8 @@ declare class SignedUrlService {
|
|
|
1060
1195
|
private readonly options;
|
|
1061
1196
|
private readonly s3Provider;
|
|
1062
1197
|
private readonly keyResolver;
|
|
1063
|
-
|
|
1198
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1199
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1064
1200
|
/**
|
|
1065
1201
|
* Issues a presigned GET URL for downloading an object.
|
|
1066
1202
|
*
|
|
@@ -1203,7 +1339,8 @@ declare class BucketLifecycleService {
|
|
|
1203
1339
|
private readonly options;
|
|
1204
1340
|
private readonly s3Provider;
|
|
1205
1341
|
private readonly keyResolver;
|
|
1206
|
-
|
|
1342
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1343
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1207
1344
|
/**
|
|
1208
1345
|
* Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
|
|
1209
1346
|
* yields an empty array. Key prefixes inside the module's `keyPrefix` come back
|
|
@@ -1486,8 +1623,10 @@ declare class StorageException extends HttpException {
|
|
|
1486
1623
|
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1487
1624
|
statusCode?: number, details?: Record<string, unknown>,
|
|
1488
1625
|
/** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
|
|
1489
|
-
message?: string
|
|
1626
|
+
message?: string,
|
|
1627
|
+
/** What made the call fail, for a log or a debugger; it is never part of the response body. */
|
|
1628
|
+
cause?: unknown);
|
|
1490
1629
|
}
|
|
1491
1630
|
|
|
1492
|
-
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 };
|
|
1493
|
-
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
|
|
1631
|
+
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 };
|
|
1632
|
+
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, ScanVerdict, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, StorageOperation, StorageOutcome, UploadOptions, UploadResult };
|
package/dist/server/index.d.ts
CHANGED
|
@@ -669,6 +669,132 @@ declare class ValidationService {
|
|
|
669
669
|
private runCustomValidators;
|
|
670
670
|
}
|
|
671
671
|
|
|
672
|
+
/** The operations the library counts and times. */
|
|
673
|
+
declare const STORAGE_OPERATIONS: readonly ["upload", "download", "head", "delete", "delete_many", "list", "copy", "get_download_url", "get_upload_url", "get_multipart_upload_urls", "check_bucket", "lifecycle_get", "lifecycle_upsert", "lifecycle_remove"];
|
|
674
|
+
/** What an operation ended as. */
|
|
675
|
+
declare const STORAGE_OUTCOMES: readonly ["success", "not_found", "aborted", "error"];
|
|
676
|
+
/** What a scan ended as. */
|
|
677
|
+
declare const SCAN_VERDICTS: readonly ["clean", "infected", "unknown", "timeout", "error"];
|
|
678
|
+
/** One of {@link STORAGE_OPERATIONS}. */
|
|
679
|
+
type StorageOperation = (typeof STORAGE_OPERATIONS)[number];
|
|
680
|
+
/** One of {@link STORAGE_OUTCOMES}. */
|
|
681
|
+
type StorageOutcome = (typeof STORAGE_OUTCOMES)[number];
|
|
682
|
+
/** One of {@link SCAN_VERDICTS}. */
|
|
683
|
+
type ScanVerdict = (typeof SCAN_VERDICTS)[number];
|
|
684
|
+
|
|
685
|
+
/** Told how long an operation took, once it ended. Typed to return a value: a listener typed `void` can still return a promise. */
|
|
686
|
+
type DurationListener = (operation: StorageOperation, seconds: number) => unknown;
|
|
687
|
+
/**
|
|
688
|
+
* Counts what the storage operations do. Each count is keyed by a closed set (see `storage-operations`), so no
|
|
689
|
+
* label can grow with the traffic, and nothing a caller or a host supplied is ever a key. The optional
|
|
690
|
+
* `observability` subpath reads these numbers when it is scraped, and feeds a duration histogram through
|
|
691
|
+
* {@link StorageMetricsTally.onDuration}.
|
|
692
|
+
*/
|
|
693
|
+
declare class StorageMetricsTally {
|
|
694
|
+
#private;
|
|
695
|
+
/** An operation ended as `outcome` after `seconds`. */
|
|
696
|
+
operation(operation: StorageOperation, outcome: StorageOutcome, seconds: number): void;
|
|
697
|
+
/**
|
|
698
|
+
* `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. The
|
|
699
|
+
* count stops at the largest finite number: a sum of two finite sizes can overflow to `Infinity`, which no
|
|
700
|
+
* counter accepts, and a scrape that read it would fail whole.
|
|
701
|
+
*/
|
|
702
|
+
bytesUploaded(bytes: number | undefined): void;
|
|
703
|
+
/** A scan ended as `verdict`. */
|
|
704
|
+
scan(verdict: ScanVerdict): void;
|
|
705
|
+
/** Calls `listener` with the duration of every operation that ends from now on. */
|
|
706
|
+
onDuration(listener: DurationListener): void;
|
|
707
|
+
/** The counts so far, as copies. */
|
|
708
|
+
snapshot(): {
|
|
709
|
+
readonly operations: Readonly<Record<StorageOperation, Readonly<Record<StorageOutcome, number>>>>;
|
|
710
|
+
readonly bytesUploaded: number;
|
|
711
|
+
readonly scans: Readonly<Record<ScanVerdict, number>>;
|
|
712
|
+
};
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
/** The span names the library starts. */
|
|
716
|
+
type StorageSpanName = 'storage.upload' | 'storage.download_url' | 'storage.scan';
|
|
717
|
+
/**
|
|
718
|
+
* The attributes a span carries, named one by one: the outcome, whether an upload was multipart, and when a scan
|
|
719
|
+
* runs. A key, a bucket or a payload has no member, so a call site cannot add one.
|
|
720
|
+
*/
|
|
721
|
+
interface StorageSpanAttributes {
|
|
722
|
+
readonly 'bymax.storage.outcome'?: StorageOutcome;
|
|
723
|
+
readonly 'bymax.storage.multipart'?: 'true' | 'false';
|
|
724
|
+
readonly 'bymax.storage.scan_mode'?: 'pre-upload' | 'post-upload';
|
|
725
|
+
}
|
|
726
|
+
/** What a span states of a result, once the operation succeeded. */
|
|
727
|
+
type ResultAttributes<T> = (result: T) => StorageSpanAttributes;
|
|
728
|
+
/**
|
|
729
|
+
* Starts a span around an operation when `@opentelemetry/api` is installed, and runs it bare otherwise.
|
|
730
|
+
*
|
|
731
|
+
* The peer is optional, so it is loaded with a dynamic `import()` that a missing package turns into a no-op:
|
|
732
|
+
* the server bundle never names it statically, and an application that does not trace installs nothing. With
|
|
733
|
+
* the API present and no SDK registered the API itself is a no-op. A span carries a closed set of attributes
|
|
734
|
+
* and, on failure, the library error code and nothing of the message.
|
|
735
|
+
*/
|
|
736
|
+
declare class StorageTracing implements OnModuleInit {
|
|
737
|
+
#private;
|
|
738
|
+
/** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
|
|
739
|
+
onModuleInit(): Promise<void>;
|
|
740
|
+
/** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
|
|
741
|
+
private traced;
|
|
742
|
+
/**
|
|
743
|
+
* Runs `run` inside a span named `name`.
|
|
744
|
+
*
|
|
745
|
+
* The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
|
|
746
|
+
* throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
|
|
747
|
+
* otherwise, and its own result or error is what comes back.
|
|
748
|
+
*
|
|
749
|
+
* @param name - One of the library's span names.
|
|
750
|
+
* @param attributes - Closed-set attributes of the span.
|
|
751
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
752
|
+
* @param describe - What the span states of a successful result; a throw of its own is the operation's own.
|
|
753
|
+
*/
|
|
754
|
+
span<T>(name: StorageSpanName, attributes: StorageSpanAttributes, run: () => Promise<T>, describe?: ResultAttributes<T>): Promise<T>;
|
|
755
|
+
}
|
|
756
|
+
|
|
757
|
+
/** What an observed operation adds to the plain count and timing. */
|
|
758
|
+
interface ObservedOptions<T> {
|
|
759
|
+
/** The span to start around the operation. */
|
|
760
|
+
readonly span?: StorageSpanName;
|
|
761
|
+
/** Attributes the span starts with. */
|
|
762
|
+
readonly attributes?: StorageSpanAttributes;
|
|
763
|
+
/** What the span states of a successful result. */
|
|
764
|
+
readonly describe?: (result: T) => StorageSpanAttributes;
|
|
765
|
+
/** The bytes of a successful result that reached the provider, for the upload counter. */
|
|
766
|
+
readonly bytes?: (result: T) => number | undefined;
|
|
767
|
+
}
|
|
768
|
+
/**
|
|
769
|
+
* Observes the operations of the library.
|
|
770
|
+
*
|
|
771
|
+
* It is a seam between the services and two optional consumers: the tally the `observability` subpath
|
|
772
|
+
* publishes from, and the span the host's OpenTelemetry SDK records. A service that is built without one
|
|
773
|
+
* (a unit test, say) runs its operations bare.
|
|
774
|
+
*/
|
|
775
|
+
declare class StorageObserver {
|
|
776
|
+
private readonly tally;
|
|
777
|
+
private readonly tracing;
|
|
778
|
+
constructor(tally: StorageMetricsTally, tracing: StorageTracing);
|
|
779
|
+
/**
|
|
780
|
+
* Runs `run`, counting how it ended and how long it took.
|
|
781
|
+
*
|
|
782
|
+
* @param operation - The operation, one of the closed set.
|
|
783
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
784
|
+
* @param options - A span to start, and what to state of the result.
|
|
785
|
+
*/
|
|
786
|
+
observe<T>(operation: StorageOperation, run: () => Promise<T>, options?: ObservedOptions<T>): Promise<T>;
|
|
787
|
+
/**
|
|
788
|
+
* Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
|
|
789
|
+
*
|
|
790
|
+
* @param mode - When the scan runs, `pre-upload` or `post-upload`.
|
|
791
|
+
* @param run - The scan; its result or its error passes through unchanged.
|
|
792
|
+
*/
|
|
793
|
+
scan<T extends {
|
|
794
|
+
readonly status: string;
|
|
795
|
+
}>(mode: 'pre-upload' | 'post-upload', run: () => Promise<T>): Promise<T>;
|
|
796
|
+
}
|
|
797
|
+
|
|
672
798
|
/** Input shape for a scan request. */
|
|
673
799
|
interface ScanInput {
|
|
674
800
|
mode: 'pre-upload' | 'post-upload';
|
|
@@ -681,8 +807,9 @@ interface ScanInput {
|
|
|
681
807
|
declare class FileScannerService {
|
|
682
808
|
private readonly options;
|
|
683
809
|
private readonly scanner;
|
|
810
|
+
private readonly observer?;
|
|
684
811
|
private readonly logger;
|
|
685
|
-
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
|
|
812
|
+
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null, observer?: StorageObserver | undefined);
|
|
686
813
|
/**
|
|
687
814
|
* Returns `true` when both a scanner implementation and scanner options are
|
|
688
815
|
* configured.
|
|
@@ -708,13 +835,22 @@ declare class FileScannerService {
|
|
|
708
835
|
* says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
|
|
709
836
|
*
|
|
710
837
|
* @param input - The scan input.
|
|
838
|
+
* @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
|
|
839
|
+
* bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
|
|
711
840
|
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
712
841
|
* @throws Error when called without a configured scanner.
|
|
713
842
|
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
714
843
|
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
|
|
715
844
|
* @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
|
|
716
845
|
*/
|
|
717
|
-
scan(input: ScanInput): Promise<FileScanResult>;
|
|
846
|
+
scan(input: ScanInput, caller?: Record<string, unknown>): Promise<FileScanResult>;
|
|
847
|
+
/** Runs the scanner and applies the library's policy to what it answered. */
|
|
848
|
+
private evaluate;
|
|
849
|
+
/**
|
|
850
|
+
* `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
|
|
851
|
+
* exactly one of the three): the object is not known to be clean, so it is not stored.
|
|
852
|
+
*/
|
|
853
|
+
private rejectInconclusive;
|
|
718
854
|
/**
|
|
719
855
|
* Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
|
|
720
856
|
* line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
|
|
@@ -813,8 +949,9 @@ declare class StorageService {
|
|
|
813
949
|
private readonly idempotencyCache;
|
|
814
950
|
private readonly validation;
|
|
815
951
|
private readonly scanner;
|
|
952
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
816
953
|
private readonly logger;
|
|
817
|
-
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
|
|
954
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService, observer?: StorageObserver | undefined);
|
|
818
955
|
/**
|
|
819
956
|
* Uploads an object, choosing single-shot or multipart automatically. When an
|
|
820
957
|
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
@@ -929,14 +1066,12 @@ declare class StorageService {
|
|
|
929
1066
|
* `STORAGE_BUCKET_UNDEFINED` before any request.
|
|
930
1067
|
*/
|
|
931
1068
|
checkBucket(options?: BucketScopedOptions): Promise<void>;
|
|
1069
|
+
/** What the single-shot upload needs of this service. */
|
|
1070
|
+
private get uploadContext();
|
|
932
1071
|
/** Throws when the S3 client was never built (missing credentials). */
|
|
933
1072
|
private assertConfigured;
|
|
934
1073
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
935
1074
|
private resolveBucket;
|
|
936
|
-
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
937
|
-
private toObjectMetadata;
|
|
938
|
-
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
939
|
-
private uploadSingleShot;
|
|
940
1075
|
/**
|
|
941
1076
|
* Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
|
|
942
1077
|
* (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
|
|
@@ -1060,7 +1195,8 @@ declare class SignedUrlService {
|
|
|
1060
1195
|
private readonly options;
|
|
1061
1196
|
private readonly s3Provider;
|
|
1062
1197
|
private readonly keyResolver;
|
|
1063
|
-
|
|
1198
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1199
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1064
1200
|
/**
|
|
1065
1201
|
* Issues a presigned GET URL for downloading an object.
|
|
1066
1202
|
*
|
|
@@ -1203,7 +1339,8 @@ declare class BucketLifecycleService {
|
|
|
1203
1339
|
private readonly options;
|
|
1204
1340
|
private readonly s3Provider;
|
|
1205
1341
|
private readonly keyResolver;
|
|
1206
|
-
|
|
1342
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1343
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1207
1344
|
/**
|
|
1208
1345
|
* Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
|
|
1209
1346
|
* yields an empty array. Key prefixes inside the module's `keyPrefix` come back
|
|
@@ -1486,8 +1623,10 @@ declare class StorageException extends HttpException {
|
|
|
1486
1623
|
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1487
1624
|
statusCode?: number, details?: Record<string, unknown>,
|
|
1488
1625
|
/** Defaults to the message of `code`. Pass only when the situation is more specific than the code. */
|
|
1489
|
-
message?: string
|
|
1626
|
+
message?: string,
|
|
1627
|
+
/** What made the call fail, for a log or a debugger; it is never part of the response body. */
|
|
1628
|
+
cause?: unknown);
|
|
1490
1629
|
}
|
|
1491
1630
|
|
|
1492
|
-
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 };
|
|
1493
|
-
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, UploadOptions, UploadResult };
|
|
1631
|
+
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 };
|
|
1632
|
+
export type { AbortMultipartRuleInput, BucketLifecycleRule, BucketLifecycleRuleView, BymaxStorageModuleAsyncOptions, BymaxStorageModuleOptions, BymaxStorageModuleOptionsFactory, CopyOptions, DeleteManyOptions, DeleteManyResult, DownloadBufferOptions, DownloadOptions, ExpirationRuleInput, FailedDeletion, FileScanResult, IFileScanner, IUploadValidator, LifecycleBucketOptions, LifecycleRuleInput, ListOptions, ListResult, ListedObject, MultipartUploadUrlsOptions, MultipartUploadUrlsResult, ObjectMetadata, ProviderRecipe, ScanVerdict, SignedGetUrlOptions, SignedPutUrlOptions, SignedUrlResult, StorageErrorCode, StorageOperation, StorageOutcome, UploadOptions, UploadResult };
|