@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.
- package/CHANGELOG.md +169 -1
- package/README.md +172 -21
- 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 +895 -420
- package/dist/server/index.d.cts +137 -11
- package/dist/server/index.d.ts +137 -11
- package/dist/server/index.mjs +895 -423
- package/package.json +32 -5
package/dist/server/index.d.cts
CHANGED
|
@@ -669,6 +669,121 @@ 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
|
+
/** `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. */
|
|
698
|
+
bytesUploaded(bytes: number | undefined): void;
|
|
699
|
+
/** A scan ended as `verdict`. */
|
|
700
|
+
scan(verdict: ScanVerdict): void;
|
|
701
|
+
/** Calls `listener` with the duration of every operation that ends from now on. */
|
|
702
|
+
onDuration(listener: DurationListener): void;
|
|
703
|
+
/** The counts so far, as copies. */
|
|
704
|
+
snapshot(): {
|
|
705
|
+
readonly operations: Readonly<Record<StorageOperation, Readonly<Record<StorageOutcome, number>>>>;
|
|
706
|
+
readonly bytesUploaded: number;
|
|
707
|
+
readonly scans: Readonly<Record<ScanVerdict, number>>;
|
|
708
|
+
};
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
/** The span names the library starts. */
|
|
712
|
+
type StorageSpanName = 'storage.upload' | 'storage.download_url' | 'storage.scan';
|
|
713
|
+
/** Attributes are closed: an operation, an outcome, a mode or a flag, never a key, a bucket or a payload. */
|
|
714
|
+
type StorageSpanAttributes = Readonly<Record<string, string>>;
|
|
715
|
+
/** What a span states of a result, once the operation succeeded. */
|
|
716
|
+
type ResultAttributes<T> = (result: T) => StorageSpanAttributes;
|
|
717
|
+
/**
|
|
718
|
+
* Starts a span around an operation when `@opentelemetry/api` is installed, and runs it bare otherwise.
|
|
719
|
+
*
|
|
720
|
+
* The peer is optional, so it is loaded with a dynamic `import()` that a missing package turns into a no-op:
|
|
721
|
+
* the server bundle never names it statically, and an application that does not trace installs nothing. With
|
|
722
|
+
* the API present and no SDK registered the API itself is a no-op. A span carries a closed set of attributes
|
|
723
|
+
* and, on failure, the library error code and nothing of the message.
|
|
724
|
+
*/
|
|
725
|
+
declare class StorageTracing implements OnModuleInit {
|
|
726
|
+
#private;
|
|
727
|
+
/** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
|
|
728
|
+
onModuleInit(): Promise<void>;
|
|
729
|
+
/** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
|
|
730
|
+
private traced;
|
|
731
|
+
/**
|
|
732
|
+
* Runs `run` inside a span named `name`.
|
|
733
|
+
*
|
|
734
|
+
* The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
|
|
735
|
+
* throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
|
|
736
|
+
* otherwise, and its own result or error is what comes back.
|
|
737
|
+
*
|
|
738
|
+
* @param name - One of the library's span names.
|
|
739
|
+
* @param attributes - Closed-set attributes of the span.
|
|
740
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
741
|
+
* @param describe - What the span states of a successful result; a throw of its own is the operation's own.
|
|
742
|
+
*/
|
|
743
|
+
span<T>(name: StorageSpanName, attributes: StorageSpanAttributes, run: () => Promise<T>, describe?: ResultAttributes<T>): Promise<T>;
|
|
744
|
+
}
|
|
745
|
+
|
|
746
|
+
/** What an observed operation adds to the plain count and timing. */
|
|
747
|
+
interface ObservedOptions<T> {
|
|
748
|
+
/** The span to start around the operation. */
|
|
749
|
+
readonly span?: StorageSpanName;
|
|
750
|
+
/** Attributes the span starts with. */
|
|
751
|
+
readonly attributes?: StorageSpanAttributes;
|
|
752
|
+
/** What the span states of a successful result. */
|
|
753
|
+
readonly describe?: (result: T) => StorageSpanAttributes;
|
|
754
|
+
/** The bytes of a successful result that reached the provider, for the upload counter. */
|
|
755
|
+
readonly bytes?: (result: T) => number | undefined;
|
|
756
|
+
}
|
|
757
|
+
/**
|
|
758
|
+
* Observes the operations of the library.
|
|
759
|
+
*
|
|
760
|
+
* It is a seam between the services and two optional consumers: the tally the `observability` subpath
|
|
761
|
+
* publishes from, and the span the host's OpenTelemetry SDK records. A service that is built without one
|
|
762
|
+
* (a unit test, say) runs its operations bare.
|
|
763
|
+
*/
|
|
764
|
+
declare class StorageObserver {
|
|
765
|
+
private readonly tally;
|
|
766
|
+
private readonly tracing;
|
|
767
|
+
constructor(tally: StorageMetricsTally, tracing: StorageTracing);
|
|
768
|
+
/**
|
|
769
|
+
* Runs `run`, counting how it ended and how long it took.
|
|
770
|
+
*
|
|
771
|
+
* @param operation - The operation, one of the closed set.
|
|
772
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
773
|
+
* @param options - A span to start, and what to state of the result.
|
|
774
|
+
*/
|
|
775
|
+
observe<T>(operation: StorageOperation, run: () => Promise<T>, options?: ObservedOptions<T>): Promise<T>;
|
|
776
|
+
/**
|
|
777
|
+
* Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
|
|
778
|
+
*
|
|
779
|
+
* @param mode - When the scan runs, `pre-upload` or `post-upload`.
|
|
780
|
+
* @param run - The scan; its result or its error passes through unchanged.
|
|
781
|
+
*/
|
|
782
|
+
scan<T extends {
|
|
783
|
+
readonly status: string;
|
|
784
|
+
}>(mode: string, run: () => Promise<T>): Promise<T>;
|
|
785
|
+
}
|
|
786
|
+
|
|
672
787
|
/** Input shape for a scan request. */
|
|
673
788
|
interface ScanInput {
|
|
674
789
|
mode: 'pre-upload' | 'post-upload';
|
|
@@ -681,8 +796,9 @@ interface ScanInput {
|
|
|
681
796
|
declare class FileScannerService {
|
|
682
797
|
private readonly options;
|
|
683
798
|
private readonly scanner;
|
|
799
|
+
private readonly observer?;
|
|
684
800
|
private readonly logger;
|
|
685
|
-
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
|
|
801
|
+
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null, observer?: StorageObserver | undefined);
|
|
686
802
|
/**
|
|
687
803
|
* Returns `true` when both a scanner implementation and scanner options are
|
|
688
804
|
* configured.
|
|
@@ -708,13 +824,22 @@ declare class FileScannerService {
|
|
|
708
824
|
* says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
|
|
709
825
|
*
|
|
710
826
|
* @param input - The scan input.
|
|
827
|
+
* @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
|
|
828
|
+
* bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
|
|
711
829
|
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
712
830
|
* @throws Error when called without a configured scanner.
|
|
713
831
|
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
714
832
|
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
|
|
715
833
|
* @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
|
|
716
834
|
*/
|
|
717
|
-
scan(input: ScanInput): Promise<FileScanResult>;
|
|
835
|
+
scan(input: ScanInput, caller?: Record<string, unknown>): Promise<FileScanResult>;
|
|
836
|
+
/** Runs the scanner and applies the library's policy to what it answered. */
|
|
837
|
+
private evaluate;
|
|
838
|
+
/**
|
|
839
|
+
* `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
|
|
840
|
+
* exactly one of the three): the object is not known to be clean, so it is not stored.
|
|
841
|
+
*/
|
|
842
|
+
private rejectInconclusive;
|
|
718
843
|
/**
|
|
719
844
|
* Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
|
|
720
845
|
* line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
|
|
@@ -813,8 +938,9 @@ declare class StorageService {
|
|
|
813
938
|
private readonly idempotencyCache;
|
|
814
939
|
private readonly validation;
|
|
815
940
|
private readonly scanner;
|
|
941
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
816
942
|
private readonly logger;
|
|
817
|
-
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
|
|
943
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService, observer?: StorageObserver | undefined);
|
|
818
944
|
/**
|
|
819
945
|
* Uploads an object, choosing single-shot or multipart automatically. When an
|
|
820
946
|
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
@@ -929,14 +1055,12 @@ declare class StorageService {
|
|
|
929
1055
|
* `STORAGE_BUCKET_UNDEFINED` before any request.
|
|
930
1056
|
*/
|
|
931
1057
|
checkBucket(options?: BucketScopedOptions): Promise<void>;
|
|
1058
|
+
/** What the single-shot upload needs of this service. */
|
|
1059
|
+
private get uploadContext();
|
|
932
1060
|
/** Throws when the S3 client was never built (missing credentials). */
|
|
933
1061
|
private assertConfigured;
|
|
934
1062
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
935
1063
|
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
1064
|
/**
|
|
941
1065
|
* Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
|
|
942
1066
|
* (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
|
|
@@ -1060,7 +1184,8 @@ declare class SignedUrlService {
|
|
|
1060
1184
|
private readonly options;
|
|
1061
1185
|
private readonly s3Provider;
|
|
1062
1186
|
private readonly keyResolver;
|
|
1063
|
-
|
|
1187
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1188
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1064
1189
|
/**
|
|
1065
1190
|
* Issues a presigned GET URL for downloading an object.
|
|
1066
1191
|
*
|
|
@@ -1203,7 +1328,8 @@ declare class BucketLifecycleService {
|
|
|
1203
1328
|
private readonly options;
|
|
1204
1329
|
private readonly s3Provider;
|
|
1205
1330
|
private readonly keyResolver;
|
|
1206
|
-
|
|
1331
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1332
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1207
1333
|
/**
|
|
1208
1334
|
* Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
|
|
1209
1335
|
* yields an empty array. Key prefixes inside the module's `keyPrefix` come back
|
|
@@ -1489,5 +1615,5 @@ declare class StorageException extends HttpException {
|
|
|
1489
1615
|
message?: string);
|
|
1490
1616
|
}
|
|
1491
1617
|
|
|
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 };
|
|
1618
|
+
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 };
|
|
1619
|
+
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,121 @@ 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
|
+
/** `bytes` of an object reached the provider; anything that is not a positive finite number is ignored. */
|
|
698
|
+
bytesUploaded(bytes: number | undefined): void;
|
|
699
|
+
/** A scan ended as `verdict`. */
|
|
700
|
+
scan(verdict: ScanVerdict): void;
|
|
701
|
+
/** Calls `listener` with the duration of every operation that ends from now on. */
|
|
702
|
+
onDuration(listener: DurationListener): void;
|
|
703
|
+
/** The counts so far, as copies. */
|
|
704
|
+
snapshot(): {
|
|
705
|
+
readonly operations: Readonly<Record<StorageOperation, Readonly<Record<StorageOutcome, number>>>>;
|
|
706
|
+
readonly bytesUploaded: number;
|
|
707
|
+
readonly scans: Readonly<Record<ScanVerdict, number>>;
|
|
708
|
+
};
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
/** The span names the library starts. */
|
|
712
|
+
type StorageSpanName = 'storage.upload' | 'storage.download_url' | 'storage.scan';
|
|
713
|
+
/** Attributes are closed: an operation, an outcome, a mode or a flag, never a key, a bucket or a payload. */
|
|
714
|
+
type StorageSpanAttributes = Readonly<Record<string, string>>;
|
|
715
|
+
/** What a span states of a result, once the operation succeeded. */
|
|
716
|
+
type ResultAttributes<T> = (result: T) => StorageSpanAttributes;
|
|
717
|
+
/**
|
|
718
|
+
* Starts a span around an operation when `@opentelemetry/api` is installed, and runs it bare otherwise.
|
|
719
|
+
*
|
|
720
|
+
* The peer is optional, so it is loaded with a dynamic `import()` that a missing package turns into a no-op:
|
|
721
|
+
* the server bundle never names it statically, and an application that does not trace installs nothing. With
|
|
722
|
+
* the API present and no SDK registered the API itself is a no-op. A span carries a closed set of attributes
|
|
723
|
+
* and, on failure, the library error code and nothing of the message.
|
|
724
|
+
*/
|
|
725
|
+
declare class StorageTracing implements OnModuleInit {
|
|
726
|
+
#private;
|
|
727
|
+
/** Loads the API once, at start-up; a package that is not there leaves the seam inert. */
|
|
728
|
+
onModuleInit(): Promise<void>;
|
|
729
|
+
/** Runs the operation and reports it on the span, where nothing the span does can change what comes back. */
|
|
730
|
+
private traced;
|
|
731
|
+
/**
|
|
732
|
+
* Runs `run` inside a span named `name`.
|
|
733
|
+
*
|
|
734
|
+
* The tracer belongs to the host's SDK, so it is never trusted with the operation: whatever it returns or
|
|
735
|
+
* throws is ignored, the operation runs exactly once, through the span when the tracer started it and bare
|
|
736
|
+
* otherwise, and its own result or error is what comes back.
|
|
737
|
+
*
|
|
738
|
+
* @param name - One of the library's span names.
|
|
739
|
+
* @param attributes - Closed-set attributes of the span.
|
|
740
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
741
|
+
* @param describe - What the span states of a successful result; a throw of its own is the operation's own.
|
|
742
|
+
*/
|
|
743
|
+
span<T>(name: StorageSpanName, attributes: StorageSpanAttributes, run: () => Promise<T>, describe?: ResultAttributes<T>): Promise<T>;
|
|
744
|
+
}
|
|
745
|
+
|
|
746
|
+
/** What an observed operation adds to the plain count and timing. */
|
|
747
|
+
interface ObservedOptions<T> {
|
|
748
|
+
/** The span to start around the operation. */
|
|
749
|
+
readonly span?: StorageSpanName;
|
|
750
|
+
/** Attributes the span starts with. */
|
|
751
|
+
readonly attributes?: StorageSpanAttributes;
|
|
752
|
+
/** What the span states of a successful result. */
|
|
753
|
+
readonly describe?: (result: T) => StorageSpanAttributes;
|
|
754
|
+
/** The bytes of a successful result that reached the provider, for the upload counter. */
|
|
755
|
+
readonly bytes?: (result: T) => number | undefined;
|
|
756
|
+
}
|
|
757
|
+
/**
|
|
758
|
+
* Observes the operations of the library.
|
|
759
|
+
*
|
|
760
|
+
* It is a seam between the services and two optional consumers: the tally the `observability` subpath
|
|
761
|
+
* publishes from, and the span the host's OpenTelemetry SDK records. A service that is built without one
|
|
762
|
+
* (a unit test, say) runs its operations bare.
|
|
763
|
+
*/
|
|
764
|
+
declare class StorageObserver {
|
|
765
|
+
private readonly tally;
|
|
766
|
+
private readonly tracing;
|
|
767
|
+
constructor(tally: StorageMetricsTally, tracing: StorageTracing);
|
|
768
|
+
/**
|
|
769
|
+
* Runs `run`, counting how it ended and how long it took.
|
|
770
|
+
*
|
|
771
|
+
* @param operation - The operation, one of the closed set.
|
|
772
|
+
* @param run - The operation; its result or its error passes through unchanged.
|
|
773
|
+
* @param options - A span to start, and what to state of the result.
|
|
774
|
+
*/
|
|
775
|
+
observe<T>(operation: StorageOperation, run: () => Promise<T>, options?: ObservedOptions<T>): Promise<T>;
|
|
776
|
+
/**
|
|
777
|
+
* Runs a scan, counting its verdict and wrapping it in the `storage.scan` span.
|
|
778
|
+
*
|
|
779
|
+
* @param mode - When the scan runs, `pre-upload` or `post-upload`.
|
|
780
|
+
* @param run - The scan; its result or its error passes through unchanged.
|
|
781
|
+
*/
|
|
782
|
+
scan<T extends {
|
|
783
|
+
readonly status: string;
|
|
784
|
+
}>(mode: string, run: () => Promise<T>): Promise<T>;
|
|
785
|
+
}
|
|
786
|
+
|
|
672
787
|
/** Input shape for a scan request. */
|
|
673
788
|
interface ScanInput {
|
|
674
789
|
mode: 'pre-upload' | 'post-upload';
|
|
@@ -681,8 +796,9 @@ interface ScanInput {
|
|
|
681
796
|
declare class FileScannerService {
|
|
682
797
|
private readonly options;
|
|
683
798
|
private readonly scanner;
|
|
799
|
+
private readonly observer?;
|
|
684
800
|
private readonly logger;
|
|
685
|
-
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
|
|
801
|
+
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null, observer?: StorageObserver | undefined);
|
|
686
802
|
/**
|
|
687
803
|
* Returns `true` when both a scanner implementation and scanner options are
|
|
688
804
|
* configured.
|
|
@@ -708,13 +824,22 @@ declare class FileScannerService {
|
|
|
708
824
|
* says, and a scan that outlasts `scanner.timeoutMs` throws `STORAGE_TIMEOUT`.
|
|
709
825
|
*
|
|
710
826
|
* @param input - The scan input.
|
|
827
|
+
* @param caller - What the deadline error repeats of the call (see `callerFields`): the caller's own key and
|
|
828
|
+
* bucket, never the prefixed key or the configured bucket that `input` holds for the scanner.
|
|
711
829
|
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
712
830
|
* @throws Error when called without a configured scanner.
|
|
713
831
|
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
714
832
|
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`, or a result outside the contract.
|
|
715
833
|
* @throws StorageException `STORAGE_TIMEOUT` when the scan outlasts `scanner.timeoutMs`.
|
|
716
834
|
*/
|
|
717
|
-
scan(input: ScanInput): Promise<FileScanResult>;
|
|
835
|
+
scan(input: ScanInput, caller?: Record<string, unknown>): Promise<FileScanResult>;
|
|
836
|
+
/** Runs the scanner and applies the library's policy to what it answered. */
|
|
837
|
+
private evaluate;
|
|
838
|
+
/**
|
|
839
|
+
* `unknown` with `rejectOnUnknown`, or a result outside the contract (no result, a status that is not
|
|
840
|
+
* exactly one of the three): the object is not known to be clean, so it is not stored.
|
|
841
|
+
*/
|
|
842
|
+
private rejectInconclusive;
|
|
718
843
|
/**
|
|
719
844
|
* Runs the scan and logs a scanner that throws: the caller is answered 500 for that, and without the
|
|
720
845
|
* line there would be no trace of why. A typed failure of ours (the deadline) says it itself.
|
|
@@ -813,8 +938,9 @@ declare class StorageService {
|
|
|
813
938
|
private readonly idempotencyCache;
|
|
814
939
|
private readonly validation;
|
|
815
940
|
private readonly scanner;
|
|
941
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
816
942
|
private readonly logger;
|
|
817
|
-
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
|
|
943
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService, observer?: StorageObserver | undefined);
|
|
818
944
|
/**
|
|
819
945
|
* Uploads an object, choosing single-shot or multipart automatically. When an
|
|
820
946
|
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
@@ -929,14 +1055,12 @@ declare class StorageService {
|
|
|
929
1055
|
* `STORAGE_BUCKET_UNDEFINED` before any request.
|
|
930
1056
|
*/
|
|
931
1057
|
checkBucket(options?: BucketScopedOptions): Promise<void>;
|
|
1058
|
+
/** What the single-shot upload needs of this service. */
|
|
1059
|
+
private get uploadContext();
|
|
932
1060
|
/** Throws when the S3 client was never built (missing credentials). */
|
|
933
1061
|
private assertConfigured;
|
|
934
1062
|
/** Resolves the target bucket from a per-call override or the module default. */
|
|
935
1063
|
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
1064
|
/**
|
|
941
1065
|
* Multipart upload via `@aws-sdk/lib-storage`. The SDK is told to leave the parts
|
|
942
1066
|
* (`leavePartsOnError: true`) because its own abort runs inside its failure path: a failing
|
|
@@ -1060,7 +1184,8 @@ declare class SignedUrlService {
|
|
|
1060
1184
|
private readonly options;
|
|
1061
1185
|
private readonly s3Provider;
|
|
1062
1186
|
private readonly keyResolver;
|
|
1063
|
-
|
|
1187
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1188
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1064
1189
|
/**
|
|
1065
1190
|
* Issues a presigned GET URL for downloading an object.
|
|
1066
1191
|
*
|
|
@@ -1203,7 +1328,8 @@ declare class BucketLifecycleService {
|
|
|
1203
1328
|
private readonly options;
|
|
1204
1329
|
private readonly s3Provider;
|
|
1205
1330
|
private readonly keyResolver;
|
|
1206
|
-
|
|
1331
|
+
protected readonly observer?: StorageObserver | undefined;
|
|
1332
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, observer?: StorageObserver | undefined);
|
|
1207
1333
|
/**
|
|
1208
1334
|
* Returns the bucket's lifecycle rules. A bucket with no lifecycle configuration
|
|
1209
1335
|
* yields an empty array. Key prefixes inside the module's `keyPrefix` come back
|
|
@@ -1489,5 +1615,5 @@ declare class StorageException extends HttpException {
|
|
|
1489
1615
|
message?: string);
|
|
1490
1616
|
}
|
|
1491
1617
|
|
|
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 };
|
|
1618
|
+
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 };
|
|
1619
|
+
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 };
|