@bymax-one/nest-storage 1.0.0
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 +99 -0
- package/LICENSE +21 -0
- package/README.md +546 -0
- package/dist/server/index.cjs +1848 -0
- package/dist/server/index.d.cts +1210 -0
- package/dist/server/index.d.ts +1210 -0
- package/dist/server/index.mjs +1836 -0
- package/dist/shared/index.cjs +63 -0
- package/dist/shared/index.d.cts +143 -0
- package/dist/shared/index.d.ts +143 -0
- package/dist/shared/index.mjs +53 -0
- package/package.json +159 -0
|
@@ -0,0 +1,1210 @@
|
|
|
1
|
+
import { ModuleMetadata, Type, DynamicModule, OnModuleInit, OnApplicationShutdown, HttpException, HttpStatus } from '@nestjs/common';
|
|
2
|
+
import { S3Client } from '@aws-sdk/client-s3';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* @fileoverview Pluggable upload-validator contract. Implementations run in order
|
|
6
|
+
* before the S3 PutObject — the first that returns `{ ok: false }` aborts the
|
|
7
|
+
* upload.
|
|
8
|
+
* @layer server/interfaces
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Pluggable upload validator.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* class PdfMagicByteValidator implements IUploadValidator {
|
|
15
|
+
* readonly name = 'pdf-magic-byte'
|
|
16
|
+
* async validate(ctx) {
|
|
17
|
+
* if (ctx.contentType !== 'application/pdf' || !ctx.readBytes) return { ok: true }
|
|
18
|
+
* const head = await ctx.readBytes(4)
|
|
19
|
+
* return head.toString('ascii') === '%PDF'
|
|
20
|
+
* ? { ok: true }
|
|
21
|
+
* : { ok: false, reason: 'Declared as PDF but missing magic bytes' }
|
|
22
|
+
* }
|
|
23
|
+
* }
|
|
24
|
+
*/
|
|
25
|
+
interface IUploadValidator {
|
|
26
|
+
/** Unique name — used in error logs. */
|
|
27
|
+
readonly name: string;
|
|
28
|
+
validate(context: {
|
|
29
|
+
key: string;
|
|
30
|
+
contentType: string;
|
|
31
|
+
size?: number;
|
|
32
|
+
metadata?: Record<string, string>;
|
|
33
|
+
/**
|
|
34
|
+
* Reads up to `maxBytes` from the body without consuming it for the actual
|
|
35
|
+
* upload. Useful for magic-byte sniffing on streams.
|
|
36
|
+
*/
|
|
37
|
+
readBytes?: (maxBytes: number) => Promise<Buffer>;
|
|
38
|
+
}): Promise<{
|
|
39
|
+
ok: true;
|
|
40
|
+
} | {
|
|
41
|
+
ok: false;
|
|
42
|
+
reason: string;
|
|
43
|
+
}>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* @fileoverview Pluggable file-scanner contract (virus, malware, content
|
|
48
|
+
* moderation) and its result shape.
|
|
49
|
+
* @layer server/interfaces
|
|
50
|
+
*/
|
|
51
|
+
/**
|
|
52
|
+
* Pluggable file scanner. Receives bytes in pre-upload mode, only metadata in
|
|
53
|
+
* post-upload mode.
|
|
54
|
+
*/
|
|
55
|
+
interface IFileScanner {
|
|
56
|
+
scan(input: {
|
|
57
|
+
/** `'pre-upload'` includes `body`; `'post-upload'` has only key/bucket/contentType. */
|
|
58
|
+
mode: 'pre-upload' | 'post-upload';
|
|
59
|
+
body?: Buffer | NodeJS.ReadableStream;
|
|
60
|
+
key: string;
|
|
61
|
+
bucket: string;
|
|
62
|
+
contentType: string;
|
|
63
|
+
size?: number;
|
|
64
|
+
}): Promise<FileScanResult>;
|
|
65
|
+
}
|
|
66
|
+
/** Outcome of a file scan. */
|
|
67
|
+
interface FileScanResult {
|
|
68
|
+
status: 'clean' | 'infected' | 'unknown';
|
|
69
|
+
/** Engine name — e.g. `'clamav-0.103'`, `'aws-macie'`. */
|
|
70
|
+
engine: string;
|
|
71
|
+
/** Threat name when `status === 'infected'`. */
|
|
72
|
+
threat?: string;
|
|
73
|
+
details?: Record<string, unknown>;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* @fileoverview Public configuration contracts for the dynamic module —
|
|
78
|
+
* synchronous options, async options, and the options factory.
|
|
79
|
+
* @layer server/interfaces
|
|
80
|
+
*/
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Synchronous configuration for `BymaxStorageModule.forRoot()`.
|
|
84
|
+
*
|
|
85
|
+
* `defaultPublicRead` applies an ACL on uploads. NOTE: ACLs fail with HTTP 400
|
|
86
|
+
* `AccessControlListNotSupported` on modern AWS S3 buckets (Object Ownership =
|
|
87
|
+
* "Bucket owner enforced") and are a no-op on Cloudflare R2 — prefer a bucket
|
|
88
|
+
* policy, a CDN, or signed URLs.
|
|
89
|
+
*/
|
|
90
|
+
interface BymaxStorageModuleOptions {
|
|
91
|
+
/** S3-compatible endpoint. REQUIRED. */
|
|
92
|
+
endpoint: string;
|
|
93
|
+
/** Region — `'auto'` for R2, any non-empty string for MinIO. REQUIRED. */
|
|
94
|
+
region: string;
|
|
95
|
+
/** Default bucket — overridable per call. REQUIRED. */
|
|
96
|
+
bucket: string;
|
|
97
|
+
/** Credentials — inject via ConfigService, never hardcode. REQUIRED. */
|
|
98
|
+
credentials: {
|
|
99
|
+
accessKeyId: string;
|
|
100
|
+
secretAccessKey: string;
|
|
101
|
+
/** STS / OIDC temporary session token. */
|
|
102
|
+
sessionToken?: string;
|
|
103
|
+
};
|
|
104
|
+
/** `false` = virtual-hosted, `true` = path-style (MinIO). Default: `false`. */
|
|
105
|
+
forcePathStyle?: boolean;
|
|
106
|
+
/** Public base URL for direct links. Fallback: endpoint + bucket. */
|
|
107
|
+
publicBaseUrl?: string;
|
|
108
|
+
/** When set, `getPublicUrl()` returns the CDN URL instead. */
|
|
109
|
+
cdnBaseUrl?: string;
|
|
110
|
+
/**
|
|
111
|
+
* Apply ACL `public-read` on uploads. Default: `false`. Fails with HTTP 400
|
|
112
|
+
* on modern AWS S3 (ACLs disabled) and is a no-op on R2 — prefer bucket
|
|
113
|
+
* policy / CDN / signed URLs.
|
|
114
|
+
*/
|
|
115
|
+
defaultPublicRead?: boolean;
|
|
116
|
+
/** Global key prefix applied to every operation — useful for multi-tenant isolation. */
|
|
117
|
+
keyPrefix?: string;
|
|
118
|
+
/** Default `Cache-Control` header on uploads. */
|
|
119
|
+
defaultCacheControl?: string;
|
|
120
|
+
/** Default `Content-Disposition`. */
|
|
121
|
+
defaultContentDisposition?: 'inline' | 'attachment';
|
|
122
|
+
signedUrls?: {
|
|
123
|
+
/** Default GET TTL (seconds). Default: `300`. */
|
|
124
|
+
defaultGetTtlSeconds?: number;
|
|
125
|
+
/** Default PUT TTL (seconds). Default: `300`. */
|
|
126
|
+
defaultPutTtlSeconds?: number;
|
|
127
|
+
/** Hard cap — higher TTLs are silently clamped. Default: `604800` (7 days). */
|
|
128
|
+
maxTtlSeconds?: number;
|
|
129
|
+
};
|
|
130
|
+
multipart?: {
|
|
131
|
+
/** Bytes threshold to switch to multipart. Default: `5242880` (5 MB). */
|
|
132
|
+
thresholdBytes?: number;
|
|
133
|
+
/** Size per part (S3 minimum: 5 MB). Default: 5 MB. */
|
|
134
|
+
partSizeBytes?: number;
|
|
135
|
+
/** Concurrent parts. Default: `4`. */
|
|
136
|
+
queueSize?: number;
|
|
137
|
+
};
|
|
138
|
+
/** Enables the validation pipeline when present. */
|
|
139
|
+
validation?: {
|
|
140
|
+
/** MIME whitelist — supports wildcards like `'image/*'`. */
|
|
141
|
+
mimeWhitelist?: readonly string[];
|
|
142
|
+
/** Max upload size in bytes. */
|
|
143
|
+
maxSizeBytes?: number;
|
|
144
|
+
/** Custom validators run in order; the first rejection short-circuits. */
|
|
145
|
+
customValidators?: readonly IUploadValidator[];
|
|
146
|
+
};
|
|
147
|
+
/** Enables the file scanner when present. */
|
|
148
|
+
scanner?: {
|
|
149
|
+
impl: IFileScanner;
|
|
150
|
+
/** `'pre-upload'` (default) scans before; `'post-upload'` scans after. */
|
|
151
|
+
mode?: 'pre-upload' | 'post-upload';
|
|
152
|
+
/** Reject when the scanner returns `'unknown'`. Default: `false`. */
|
|
153
|
+
rejectOnUnknown?: boolean;
|
|
154
|
+
};
|
|
155
|
+
/** Server-side encryption. */
|
|
156
|
+
serverSideEncryption?: 'AES256' | 'aws:kms';
|
|
157
|
+
/** Required when `serverSideEncryption === 'aws:kms'`. */
|
|
158
|
+
kmsKeyId?: string;
|
|
159
|
+
/**
|
|
160
|
+
* S3Client `requestChecksumCalculation`. AWS SDK v3 defaults to
|
|
161
|
+
* `'WHEN_SUPPORTED'` (CRC32 integrity headers); non-AWS providers (R2, B2,
|
|
162
|
+
* MinIO, Spaces) require `'WHEN_REQUIRED'`. Provider recipes set it.
|
|
163
|
+
*/
|
|
164
|
+
requestChecksumCalculation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
165
|
+
/** S3Client `responseChecksumValidation` (checksum mode on GET). Same provider caveat. */
|
|
166
|
+
responseChecksumValidation?: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
167
|
+
/** Total attempts including the first try (maps to `maxAttempts`). Default: `3`. */
|
|
168
|
+
maxAttempts?: number;
|
|
169
|
+
/** Per-request timeout. Default: `30000` ms. */
|
|
170
|
+
requestTimeoutMs?: number;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Asynchronous configuration for `BymaxStorageModule.forRootAsync()` — the
|
|
174
|
+
* standard NestJS async dynamic-module options shape.
|
|
175
|
+
*/
|
|
176
|
+
interface BymaxStorageModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
|
|
177
|
+
useFactory?: (...args: unknown[]) => BymaxStorageModuleOptions | Promise<BymaxStorageModuleOptions>;
|
|
178
|
+
inject?: readonly (string | symbol | Type<unknown>)[];
|
|
179
|
+
useExisting?: Type<BymaxStorageModuleOptionsFactory>;
|
|
180
|
+
useClass?: Type<BymaxStorageModuleOptionsFactory>;
|
|
181
|
+
}
|
|
182
|
+
/** Factory contract for `useExisting` / `useClass` async configuration. */
|
|
183
|
+
interface BymaxStorageModuleOptionsFactory {
|
|
184
|
+
createStorageOptions(): BymaxStorageModuleOptions | Promise<BymaxStorageModuleOptions>;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* @fileoverview The `@Global()` dynamic module. `forRoot()` resolves options
|
|
189
|
+
* synchronously; `forRootAsync()` resolves them from injected dependencies
|
|
190
|
+
* (`useFactory`/`useClass`/`useExisting`). Both wire the identical provider and
|
|
191
|
+
* export surface — the S3 client lifecycle, key resolver, the public facades, and
|
|
192
|
+
* the internal validation/scanner services — so the module behaves the same way
|
|
193
|
+
* regardless of how it was configured.
|
|
194
|
+
* @layer server/module
|
|
195
|
+
*/
|
|
196
|
+
|
|
197
|
+
declare class BymaxStorageModule {
|
|
198
|
+
/**
|
|
199
|
+
* Synchronous configuration. Validates and resolves the options, then returns
|
|
200
|
+
* the wired dynamic module.
|
|
201
|
+
*
|
|
202
|
+
* @param options - The storage module options.
|
|
203
|
+
* @returns The configured `DynamicModule`.
|
|
204
|
+
* @throws StorageException with code `STORAGE_INVALID_CONFIG` on invalid options.
|
|
205
|
+
*
|
|
206
|
+
* @example
|
|
207
|
+
* BymaxStorageModule.forRoot({
|
|
208
|
+
* endpoint: 'https://s3.us-east-1.amazonaws.com',
|
|
209
|
+
* region: 'us-east-1',
|
|
210
|
+
* bucket: 'my-bucket',
|
|
211
|
+
* credentials: { accessKeyId, secretAccessKey },
|
|
212
|
+
* })
|
|
213
|
+
*/
|
|
214
|
+
static forRoot(options: BymaxStorageModuleOptions): DynamicModule;
|
|
215
|
+
/**
|
|
216
|
+
* Asynchronous configuration (the canonical NestJS pattern). Resolves the
|
|
217
|
+
* options from injected dependencies via `useFactory` (+ `inject`), `useClass`,
|
|
218
|
+
* or `useExisting`, running `validateOptions` + `applyDefaults` inside the
|
|
219
|
+
* factory. Replicates every provider and export of {@link forRoot}.
|
|
220
|
+
*
|
|
221
|
+
* @param asyncOptions - The async options descriptor.
|
|
222
|
+
* @returns The configured `DynamicModule`.
|
|
223
|
+
* @throws Error when none of `useFactory`/`useClass`/`useExisting` is provided.
|
|
224
|
+
*
|
|
225
|
+
* @example
|
|
226
|
+
* BymaxStorageModule.forRootAsync({
|
|
227
|
+
* imports: [ConfigModule],
|
|
228
|
+
* inject: [ConfigService],
|
|
229
|
+
* useFactory: (config: ConfigService) => ({
|
|
230
|
+
* endpoint: config.getOrThrow('S3_ENDPOINT'),
|
|
231
|
+
* region: config.getOrThrow('S3_REGION'),
|
|
232
|
+
* bucket: config.getOrThrow('S3_BUCKET'),
|
|
233
|
+
* credentials: {
|
|
234
|
+
* accessKeyId: config.getOrThrow('S3_ACCESS_KEY_ID'),
|
|
235
|
+
* secretAccessKey: config.getOrThrow('S3_SECRET_ACCESS_KEY'),
|
|
236
|
+
* },
|
|
237
|
+
* }),
|
|
238
|
+
* })
|
|
239
|
+
*/
|
|
240
|
+
static forRootAsync(asyncOptions: BymaxStorageModuleAsyncOptions): DynamicModule;
|
|
241
|
+
/** Providers shared by both configuration paths (options-agnostic). */
|
|
242
|
+
private static buildCoreProviders;
|
|
243
|
+
/**
|
|
244
|
+
* Public DI surface: the facades, the resolved options, the raw-client token,
|
|
245
|
+
* and the user-supplied validators + scanner tokens. Internal services and the
|
|
246
|
+
* idempotency cache are intentionally not exported.
|
|
247
|
+
*/
|
|
248
|
+
private static buildExports;
|
|
249
|
+
/**
|
|
250
|
+
* Builds the options provider plus, for `useClass`, the factory-class provider
|
|
251
|
+
* that must be registered so Nest can instantiate and inject it.
|
|
252
|
+
*/
|
|
253
|
+
private static buildAsyncOptionsProviders;
|
|
254
|
+
/** Builds the `BYMAX_STORAGE_OPTIONS` provider from the async descriptor. */
|
|
255
|
+
private static createAsyncOptionsProvider;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* @fileoverview The fully-resolved options shape consumed internally by services
|
|
260
|
+
* so they never deal with `undefined` for fields that carry a default.
|
|
261
|
+
* @layer server/config
|
|
262
|
+
*/
|
|
263
|
+
|
|
264
|
+
/** Every optional field with a default is present and typed as required. */
|
|
265
|
+
interface ResolvedBymaxStorageOptions {
|
|
266
|
+
endpoint: string;
|
|
267
|
+
region: string;
|
|
268
|
+
bucket: string;
|
|
269
|
+
credentials: {
|
|
270
|
+
accessKeyId: string;
|
|
271
|
+
secretAccessKey: string;
|
|
272
|
+
sessionToken?: string;
|
|
273
|
+
};
|
|
274
|
+
forcePathStyle: boolean;
|
|
275
|
+
publicBaseUrl: string;
|
|
276
|
+
cdnBaseUrl?: string;
|
|
277
|
+
defaultPublicRead: boolean;
|
|
278
|
+
keyPrefix: string;
|
|
279
|
+
defaultCacheControl: string;
|
|
280
|
+
defaultContentDisposition: 'inline' | 'attachment';
|
|
281
|
+
signedUrls: {
|
|
282
|
+
defaultGetTtlSeconds: number;
|
|
283
|
+
defaultPutTtlSeconds: number;
|
|
284
|
+
maxTtlSeconds: number;
|
|
285
|
+
};
|
|
286
|
+
multipart: {
|
|
287
|
+
thresholdBytes: number;
|
|
288
|
+
partSizeBytes: number;
|
|
289
|
+
queueSize: number;
|
|
290
|
+
};
|
|
291
|
+
validation?: BymaxStorageModuleOptions['validation'];
|
|
292
|
+
scanner?: BymaxStorageModuleOptions['scanner'];
|
|
293
|
+
serverSideEncryption?: 'AES256' | 'aws:kms';
|
|
294
|
+
kmsKeyId?: string;
|
|
295
|
+
requestChecksumCalculation: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
296
|
+
responseChecksumValidation: 'WHEN_SUPPORTED' | 'WHEN_REQUIRED';
|
|
297
|
+
maxAttempts: number;
|
|
298
|
+
requestTimeoutMs: number;
|
|
299
|
+
/** True when both `accessKeyId` and `secretAccessKey` are non-empty. */
|
|
300
|
+
hasCredentials: boolean;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* @fileoverview Per-call options for `StorageService.upload()`.
|
|
305
|
+
* @layer server/interfaces
|
|
306
|
+
*/
|
|
307
|
+
/** Options for a single upload call. */
|
|
308
|
+
interface UploadOptions {
|
|
309
|
+
key: string;
|
|
310
|
+
/** Buffer (small/medium), Readable (large), or Uint8Array. */
|
|
311
|
+
body: Buffer | NodeJS.ReadableStream | Uint8Array;
|
|
312
|
+
contentType: string;
|
|
313
|
+
bucket?: string;
|
|
314
|
+
/** Required for validation and optimal multipart sizing. */
|
|
315
|
+
size?: number;
|
|
316
|
+
cacheControl?: string;
|
|
317
|
+
/** `'inline'`, `'attachment'`, or a full `Content-Disposition` value. */
|
|
318
|
+
contentDisposition?: string;
|
|
319
|
+
/** Default: `defaultPublicRead` from module options. */
|
|
320
|
+
publicRead?: boolean;
|
|
321
|
+
/** `'NONE'` forces no SSE even when a default is set globally. */
|
|
322
|
+
serverSideEncryption?: 'AES256' | 'aws:kms' | 'NONE';
|
|
323
|
+
kmsKeyId?: string;
|
|
324
|
+
/** Custom `x-amz-meta-*` headers. */
|
|
325
|
+
metadata?: Record<string, string>;
|
|
326
|
+
/**
|
|
327
|
+
* If the same `idempotencyKey` was seen within the cache TTL window, the
|
|
328
|
+
* cached `UploadResult` is returned without re-uploading.
|
|
329
|
+
*/
|
|
330
|
+
idempotencyKey?: string;
|
|
331
|
+
/** Progress callback fired after each multipart part (or once for single). */
|
|
332
|
+
onProgress?: (event: {
|
|
333
|
+
loaded: number;
|
|
334
|
+
total?: number;
|
|
335
|
+
part?: number;
|
|
336
|
+
}) => void;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* @fileoverview Per-call options for `StorageService.download()`.
|
|
341
|
+
* @layer server/interfaces
|
|
342
|
+
*/
|
|
343
|
+
/** Options for a single download call. */
|
|
344
|
+
interface DownloadOptions {
|
|
345
|
+
key: string;
|
|
346
|
+
bucket?: string;
|
|
347
|
+
/** S3 Range header — e.g. `'bytes=0-1023'` for partial downloads. */
|
|
348
|
+
range?: string;
|
|
349
|
+
/** Conditional GET — only return if the ETag does NOT match. */
|
|
350
|
+
ifNoneMatch?: string;
|
|
351
|
+
/** Conditional GET — only return if the ETag matches. */
|
|
352
|
+
ifMatch?: string;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
/**
|
|
356
|
+
* @fileoverview Pure data shapes returned by storage operations. Zero NestJS or
|
|
357
|
+
* AWS SDK dependencies — safe to import in frontends, edge functions, or other
|
|
358
|
+
* non-Node environments.
|
|
359
|
+
* @layer shared/types
|
|
360
|
+
*/
|
|
361
|
+
/** Outcome of an upload — returned to the caller. */
|
|
362
|
+
interface UploadResult {
|
|
363
|
+
/** Final key after normalization and the global key prefix. */
|
|
364
|
+
key: string;
|
|
365
|
+
bucket: string;
|
|
366
|
+
etag: string;
|
|
367
|
+
/** Only set on versioned buckets. */
|
|
368
|
+
versionId?: string;
|
|
369
|
+
size?: number;
|
|
370
|
+
contentType: string;
|
|
371
|
+
publicUrl: string;
|
|
372
|
+
/** True when the multipart pathway was used. */
|
|
373
|
+
multipart: boolean;
|
|
374
|
+
/** True when the result was returned from the idempotency cache. */
|
|
375
|
+
fromIdempotencyCache: boolean;
|
|
376
|
+
}
|
|
377
|
+
/** Object metadata as returned by `head()` and `download()`. */
|
|
378
|
+
interface ObjectMetadata {
|
|
379
|
+
key: string;
|
|
380
|
+
bucket: string;
|
|
381
|
+
size: number;
|
|
382
|
+
contentType: string;
|
|
383
|
+
etag: string;
|
|
384
|
+
lastModified: Date;
|
|
385
|
+
cacheControl?: string;
|
|
386
|
+
contentDisposition?: string;
|
|
387
|
+
/** `x-amz-meta-*` custom metadata. */
|
|
388
|
+
metadata: Record<string, string>;
|
|
389
|
+
/** S3 storage class (STANDARD, GLACIER, etc.). */
|
|
390
|
+
storageClass?: string;
|
|
391
|
+
versionId?: string;
|
|
392
|
+
}
|
|
393
|
+
/** Result row returned by `list()`. */
|
|
394
|
+
interface ListedObject {
|
|
395
|
+
key: string;
|
|
396
|
+
size: number;
|
|
397
|
+
etag: string;
|
|
398
|
+
lastModified: Date;
|
|
399
|
+
storageClass?: string;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* @fileoverview Per-call options and the result shape for `StorageService.list()`.
|
|
404
|
+
* @layer server/interfaces
|
|
405
|
+
*/
|
|
406
|
+
|
|
407
|
+
/** Options for a single list call. */
|
|
408
|
+
interface ListOptions {
|
|
409
|
+
/** Filter prefix (applied AFTER the global key prefix). */
|
|
410
|
+
prefix?: string;
|
|
411
|
+
bucket?: string;
|
|
412
|
+
/** Page size. Default: `1000` (S3 hard max). */
|
|
413
|
+
maxKeys?: number;
|
|
414
|
+
/** Token from a previous page. */
|
|
415
|
+
continuationToken?: string;
|
|
416
|
+
/**
|
|
417
|
+
* Delimiter for pseudo-hierarchical listing. When `'/'`, objects under
|
|
418
|
+
* sub-prefixes are aggregated into `commonPrefixes`.
|
|
419
|
+
*/
|
|
420
|
+
delimiter?: string;
|
|
421
|
+
}
|
|
422
|
+
/** Result of a single list call. */
|
|
423
|
+
interface ListResult {
|
|
424
|
+
objects: ListedObject[];
|
|
425
|
+
commonPrefixes: string[];
|
|
426
|
+
isTruncated: boolean;
|
|
427
|
+
nextContinuationToken?: string;
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
/**
|
|
431
|
+
* @fileoverview Per-call options for `StorageService.copy()`.
|
|
432
|
+
* @layer server/interfaces
|
|
433
|
+
*/
|
|
434
|
+
/** Options for a server-side object copy. */
|
|
435
|
+
interface CopyOptions {
|
|
436
|
+
sourceKey: string;
|
|
437
|
+
destinationKey: string;
|
|
438
|
+
sourceBucket?: string;
|
|
439
|
+
destinationBucket?: string;
|
|
440
|
+
publicRead?: boolean;
|
|
441
|
+
cacheControl?: string;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* @fileoverview Per-call options and the result shape for
|
|
446
|
+
* `StorageService.deleteMany()`.
|
|
447
|
+
* @layer server/interfaces
|
|
448
|
+
*/
|
|
449
|
+
/** Per-call options for a batch delete. */
|
|
450
|
+
interface DeleteManyOptions {
|
|
451
|
+
bucket?: string;
|
|
452
|
+
}
|
|
453
|
+
/** A single failed key from a batch delete, with a readable provider error. */
|
|
454
|
+
interface FailedDeletion {
|
|
455
|
+
key: string;
|
|
456
|
+
error: string;
|
|
457
|
+
}
|
|
458
|
+
/** Aggregated outcome of a batch delete: succeeded keys and per-key failures. */
|
|
459
|
+
interface DeleteManyResult {
|
|
460
|
+
deleted: string[];
|
|
461
|
+
failed: FailedDeletion[];
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/**
|
|
465
|
+
* @fileoverview Owns the singleton `S3Client`. Builds it lazily (skipped when
|
|
466
|
+
* credentials are absent so the module still registers), serves it through
|
|
467
|
+
* `getClient()` / `getClientOrNull()`, and releases TCP connections via
|
|
468
|
+
* `destroy()` on application shutdown.
|
|
469
|
+
* @layer server/providers
|
|
470
|
+
*/
|
|
471
|
+
|
|
472
|
+
/**
|
|
473
|
+
* When credentials are missing the module registers but never instantiates a
|
|
474
|
+
* client; operations then fail with `STORAGE_NOT_CONFIGURED`. This keeps dev
|
|
475
|
+
* workflows running without storage credentials in the environment.
|
|
476
|
+
*/
|
|
477
|
+
declare class S3ClientProvider implements OnModuleInit, OnApplicationShutdown {
|
|
478
|
+
private readonly options;
|
|
479
|
+
private readonly logger;
|
|
480
|
+
private client;
|
|
481
|
+
constructor(options: ResolvedBymaxStorageOptions);
|
|
482
|
+
onModuleInit(): void;
|
|
483
|
+
onApplicationShutdown(): void;
|
|
484
|
+
/**
|
|
485
|
+
* Returns the live client, building it on first use, or `null` when storage is
|
|
486
|
+
* not configured. Used by the public raw-client token so its value does not
|
|
487
|
+
* depend on lifecycle-hook ordering.
|
|
488
|
+
*
|
|
489
|
+
* @returns The singleton client, or `null` when no credentials are configured.
|
|
490
|
+
*/
|
|
491
|
+
getClientOrNull(): S3Client | null;
|
|
492
|
+
/**
|
|
493
|
+
* Returns the singleton client. Throws when storage is not configured — call
|
|
494
|
+
* `isConfigured()` first and surface a typed `STORAGE_NOT_CONFIGURED`.
|
|
495
|
+
*
|
|
496
|
+
* @returns The singleton `S3Client`.
|
|
497
|
+
* @throws Error when storage is not configured.
|
|
498
|
+
*/
|
|
499
|
+
getClient(): S3Client;
|
|
500
|
+
/**
|
|
501
|
+
* Reports whether the singleton client has been built.
|
|
502
|
+
*
|
|
503
|
+
* @returns `true` once the client exists, `false` otherwise.
|
|
504
|
+
*/
|
|
505
|
+
isConfigured(): boolean;
|
|
506
|
+
private resolveClient;
|
|
507
|
+
private createClient;
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
declare class KeyResolverService {
|
|
511
|
+
private readonly keyPrefix;
|
|
512
|
+
constructor(options: ResolvedBymaxStorageOptions);
|
|
513
|
+
/**
|
|
514
|
+
* Normalizes a raw key into the final S3 object key. Rejects empty keys, null
|
|
515
|
+
* bytes, a leading `/`, and any `..` path segment; collapses duplicate slashes;
|
|
516
|
+
* prepends the configured prefix.
|
|
517
|
+
*
|
|
518
|
+
* @param rawKey - The caller-provided key, already URL-decoded by the caller.
|
|
519
|
+
* @returns The prefixed, normalized object key.
|
|
520
|
+
* @throws StorageException with code `STORAGE_KEY_INVALID`.
|
|
521
|
+
*/
|
|
522
|
+
normalize(rawKey: string): string;
|
|
523
|
+
/**
|
|
524
|
+
* Strips the global key prefix from a key — useful when returning keys to the
|
|
525
|
+
* consumer so they need not know the prefix exists.
|
|
526
|
+
*
|
|
527
|
+
* @param fullKey - A normalized key that may carry the global prefix.
|
|
528
|
+
* @returns The key without the configured prefix.
|
|
529
|
+
*/
|
|
530
|
+
stripPrefix(fullKey: string): string;
|
|
531
|
+
/**
|
|
532
|
+
* Read-only accessor for the resolved prefix.
|
|
533
|
+
*
|
|
534
|
+
* @returns The normalized prefix (empty string when none is configured).
|
|
535
|
+
*/
|
|
536
|
+
getPrefix(): string;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
/**
|
|
540
|
+
* @fileoverview Helpers for the polymorphic upload body (`Buffer`,
|
|
541
|
+
* `NodeJS.ReadableStream`, or `Uint8Array`): type guards, best-effort sizing,
|
|
542
|
+
* a non-consuming first-bytes peek for content validators, and a buffer-to-
|
|
543
|
+
* stream adapter. Hand-rolled with `node:stream` to keep zero runtime deps.
|
|
544
|
+
* @layer server/utils
|
|
545
|
+
*/
|
|
546
|
+
|
|
547
|
+
/** Every shape accepted as an upload body. */
|
|
548
|
+
type UploadBody = Buffer | NodeJS.ReadableStream | Uint8Array;
|
|
549
|
+
|
|
550
|
+
/** Minimal subset of upload options consumed by the validation pipeline. */
|
|
551
|
+
interface ValidationInput {
|
|
552
|
+
key: string;
|
|
553
|
+
body: UploadBody;
|
|
554
|
+
contentType: string;
|
|
555
|
+
size?: number;
|
|
556
|
+
metadata?: Record<string, string>;
|
|
557
|
+
}
|
|
558
|
+
declare class ValidationService {
|
|
559
|
+
private readonly options;
|
|
560
|
+
private readonly validators;
|
|
561
|
+
constructor(options: ResolvedBymaxStorageOptions, validators: readonly IUploadValidator[]);
|
|
562
|
+
/**
|
|
563
|
+
* Runs the upload validation pipeline in the canonical order:
|
|
564
|
+
* 1. MIME whitelist (when configured)
|
|
565
|
+
* 2. Size check (best-effort — skipped when `size` is absent)
|
|
566
|
+
* 3. Custom `IUploadValidator` chain (first rejection short-circuits)
|
|
567
|
+
*
|
|
568
|
+
* @param input - The upload options subset used for validation.
|
|
569
|
+
* @returns The validated body (possibly replaced via a tee'd stream).
|
|
570
|
+
* @throws StorageException `STORAGE_MIME_NOT_ALLOWED` on a MIME violation.
|
|
571
|
+
* @throws StorageException `STORAGE_SIZE_EXCEEDED` when `size > maxSizeBytes`.
|
|
572
|
+
* @throws StorageException `STORAGE_VALIDATION_FAILED` on a custom validator rejection.
|
|
573
|
+
*/
|
|
574
|
+
validate(input: ValidationInput): Promise<{
|
|
575
|
+
body: UploadBody;
|
|
576
|
+
}>;
|
|
577
|
+
/** Checks the MIME against the configured whitelist (no-op when absent or empty). */
|
|
578
|
+
private checkMime;
|
|
579
|
+
/** Best-effort size check — skipped when size is undefined. */
|
|
580
|
+
private checkSize;
|
|
581
|
+
/**
|
|
582
|
+
* Runs the custom validator chain. When a validator calls `readBytes`, the
|
|
583
|
+
* body is tee'd and the replacement stream is propagated to subsequent
|
|
584
|
+
* validators and the final upload.
|
|
585
|
+
*/
|
|
586
|
+
private runCustomValidators;
|
|
587
|
+
}
|
|
588
|
+
|
|
589
|
+
/** Input shape for a scan request. */
|
|
590
|
+
interface ScanInput {
|
|
591
|
+
mode: 'pre-upload' | 'post-upload';
|
|
592
|
+
body?: Buffer | NodeJS.ReadableStream;
|
|
593
|
+
key: string;
|
|
594
|
+
bucket: string;
|
|
595
|
+
contentType: string;
|
|
596
|
+
size?: number;
|
|
597
|
+
}
|
|
598
|
+
declare class FileScannerService {
|
|
599
|
+
private readonly options;
|
|
600
|
+
private readonly scanner;
|
|
601
|
+
private readonly logger;
|
|
602
|
+
constructor(options: ResolvedBymaxStorageOptions, scanner: IFileScanner | null);
|
|
603
|
+
/**
|
|
604
|
+
* Returns `true` when both a scanner implementation and scanner options are
|
|
605
|
+
* configured.
|
|
606
|
+
*
|
|
607
|
+
* @returns `true` when scanning is active.
|
|
608
|
+
*/
|
|
609
|
+
isEnabled(): boolean;
|
|
610
|
+
/**
|
|
611
|
+
* Returns the configured scan mode, or `null` when scanning is disabled.
|
|
612
|
+
*
|
|
613
|
+
* @returns `'pre-upload'`, `'post-upload'`, or `null`.
|
|
614
|
+
*/
|
|
615
|
+
getMode(): 'pre-upload' | 'post-upload' | null;
|
|
616
|
+
/**
|
|
617
|
+
* Scans the given input. Callers MUST guard with `isEnabled()` — calling this
|
|
618
|
+
* method without a configured scanner is a programming error and throws a
|
|
619
|
+
* plain `Error`.
|
|
620
|
+
*
|
|
621
|
+
* Infected results throw `STORAGE_SCAN_INFECTED`. Inconclusive results throw
|
|
622
|
+
* `STORAGE_SCAN_INCONCLUSIVE` when `rejectOnUnknown` is set; otherwise they
|
|
623
|
+
* are returned with a warning log.
|
|
624
|
+
*
|
|
625
|
+
* @param input - The scan input.
|
|
626
|
+
* @returns The scan result when `status` is `'clean'` or `'unknown'` (non-rejecting).
|
|
627
|
+
* @throws Error when called without a configured scanner.
|
|
628
|
+
* @throws StorageException `STORAGE_SCAN_INFECTED` on an infected result.
|
|
629
|
+
* @throws StorageException `STORAGE_SCAN_INCONCLUSIVE` on an unknown result with `rejectOnUnknown`.
|
|
630
|
+
*/
|
|
631
|
+
scan(input: ScanInput): Promise<FileScanResult>;
|
|
632
|
+
}
|
|
633
|
+
|
|
634
|
+
/**
|
|
635
|
+
* In-memory LRU cache for idempotent upload deduplication.
|
|
636
|
+
*
|
|
637
|
+
* A `Map` preserves insertion order, which is the basis of the LRU: a hit
|
|
638
|
+
* deletes-and-reinserts the entry (moving it to the newest position) and
|
|
639
|
+
* eviction removes the oldest insertion (the first key in iteration order).
|
|
640
|
+
*
|
|
641
|
+
* Trade-off: the cache is per-instance. In multi-replica deployments two pods
|
|
642
|
+
* may double-upload the same idempotency key within the TTL window because they
|
|
643
|
+
* do not share state. A cross-instance store is intentionally out of scope for
|
|
644
|
+
* this version.
|
|
645
|
+
*/
|
|
646
|
+
declare class IdempotencyCache {
|
|
647
|
+
private readonly maxEntries;
|
|
648
|
+
private readonly ttlMs;
|
|
649
|
+
private readonly now;
|
|
650
|
+
private readonly entries;
|
|
651
|
+
/**
|
|
652
|
+
* @param maxEntries - Hard cap; the oldest entries are evicted beyond it.
|
|
653
|
+
* @param ttlMs - Lifetime of each entry in milliseconds.
|
|
654
|
+
* @param now - Injectable clock for deterministic tests; defaults to `Date.now`.
|
|
655
|
+
*/
|
|
656
|
+
constructor(maxEntries: number, ttlMs: number, now?: () => number);
|
|
657
|
+
/**
|
|
658
|
+
* Derives a deterministic cache key by hashing the idempotency key together
|
|
659
|
+
* with the final object key. Hashing avoids storing the raw idempotency key as
|
|
660
|
+
* a `Map` key, where it could be inspected during debugging.
|
|
661
|
+
*
|
|
662
|
+
* The two components are hashed through a structured JSON encoding so their
|
|
663
|
+
* boundary is unambiguous: without it, pairs such as `('a', 'b:c')` and
|
|
664
|
+
* `('a:b', 'c')` would flatten to the same preimage and collide.
|
|
665
|
+
*
|
|
666
|
+
* @param idempotencyKey - The caller-provided idempotency key.
|
|
667
|
+
* @param finalKey - The normalized, prefixed object key.
|
|
668
|
+
* @returns A hex-encoded sha256 digest.
|
|
669
|
+
*/
|
|
670
|
+
computeKey(idempotencyKey: string, finalKey: string): string;
|
|
671
|
+
/**
|
|
672
|
+
* Looks up a cached result. Expired entries are dropped and reported as a miss.
|
|
673
|
+
* A live hit is touched (moved to the newest position) to preserve LRU order.
|
|
674
|
+
*
|
|
675
|
+
* @param cacheKey - The key returned by {@link computeKey}.
|
|
676
|
+
* @returns The cached result, or `undefined` on a miss or expiry.
|
|
677
|
+
*/
|
|
678
|
+
get(cacheKey: string): UploadResult | undefined;
|
|
679
|
+
/**
|
|
680
|
+
* Stores a result under `cacheKey`, refreshing its position, then evicts the
|
|
681
|
+
* oldest entries while the cache is over capacity.
|
|
682
|
+
*
|
|
683
|
+
* @param cacheKey - The key returned by {@link computeKey}.
|
|
684
|
+
* @param value - The upload result to cache.
|
|
685
|
+
*/
|
|
686
|
+
set(cacheKey: string, value: UploadResult): void;
|
|
687
|
+
/**
|
|
688
|
+
* Reports the current number of cached entries.
|
|
689
|
+
*
|
|
690
|
+
* @returns The entry count.
|
|
691
|
+
*/
|
|
692
|
+
size(): number;
|
|
693
|
+
/** Removes every cached entry. */
|
|
694
|
+
clear(): void;
|
|
695
|
+
}
|
|
696
|
+
|
|
697
|
+
/** Per-call options that only need to override the target bucket. */
|
|
698
|
+
interface BucketScopedOptions {
|
|
699
|
+
bucket?: string;
|
|
700
|
+
}
|
|
701
|
+
declare class StorageService {
|
|
702
|
+
private readonly options;
|
|
703
|
+
private readonly s3Provider;
|
|
704
|
+
private readonly keyResolver;
|
|
705
|
+
private readonly idempotencyCache;
|
|
706
|
+
private readonly validation;
|
|
707
|
+
private readonly scanner;
|
|
708
|
+
private readonly logger;
|
|
709
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService, idempotencyCache: IdempotencyCache, validation: ValidationService, scanner: FileScannerService);
|
|
710
|
+
/**
|
|
711
|
+
* Uploads an object, choosing single-shot or multipart automatically. When an
|
|
712
|
+
* `idempotencyKey` is supplied and a matching result is cached within the TTL
|
|
713
|
+
* window, the cached result is returned without re-uploading.
|
|
714
|
+
*
|
|
715
|
+
* @param options - The upload request.
|
|
716
|
+
* @returns The upload result.
|
|
717
|
+
* @throws StorageException for missing configuration, body, or content type.
|
|
718
|
+
*/
|
|
719
|
+
upload(options: UploadOptions): Promise<UploadResult>;
|
|
720
|
+
/** Runs a pre-upload scan when configured; throws on infected. */
|
|
721
|
+
private runPreUploadScan;
|
|
722
|
+
/**
|
|
723
|
+
* Coerces a buffer-like scan body (`Buffer` or `Uint8Array`) to a `Buffer` so
|
|
724
|
+
* the scanner always receives its declared contract type; streams pass through
|
|
725
|
+
* unchanged.
|
|
726
|
+
*/
|
|
727
|
+
private normalizeScanBody;
|
|
728
|
+
/**
|
|
729
|
+
* Runs a post-upload scan. On infection, deletes the just-uploaded object
|
|
730
|
+
* (logging delete failures as errors) and re-throws the scan exception.
|
|
731
|
+
*/
|
|
732
|
+
private runPostUploadScan;
|
|
733
|
+
/**
|
|
734
|
+
* Returns metadata for an object without downloading its body.
|
|
735
|
+
*
|
|
736
|
+
* @param key - The raw object key (normalized internally).
|
|
737
|
+
* @param options - Optional per-call bucket override.
|
|
738
|
+
* @returns The object metadata.
|
|
739
|
+
* @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the key is absent.
|
|
740
|
+
*/
|
|
741
|
+
head(key: string, options?: BucketScopedOptions): Promise<ObjectMetadata>;
|
|
742
|
+
/**
|
|
743
|
+
* Best-effort existence check. Returns `false` for a missing object and, to
|
|
744
|
+
* stay non-throwing, also `false` (with a warning) for any other error.
|
|
745
|
+
*
|
|
746
|
+
* @param key - The raw object key.
|
|
747
|
+
* @param options - Optional per-call bucket override.
|
|
748
|
+
* @returns `true` when the object exists, `false` otherwise.
|
|
749
|
+
*/
|
|
750
|
+
exists(key: string, options?: BucketScopedOptions): Promise<boolean>;
|
|
751
|
+
/**
|
|
752
|
+
* Builds the public URL for an object. Not validated against the bucket policy
|
|
753
|
+
* — public delivery depends on the bucket allowing anonymous reads or a CDN.
|
|
754
|
+
*
|
|
755
|
+
* @param key - The raw object key.
|
|
756
|
+
* @param options - Optional per-call bucket override.
|
|
757
|
+
* @returns The public URL.
|
|
758
|
+
*/
|
|
759
|
+
getPublicUrl(key: string, options?: BucketScopedOptions): string;
|
|
760
|
+
/**
|
|
761
|
+
* Streams an object. The returned `stream` is a Node `Readable` consumable via
|
|
762
|
+
* `for await` or `.pipe()`. `range` / `ifNoneMatch` / `ifMatch` are forwarded as
|
|
763
|
+
* conditional/partial GET headers.
|
|
764
|
+
*
|
|
765
|
+
* @param options - The download request.
|
|
766
|
+
* @returns The object stream and its metadata.
|
|
767
|
+
* @throws StorageException `STORAGE_OBJECT_NOT_FOUND` when the body is absent.
|
|
768
|
+
*/
|
|
769
|
+
download(options: DownloadOptions): Promise<{
|
|
770
|
+
stream: NodeJS.ReadableStream;
|
|
771
|
+
metadata: ObjectMetadata;
|
|
772
|
+
}>;
|
|
773
|
+
/**
|
|
774
|
+
* Materializes an object fully into memory via the sdk-stream-mixin. NOT
|
|
775
|
+
* recommended for files larger than 10 MB — use {@link download} for those.
|
|
776
|
+
*
|
|
777
|
+
* @param options - The download request.
|
|
778
|
+
* @returns The object buffer and its metadata.
|
|
779
|
+
*/
|
|
780
|
+
downloadBuffer(options: DownloadOptions): Promise<{
|
|
781
|
+
buffer: Buffer;
|
|
782
|
+
metadata: ObjectMetadata;
|
|
783
|
+
}>;
|
|
784
|
+
/**
|
|
785
|
+
* Deletes an object. Idempotent: a missing object is a no-op (logged as a
|
|
786
|
+
* warning), not an error. Any other failure is propagated.
|
|
787
|
+
*
|
|
788
|
+
* @param key - The raw object key.
|
|
789
|
+
* @param options - Optional per-call bucket override.
|
|
790
|
+
*/
|
|
791
|
+
delete(key: string, options?: BucketScopedOptions): Promise<void>;
|
|
792
|
+
/** Throws when the S3 client was never built (missing credentials). */
|
|
793
|
+
private assertConfigured;
|
|
794
|
+
/** Resolves the target bucket from a per-call override or the module default. */
|
|
795
|
+
private resolveBucket;
|
|
796
|
+
/** Builds a public URL, avoiding a duplicated bucket segment in the base. */
|
|
797
|
+
private buildPublicUrl;
|
|
798
|
+
/**
|
|
799
|
+
* Reports whether the base URL already carries the bucket as a real segment —
|
|
800
|
+
* the leading host label (virtual-hosted-style `bucket.host`) or a path segment
|
|
801
|
+
* (path-style `/bucket` or `/bucket/…`) — rather than an incidental substring,
|
|
802
|
+
* so `bucket="test"` is not matched by a `latest` elsewhere in the base.
|
|
803
|
+
*/
|
|
804
|
+
private baseCarriesBucket;
|
|
805
|
+
/** Maps an S3 metadata response onto the public `ObjectMetadata` shape. */
|
|
806
|
+
private toObjectMetadata;
|
|
807
|
+
/** Single `PutObject` upload for bodies below the multipart threshold. */
|
|
808
|
+
private uploadSingleShot;
|
|
809
|
+
/**
|
|
810
|
+
* Multipart upload via `@aws-sdk/lib-storage`. `leavePartsOnError: false` makes
|
|
811
|
+
* the SDK abort and clean up parts on failure, so no manual abort is issued.
|
|
812
|
+
*/
|
|
813
|
+
private uploadMultipart;
|
|
814
|
+
/** Converts a `Uint8Array` body to a `Buffer` for SDK safety; passes others through. */
|
|
815
|
+
private normalizeSingleShotBody;
|
|
816
|
+
/** Assembles an `UploadResult`, omitting optional fields that are absent. */
|
|
817
|
+
private buildUploadResult;
|
|
818
|
+
/** Emits a progress event, omitting `total`/`part` when they are unknown. */
|
|
819
|
+
private emitProgress;
|
|
820
|
+
/**
|
|
821
|
+
* Lists objects in the bucket as a single page. Applies the global key prefix
|
|
822
|
+
* to the caller's `prefix`, caps `maxKeys` at the S3 hard limit of 1000, threads
|
|
823
|
+
* the continuation token, and strips the global prefix from every returned key.
|
|
824
|
+
*
|
|
825
|
+
* @param options - The listing request.
|
|
826
|
+
* @returns One page of objects plus `commonPrefixes`, truncation, and the next token.
|
|
827
|
+
* @throws StorageException mapped from any AWS failure.
|
|
828
|
+
*/
|
|
829
|
+
list(options: ListOptions): Promise<ListResult>;
|
|
830
|
+
/** Maps a `ListObjectsV2` response onto the public `ListResult` shape. */
|
|
831
|
+
private toListResult;
|
|
832
|
+
/** Maps one `Contents` entry onto `ListedObject`, stripping the global prefix. */
|
|
833
|
+
private toListedObject;
|
|
834
|
+
/**
|
|
835
|
+
* Server-side copy of an object (no bytes flow through the app). Supports both
|
|
836
|
+
* same-bucket and cross-bucket copies and preserves the source metadata.
|
|
837
|
+
*
|
|
838
|
+
* @param options - Source/destination keys and buckets plus copy overrides.
|
|
839
|
+
* @returns The new object's ETag.
|
|
840
|
+
* @throws StorageException mapped from any AWS failure.
|
|
841
|
+
*/
|
|
842
|
+
copy(options: CopyOptions): Promise<{
|
|
843
|
+
etag: string;
|
|
844
|
+
}>;
|
|
845
|
+
/**
|
|
846
|
+
* Deletes many objects, chunking the input at the S3 hard limit of 1000 keys
|
|
847
|
+
* per request. Reports both successes and per-key failures; a whole-chunk send
|
|
848
|
+
* failure marks every key in that chunk as failed. Returned keys are stripped of
|
|
849
|
+
* the global prefix.
|
|
850
|
+
*
|
|
851
|
+
* @param keys - The raw object keys to delete.
|
|
852
|
+
* @param options - Optional per-call bucket override.
|
|
853
|
+
* @returns The deleted keys and the per-key failures.
|
|
854
|
+
*/
|
|
855
|
+
deleteMany(keys: string[], options?: DeleteManyOptions): Promise<DeleteManyResult>;
|
|
856
|
+
/** Deletes one chunk (≤ 1000 keys); a whole-chunk failure fails every key. */
|
|
857
|
+
private deleteChunk;
|
|
858
|
+
}
|
|
859
|
+
|
|
860
|
+
/**
|
|
861
|
+
* @fileoverview Per-call options and results for the signed-URL operations
|
|
862
|
+
* (GET, PUT, and multipart).
|
|
863
|
+
* @layer server/interfaces
|
|
864
|
+
*/
|
|
865
|
+
/** Options for a signed GET URL. */
|
|
866
|
+
interface SignedGetUrlOptions {
|
|
867
|
+
key: string;
|
|
868
|
+
bucket?: string;
|
|
869
|
+
/** Silently clamped to `signedUrls.maxTtlSeconds`. */
|
|
870
|
+
ttlSeconds?: number;
|
|
871
|
+
/** e.g. `'attachment; filename="invoice.pdf"'` — overrides on download. */
|
|
872
|
+
responseContentDisposition?: string;
|
|
873
|
+
responseContentType?: string;
|
|
874
|
+
}
|
|
875
|
+
/** Options for a signed PUT URL. */
|
|
876
|
+
interface SignedPutUrlOptions {
|
|
877
|
+
key: string;
|
|
878
|
+
bucket?: string;
|
|
879
|
+
/** Content-Type the client MUST send (it becomes part of the signature). */
|
|
880
|
+
contentType: string;
|
|
881
|
+
ttlSeconds?: number;
|
|
882
|
+
/**
|
|
883
|
+
* Advisory maximum upload size. NOT enforced at presign time — a SigV4 PUT
|
|
884
|
+
* signature can only pin an exact `Content-Length`, never a maximum, so the
|
|
885
|
+
* library does not bind it. Enforce it post-upload via a HEAD/size check plus
|
|
886
|
+
* the scanner path.
|
|
887
|
+
*/
|
|
888
|
+
maxSizeBytes?: number;
|
|
889
|
+
publicRead?: boolean;
|
|
890
|
+
metadata?: Record<string, string>;
|
|
891
|
+
}
|
|
892
|
+
/** Options for presigning a multipart upload. */
|
|
893
|
+
interface MultipartUploadUrlsOptions {
|
|
894
|
+
key: string;
|
|
895
|
+
bucket?: string;
|
|
896
|
+
contentType: string;
|
|
897
|
+
/** Number of parts to presign. */
|
|
898
|
+
parts: number;
|
|
899
|
+
ttlSeconds?: number;
|
|
900
|
+
}
|
|
901
|
+
/** Result of presigning a multipart upload. */
|
|
902
|
+
interface MultipartUploadUrlsResult {
|
|
903
|
+
uploadId: string;
|
|
904
|
+
partUrls: {
|
|
905
|
+
partNumber: number;
|
|
906
|
+
url: string;
|
|
907
|
+
}[];
|
|
908
|
+
completeUrl: string;
|
|
909
|
+
}
|
|
910
|
+
|
|
911
|
+
/**
|
|
912
|
+
* @fileoverview Result shape of a signed-URL request. Zero NestJS or AWS SDK
|
|
913
|
+
* dependencies.
|
|
914
|
+
* @layer shared/types
|
|
915
|
+
*/
|
|
916
|
+
/** Result of a signed URL request — the caller forwards `url` to a client. */
|
|
917
|
+
interface SignedUrlResult {
|
|
918
|
+
/** The presigned URL. NEVER LOG this — it is a temporary credential. */
|
|
919
|
+
url: string;
|
|
920
|
+
/** Absolute deadline after which the provider stops accepting the URL. */
|
|
921
|
+
expiresAt: Date;
|
|
922
|
+
/** HTTP method the client must use. */
|
|
923
|
+
method: 'GET' | 'PUT';
|
|
924
|
+
/**
|
|
925
|
+
* Headers the client MUST include verbatim — they are part of the signature.
|
|
926
|
+
* Example: `{ 'Content-Type': 'image/png' }`.
|
|
927
|
+
*/
|
|
928
|
+
requiredHeaders: Record<string, string>;
|
|
929
|
+
}
|
|
930
|
+
|
|
931
|
+
declare class SignedUrlService {
|
|
932
|
+
private readonly options;
|
|
933
|
+
private readonly s3Provider;
|
|
934
|
+
private readonly keyResolver;
|
|
935
|
+
constructor(options: ResolvedBymaxStorageOptions, s3Provider: S3ClientProvider, keyResolver: KeyResolverService);
|
|
936
|
+
/**
|
|
937
|
+
* Issues a presigned GET URL for downloading an object.
|
|
938
|
+
*
|
|
939
|
+
* SECURITY: The returned URL is a temporary credential. NEVER log it, store it
|
|
940
|
+
* in a database, or cache it across users. Issue a fresh URL per request.
|
|
941
|
+
*
|
|
942
|
+
* @param options - The download URL options.
|
|
943
|
+
* @returns The presigned URL and its expiry metadata.
|
|
944
|
+
* @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
|
|
945
|
+
* @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
|
|
946
|
+
*/
|
|
947
|
+
getDownloadUrl(options: SignedGetUrlOptions): Promise<SignedUrlResult>;
|
|
948
|
+
/**
|
|
949
|
+
* Issues a presigned PUT URL for uploading an object. The client MUST send
|
|
950
|
+
* every header listed in `requiredHeaders` verbatim — each one is part of the
|
|
951
|
+
* URL signature, so an omitted header yields `SignatureDoesNotMatch`. The map
|
|
952
|
+
* always carries `Content-Type` and additionally lists `x-amz-acl` when an ACL
|
|
953
|
+
* is signed and an `x-amz-meta-<key>` entry per metadata pair.
|
|
954
|
+
*
|
|
955
|
+
* SECURITY: The returned URL is a temporary credential — NEVER log it. A signed
|
|
956
|
+
* PUT bypasses the server-side MIME/size validation pipeline. Size limits are
|
|
957
|
+
* NOT enforced at presign time: a SigV4 PUT signature can only pin an exact
|
|
958
|
+
* `Content-Length`, never a maximum, so binding one would reject valid smaller
|
|
959
|
+
* uploads. Enforce size after the fact via a post-upload HEAD/size check plus
|
|
960
|
+
* the post-upload scanner path for defence-in-depth.
|
|
961
|
+
*
|
|
962
|
+
* ACL caveat: `publicRead` emits `ACL: public-read`, which returns HTTP 400
|
|
963
|
+
* `AccessControlListNotSupported` on modern AWS S3 buckets (Object Ownership
|
|
964
|
+
* = "Bucket owner enforced") and is a no-op on Cloudflare R2. Prefer a bucket
|
|
965
|
+
* policy, CDN, or signed GET URL for public delivery.
|
|
966
|
+
*
|
|
967
|
+
* @param options - The upload URL options.
|
|
968
|
+
* @returns The presigned URL, its expiry metadata, and required headers.
|
|
969
|
+
* @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
|
|
970
|
+
* @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
|
|
971
|
+
*/
|
|
972
|
+
getUploadUrl(options: SignedPutUrlOptions): Promise<SignedUrlResult>;
|
|
973
|
+
/**
|
|
974
|
+
* Builds the set of headers a client MUST send for a signed PUT, mirroring the
|
|
975
|
+
* headers folded into the SigV4 signature. Always includes `Content-Type`; adds
|
|
976
|
+
* `x-amz-acl` when an ACL is signed and an `x-amz-meta-<key>` entry (key
|
|
977
|
+
* lowercased to match SigV4 canonicalisation) for every metadata pair.
|
|
978
|
+
*/
|
|
979
|
+
private buildPutRequiredHeaders;
|
|
980
|
+
/**
|
|
981
|
+
* Presigns a multipart upload: creates the upload session on S3, then returns
|
|
982
|
+
* N presigned `UploadPart` URLs (1-indexed) and a presigned `CompleteMultipart`
|
|
983
|
+
* URL. The client uploads parts directly to S3 and then calls the complete URL.
|
|
984
|
+
*
|
|
985
|
+
* SECURITY: All returned URLs are temporary credentials — NEVER log them.
|
|
986
|
+
*
|
|
987
|
+
* @param options - The multipart URL options.
|
|
988
|
+
* @returns `uploadId`, `partUrls`, and `completeUrl`.
|
|
989
|
+
* @throws StorageException `STORAGE_NOT_CONFIGURED` when the client is absent.
|
|
990
|
+
* @throws StorageException `STORAGE_SIGNED_URL_TTL_INVALID` for non-positive TTL.
|
|
991
|
+
* @throws StorageException `STORAGE_PROVIDER_ERROR` when no `UploadId` is returned.
|
|
992
|
+
*/
|
|
993
|
+
getMultipartUploadUrls(options: MultipartUploadUrlsOptions): Promise<MultipartUploadUrlsResult>;
|
|
994
|
+
/** Presigns all part URLs and the complete URL in parallel. */
|
|
995
|
+
private presignMultipartParts;
|
|
996
|
+
/** Throws when the S3 client was never built (missing credentials). */
|
|
997
|
+
private assertConfigured;
|
|
998
|
+
/** Resolves the target bucket from a per-call override or the module default. */
|
|
999
|
+
private resolveBucket;
|
|
1000
|
+
}
|
|
1001
|
+
|
|
1002
|
+
/**
|
|
1003
|
+
* @fileoverview No-operation upload validator — always passes. Use as the
|
|
1004
|
+
* default when no custom validation logic is needed.
|
|
1005
|
+
* @layer server/providers
|
|
1006
|
+
*/
|
|
1007
|
+
|
|
1008
|
+
/**
|
|
1009
|
+
* No-operation upload validator that unconditionally allows every upload.
|
|
1010
|
+
* Useful as a default injectable when the host application does not need
|
|
1011
|
+
* custom validation logic.
|
|
1012
|
+
*
|
|
1013
|
+
* @example
|
|
1014
|
+
* BymaxStorageModule.forRoot({
|
|
1015
|
+
* ...options,
|
|
1016
|
+
* validation: { customValidators: [new NoOpUploadValidator()] },
|
|
1017
|
+
* })
|
|
1018
|
+
*/
|
|
1019
|
+
declare class NoOpUploadValidator implements IUploadValidator {
|
|
1020
|
+
/** Identifies this validator in validation-failed error details. */
|
|
1021
|
+
readonly name = "no-op";
|
|
1022
|
+
/**
|
|
1023
|
+
* Always returns `{ ok: true }` — no validation is performed.
|
|
1024
|
+
*
|
|
1025
|
+
* @param _ctx - The upload context (ignored).
|
|
1026
|
+
* @returns A passing validation result.
|
|
1027
|
+
*/
|
|
1028
|
+
validate(_ctx: Parameters<IUploadValidator['validate']>[0]): Promise<{
|
|
1029
|
+
ok: true;
|
|
1030
|
+
}>;
|
|
1031
|
+
}
|
|
1032
|
+
|
|
1033
|
+
/**
|
|
1034
|
+
* @fileoverview No-operation file scanner — always reports clean. Use as the
|
|
1035
|
+
* default when no scanner implementation is plugged in.
|
|
1036
|
+
* @layer server/providers
|
|
1037
|
+
*/
|
|
1038
|
+
|
|
1039
|
+
/**
|
|
1040
|
+
* No-operation file scanner that unconditionally returns a clean result.
|
|
1041
|
+
* Useful as a default injectable when the host application does not need
|
|
1042
|
+
* virus or content-moderation scanning.
|
|
1043
|
+
*
|
|
1044
|
+
* @example
|
|
1045
|
+
* BymaxStorageModule.forRoot({
|
|
1046
|
+
* ...options,
|
|
1047
|
+
* scanner: { impl: new NoOpFileScanner() },
|
|
1048
|
+
* })
|
|
1049
|
+
*/
|
|
1050
|
+
declare class NoOpFileScanner implements IFileScanner {
|
|
1051
|
+
/**
|
|
1052
|
+
* Always returns `{ status: 'clean', engine: 'noop' }`.
|
|
1053
|
+
*
|
|
1054
|
+
* @param _input - The scan input (ignored).
|
|
1055
|
+
* @returns A clean scan result with the `'noop'` engine identifier.
|
|
1056
|
+
*/
|
|
1057
|
+
scan(_input: Parameters<IFileScanner['scan']>[0]): Promise<FileScanResult>;
|
|
1058
|
+
}
|
|
1059
|
+
|
|
1060
|
+
/**
|
|
1061
|
+
* @fileoverview Provider Recipes — pure, deterministic factories that produce a
|
|
1062
|
+
* ready-to-spread `BymaxStorageModuleOptions` pre-tuned for one S3-compatible
|
|
1063
|
+
* provider. The decisive detail is the non-AWS checksum opt-out: every provider
|
|
1064
|
+
* except AWS S3 sets `requestChecksumCalculation`/`responseChecksumValidation` to
|
|
1065
|
+
* `'WHEN_REQUIRED'`, because the SDK's default CRC32 integrity headers are
|
|
1066
|
+
* rejected by R2, B2, MinIO, DigitalOcean Spaces, and Wasabi.
|
|
1067
|
+
* @layer server/config
|
|
1068
|
+
*/
|
|
1069
|
+
|
|
1070
|
+
/** Shared input for the region-addressed providers (AWS, DO Spaces, Wasabi). */
|
|
1071
|
+
interface BaseInput {
|
|
1072
|
+
region: string;
|
|
1073
|
+
bucket: string;
|
|
1074
|
+
accessKeyId: string;
|
|
1075
|
+
secretAccessKey: string;
|
|
1076
|
+
/** STS / OIDC temporary session token, forwarded only when present. */
|
|
1077
|
+
sessionToken?: string;
|
|
1078
|
+
}
|
|
1079
|
+
/** Cloudflare R2 input — account-addressed, region is always `'auto'`. */
|
|
1080
|
+
interface R2Input extends Omit<BaseInput, 'region' | 'sessionToken'> {
|
|
1081
|
+
/** Cloudflare account id — forms the S3 API endpoint host. */
|
|
1082
|
+
accountId: string;
|
|
1083
|
+
/**
|
|
1084
|
+
* Public delivery domain (r2.dev or a custom domain). REQUIRED for public
|
|
1085
|
+
* reads: the `*.r2.cloudflarestorage.com` host is the S3 API endpoint and does
|
|
1086
|
+
* not serve public object reads, so there is no working default.
|
|
1087
|
+
*/
|
|
1088
|
+
customDomain: string;
|
|
1089
|
+
}
|
|
1090
|
+
/** Backblaze B2 input — the endpoint host varies by region cluster. */
|
|
1091
|
+
interface B2Input extends Omit<BaseInput, 'sessionToken'> {
|
|
1092
|
+
/** B2 S3 endpoint host, e.g. `'s3.us-west-002.backblazeb2.com'`. */
|
|
1093
|
+
endpointHost: string;
|
|
1094
|
+
}
|
|
1095
|
+
/** MinIO / dev / self-hosted input — an explicit endpoint, arbitrary region. */
|
|
1096
|
+
interface MinIOInput {
|
|
1097
|
+
endpoint: string;
|
|
1098
|
+
bucket: string;
|
|
1099
|
+
accessKeyId: string;
|
|
1100
|
+
secretAccessKey: string;
|
|
1101
|
+
/** MinIO regions are arbitrary; defaults to `'us-east-1'`. */
|
|
1102
|
+
region?: string;
|
|
1103
|
+
}
|
|
1104
|
+
/**
|
|
1105
|
+
* Pre-tuned configuration factories for each supported S3-compatible provider.
|
|
1106
|
+
* Spread the result into `forRoot`/`forRootAsync` and override any field.
|
|
1107
|
+
*
|
|
1108
|
+
* @example
|
|
1109
|
+
* BymaxStorageModule.forRoot({
|
|
1110
|
+
* ...providerRecipes.cloudflareR2({
|
|
1111
|
+
* accountId,
|
|
1112
|
+
* bucket,
|
|
1113
|
+
* accessKeyId,
|
|
1114
|
+
* secretAccessKey,
|
|
1115
|
+
* customDomain: 'https://cdn.example.com',
|
|
1116
|
+
* }),
|
|
1117
|
+
* keyPrefix: 'tenant-x/',
|
|
1118
|
+
* validation: { mimeWhitelist: ['image/*'] },
|
|
1119
|
+
* })
|
|
1120
|
+
*/
|
|
1121
|
+
declare const providerRecipes: {
|
|
1122
|
+
/** AWS S3 — keeps the SDK's default checksum behaviour (`'WHEN_SUPPORTED'`). */
|
|
1123
|
+
readonly awsS3: (input: BaseInput) => BymaxStorageModuleOptions;
|
|
1124
|
+
/** DigitalOcean Spaces — virtual-hosted, public by default, with a CDN host. */
|
|
1125
|
+
readonly digitalOceanSpaces: (input: BaseInput) => BymaxStorageModuleOptions;
|
|
1126
|
+
/** Cloudflare R2 — region `'auto'`; public reads require a custom domain. */
|
|
1127
|
+
readonly cloudflareR2: (input: R2Input) => BymaxStorageModuleOptions;
|
|
1128
|
+
/** Backblaze B2 — S3-compatible API; virtual-hosted matches `publicBaseUrl`. */
|
|
1129
|
+
readonly backblazeB2: (input: B2Input) => BymaxStorageModuleOptions;
|
|
1130
|
+
/** MinIO — dev / CI / self-hosted; path-style addressing. */
|
|
1131
|
+
readonly minio: (input: MinIOInput) => BymaxStorageModuleOptions;
|
|
1132
|
+
/** Wasabi — Hot Cloud Storage; virtual-hosted. */
|
|
1133
|
+
readonly wasabi: (input: BaseInput) => BymaxStorageModuleOptions;
|
|
1134
|
+
};
|
|
1135
|
+
|
|
1136
|
+
/**
|
|
1137
|
+
* @fileoverview Dependency-injection tokens. `Symbol()` tokens are used instead
|
|
1138
|
+
* of strings to avoid collision with tokens from other libraries.
|
|
1139
|
+
* @layer server/di-tokens
|
|
1140
|
+
*/
|
|
1141
|
+
declare const BYMAX_STORAGE_OPTIONS: unique symbol;
|
|
1142
|
+
declare const BYMAX_STORAGE_S3_CLIENT: unique symbol;
|
|
1143
|
+
declare const BYMAX_STORAGE_UPLOAD_VALIDATORS: unique symbol;
|
|
1144
|
+
declare const BYMAX_STORAGE_FILE_SCANNER: unique symbol;
|
|
1145
|
+
declare const BYMAX_STORAGE_LOGGER: unique symbol;
|
|
1146
|
+
declare const BYMAX_STORAGE_IDEMPOTENCY_CACHE: unique symbol;
|
|
1147
|
+
|
|
1148
|
+
/**
|
|
1149
|
+
* @fileoverview Provider-recipe contract — a factory that produces
|
|
1150
|
+
* pre-tuned module options for a specific S3-compatible provider.
|
|
1151
|
+
* @layer server/interfaces
|
|
1152
|
+
*/
|
|
1153
|
+
|
|
1154
|
+
/**
|
|
1155
|
+
* Provider Recipe — a factory function that produces a
|
|
1156
|
+
* `BymaxStorageModuleOptions` pre-tuned for a specific S3-compatible provider.
|
|
1157
|
+
*/
|
|
1158
|
+
type ProviderRecipe<TInput> = (input: TInput) => BymaxStorageModuleOptions;
|
|
1159
|
+
|
|
1160
|
+
/**
|
|
1161
|
+
* @fileoverview Stable string error codes returned in error responses. Host apps
|
|
1162
|
+
* and clients pattern-match on these — they MUST NOT change between minor
|
|
1163
|
+
* versions. `as const` preserves the literal types in the emitted `.d.ts`.
|
|
1164
|
+
* @layer shared/constants
|
|
1165
|
+
*/
|
|
1166
|
+
declare const STORAGE_ERROR_CODES: {
|
|
1167
|
+
readonly STORAGE_NOT_CONFIGURED: "STORAGE_NOT_CONFIGURED";
|
|
1168
|
+
readonly STORAGE_KEY_INVALID: "STORAGE_KEY_INVALID";
|
|
1169
|
+
readonly STORAGE_BODY_MISSING: "STORAGE_BODY_MISSING";
|
|
1170
|
+
readonly STORAGE_CONTENT_TYPE_REQUIRED: "STORAGE_CONTENT_TYPE_REQUIRED";
|
|
1171
|
+
readonly STORAGE_MIME_NOT_ALLOWED: "STORAGE_MIME_NOT_ALLOWED";
|
|
1172
|
+
readonly STORAGE_SIZE_EXCEEDED: "STORAGE_SIZE_EXCEEDED";
|
|
1173
|
+
readonly STORAGE_VALIDATION_FAILED: "STORAGE_VALIDATION_FAILED";
|
|
1174
|
+
readonly STORAGE_SCAN_INFECTED: "STORAGE_SCAN_INFECTED";
|
|
1175
|
+
readonly STORAGE_SCAN_INCONCLUSIVE: "STORAGE_SCAN_INCONCLUSIVE";
|
|
1176
|
+
readonly STORAGE_OBJECT_NOT_FOUND: "STORAGE_OBJECT_NOT_FOUND";
|
|
1177
|
+
readonly STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR";
|
|
1178
|
+
readonly STORAGE_SIGNED_URL_TTL_INVALID: "STORAGE_SIGNED_URL_TTL_INVALID";
|
|
1179
|
+
readonly STORAGE_PART_TOO_SMALL: "STORAGE_PART_TOO_SMALL";
|
|
1180
|
+
readonly STORAGE_INVALID_PART_COUNT: "STORAGE_INVALID_PART_COUNT";
|
|
1181
|
+
readonly STORAGE_BUCKET_UNDEFINED: "STORAGE_BUCKET_UNDEFINED";
|
|
1182
|
+
readonly STORAGE_MULTIPART_ABORTED: "STORAGE_MULTIPART_ABORTED";
|
|
1183
|
+
readonly STORAGE_INVALID_CONFIG: "STORAGE_INVALID_CONFIG";
|
|
1184
|
+
readonly STORAGE_TIMEOUT: "STORAGE_TIMEOUT";
|
|
1185
|
+
};
|
|
1186
|
+
/** Union of every stable storage error code. */
|
|
1187
|
+
type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[keyof typeof STORAGE_ERROR_CODES];
|
|
1188
|
+
|
|
1189
|
+
/**
|
|
1190
|
+
* @fileoverview The single exception type thrown by the library. Extends NestJS
|
|
1191
|
+
* `HttpException` so it integrates with host global exception filters.
|
|
1192
|
+
* @layer server/errors
|
|
1193
|
+
*/
|
|
1194
|
+
|
|
1195
|
+
/**
|
|
1196
|
+
* Standard exception thrown by the library. The HTTP status defaults to
|
|
1197
|
+
* `STORAGE_ERROR_STATUS[code]`; `code` is exposed so filters can branch without
|
|
1198
|
+
* deserializing the body.
|
|
1199
|
+
*
|
|
1200
|
+
* @example
|
|
1201
|
+
* throw new StorageException('STORAGE_OBJECT_NOT_FOUND', undefined, { key }) // 404 from the status map
|
|
1202
|
+
*/
|
|
1203
|
+
declare class StorageException extends HttpException {
|
|
1204
|
+
readonly code: StorageErrorCode;
|
|
1205
|
+
constructor(code: StorageErrorCode,
|
|
1206
|
+
/** Defaults to `STORAGE_ERROR_STATUS[code]`. Pass only to override. */
|
|
1207
|
+
statusCode?: HttpStatus, details?: Record<string, unknown>);
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1210
|
+
export { BYMAX_STORAGE_FILE_SCANNER, BYMAX_STORAGE_IDEMPOTENCY_CACHE, BYMAX_STORAGE_LOGGER, BYMAX_STORAGE_OPTIONS, BYMAX_STORAGE_S3_CLIENT, BYMAX_STORAGE_UPLOAD_VALIDATORS, BymaxStorageModule, type BymaxStorageModuleAsyncOptions, type BymaxStorageModuleOptions, type BymaxStorageModuleOptionsFactory, type CopyOptions, type DeleteManyOptions, type DeleteManyResult, type DownloadOptions, type FailedDeletion, type FileScanResult, type IFileScanner, type IUploadValidator, type ListOptions, type ListResult, type ListedObject, type MultipartUploadUrlsOptions, type MultipartUploadUrlsResult, NoOpFileScanner, NoOpUploadValidator, type ObjectMetadata, type ProviderRecipe, STORAGE_ERROR_CODES, type SignedGetUrlOptions, type SignedPutUrlOptions, type SignedUrlResult, SignedUrlService, type StorageErrorCode, StorageException, StorageService, type UploadOptions, type UploadResult, providerRecipes };
|