@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/storage/providers/resolving-storage.provider.js

@@ -0,0 +1,292 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var ResolvingStorageProvider_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolvingStorageProvider = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const storage_config_1 = require("../config/storage-config");
+const storage_driver_context_1 = require("../config/storage-driver-context");
+const storage_config_service_1 = require("../config/storage-config.service");
+const storage_not_configured_error_1 = require("../config/storage-not-configured.error");
+const storage_driver_1 = require("../drivers/storage-driver");
+// =============================================================================
+// ResolvingStorageProvider — storage that follows the settings (issue #373)
+// =============================================================================
+//
+// The implementation bound to `STORAGE_PROVIDER`. It implements the full
+// `StorageProvider` interface and performs none of it: every method resolves
+// the configuration in force RIGHT NOW, gets or builds the client for it, and
+// delegates.
+//
+// -----------------------------------------------------------------------------
+// WHY A DELEGATING PROVIDER RATHER THAN AN ASYNC FACTORY
+// -----------------------------------------------------------------------------
+//
+// The obvious alternative is `{ provide: STORAGE_PROVIDER, useFactory: async
+// () => new S3StorageProvider(await resolve()) }`. Nest supports it, it is
+// three lines, and it is wrong for this feature in two ways that are not
+// obvious until it breaks:
+//
+//   1. IT RESOLVES ONCE, AT BOOT. A factory runs when the container is built,
+//      so the whole point of #373 — an administrator changing the bucket, or
+//      rotating the key, WITHOUT A RESTART — is lost. Nine consumers would hold
+//      an injected instance built from a configuration that stopped being true
+//      the moment somebody saved the settings page.
+//   2. IT MAKES AN UNCONFIGURED DEPLOYMENT UNBOOTABLE. An async factory that
+//      cannot resolve must either throw (the API does not start — on a FRESH
+//      INSTALL, which by definition has no storage configured yet, so nobody
+//      could ever reach the settings page to fix it) or return something
+//      broken. Both are worse than a 503 on the calls that actually need
+//      storage.
+//
+// So the indirection is permanent and deliberate. It costs one object
+// allocation and one `Map`-ish lookup per call; it buys live reconfiguration
+// and a bootable empty install.
+//
+// -----------------------------------------------------------------------------
+// WHAT DOES NOT CHANGE
+// -----------------------------------------------------------------------------
+//
+// NOT ONE CONSUMER OF `STORAGE_PROVIDER` IS TOUCHED by this. All nine still
+// inject the same token, call the same thirteen methods with the same
+// signatures, and get the same results. That constraint is why this class
+// implements the interface rather than replacing it, why `getBucket()` stays
+// synchronous (see below), and why an unconfigured deployment raises an
+// exception that already maps to a status code rather than a new error type
+// every caller would have to learn.
+// =============================================================================
+/**
+ * How many built clients are kept.
+ *
+ * TWO, not one and not many. One is not enough: a settings edit or a key
+ * rotation happening while a long upload is in flight would evict the client
+ * that upload is using, and `S3Client.destroy()` on a live pool aborts requests
+ * mid-flight. Keeping the immediately-previous configuration lets work already
+ * in progress finish against the client it started with.
+ *
+ * More than two buys nothing and costs sockets: configurations arrive one at a
+ * time, from a human saving a form. This is a rotation window, not a cache of
+ * tenants — a multi-tenant fork keying clients per tenant is a different design
+ * and should say so rather than raise this number.
+ */
+const DELEGATE_CACHE_LIMIT = 2;
+/**
+ * The default `STORAGE_PROVIDER`: resolves the active configuration per call (the `storage` settings namespace and the credential store) and delegates to an S3 client built for it, so a configuration change takes effect without a restart; refuses with `StorageNotConfiguredError` (503) while storage is not configured.
+ *
+ * @stability experimental
+ */
+let ResolvingStorageProvider = ResolvingStorageProvider_1 = class ResolvingStorageProvider {
+    storageConfig;
+    configService;
+    logger = new common_1.Logger(ResolvingStorageProvider_1.name);
+    /**
+     * Built clients, most recently used first.
+     *
+     * An array rather than a `Map` because it holds at most
+     * {@link DELEGATE_CACHE_LIMIT} entries and the order IS the eviction policy;
+     * a `Map` would need a second structure to express "which one is oldest".
+     */
+    delegates = [];
+    constructor(storageConfig, configService) {
+        this.storageConfig = storageConfig;
+        this.configService = configService;
+    }
+    /**
+     * The configured provider kind (`s3`, `r2`, `s3compatible`), from the last
+     * settings read. Synchronous, like {@link getBucket} and from the same
+     * snapshot, so a row recording a bucket and a row recording its provider
+     * describe one configuration. Code that can await and needs the current
+     * value reads `StorageConfigService.activeProvider()` first, which also
+     * refreshes this snapshot.
+     */
+    get kind() {
+        return this.storageConfig.lastKnownProvider();
+    }
+    // ---------------------------------------------------------------------------
+    // StorageProvider — all thirteen methods, each one line of delegation
+    // ---------------------------------------------------------------------------
+    //
+    // Written out rather than generated with a `Proxy` or a loop over method
+    // names. A proxy would satisfy the interface at runtime and NOT at compile
+    // time: adding a fourteenth method to `StorageProvider` would type-check
+    // here, ship, and fail in production as "is not a function". Thirteen
+    // one-line methods make the compiler the thing that notices.
+    async upload(key, stream, options) {
+        return (await this.delegate()).upload(key, stream, options);
+    }
+    async initMultipartUpload(key, options) {
+        return (await this.delegate()).initMultipartUpload(key, options);
+    }
+    async getSignedUploadUrl(key, uploadId, partNumber, expiresIn) {
+        return (await this.delegate()).getSignedUploadUrl(key, uploadId, partNumber, expiresIn);
+    }
+    async completeMultipartUpload(key, uploadId, parts) {
+        return (await this.delegate()).completeMultipartUpload(key, uploadId, parts);
+    }
+    async abortMultipartUpload(key, uploadId) {
+        return (await this.delegate()).abortMultipartUpload(key, uploadId);
+    }
+    async download(key) {
+        return (await this.delegate()).download(key);
+    }
+    async getSignedDownloadUrl(key, options) {
+        return (await this.delegate()).getSignedDownloadUrl(key, options);
+    }
+    async getSignedPutUrl(key, options) {
+        return (await this.delegate()).getSignedPutUrl(key, options);
+    }
+    async delete(key) {
+        return (await this.delegate()).delete(key);
+    }
+    async getMetadata(key) {
+        return (await this.delegate()).getMetadata(key);
+    }
+    async setMetadata(key, metadata) {
+        return (await this.delegate()).setMetadata(key, metadata);
+    }
+    async exists(key) {
+        return (await this.delegate()).exists(key);
+    }
+    /**
+     * The active bucket — the one synchronous method on an interface whose
+     * configuration is asynchronous.
+     *
+     * ── THE PROBLEM, STATED HONESTLY ────────────────────────────────────────────
+     *
+     * `StorageProvider.getBucket(): string` cannot await anything, and the bucket
+     * now lives in a database row. Three of the four call sites
+     * (`ObjectsService.initUpload`, `DatabaseBackupRunnerService.queueBackup` and
+     * `claimRun`) write the returned value onto a ROW — `storage_objects.bucket`,
+     * `database_backup_runs.bucket` — where it outlives the request and is later
+     * used to find the object again.
+     *
+     * ── WHAT THIS DOES ──────────────────────────────────────────────────────────
+     *
+     * It answers from the bucket named by the last successful settings read
+     * (`StorageConfigService.lastKnownBucket`), and throws
+     * `StorageNotConfiguredError.unresolved()` — a 503 — when this process has no
+     * such read, or that read named no bucket. The snapshot is warmed once at
+     * startup and refreshed by every one of the twelve async methods above, so on
+     * a configured deployment the answer is at most one storage operation (or
+     * five seconds) old, and in practice is current.
+     *
+     * It does NOT wait for a fully resolved configuration — a deployment with a
+     * bucket but no saved credential still has exactly one honest answer to "which
+     * bucket?", and `queueBackup` has no async storage call to recover through.
+     * Nothing is risked: every path that moves bytes goes through one of the
+     * twelve methods above first, and they refuse an incomplete configuration
+     * outright. See `StorageConfigService.lastPolicyBucket`.
+     *
+     * ── WHY NOT `''` ────────────────────────────────────────────────────────────
+     *
+     * Because it is a lie that is written to disk. An empty bucket on a
+     * `storage_objects` row does not fail anything at the time; it fails months
+     * later, when a cleanup sweep or a restore tries to address the object and
+     * cannot say where it is. A 503 at the moment of the call is loud, immediate,
+     * and fixable by the person who caused it.
+     *
+     * ── WHY NOT MAKE IT ASYNC ───────────────────────────────────────────────────
+     *
+     * That is the genuinely correct shape, and it is out of scope by construction:
+     * it changes `StorageProvider`, and this part of #373 may not change a single
+     * consumer of `STORAGE_PROVIDER`. It is also not free of judgement — the two
+     * backup call sites use it to build a storage key inside a retry loop around
+     * an INSERT, so awaiting there is a settings read inside a transaction-shaped
+     * critical section. Worth doing deliberately, in its own change, with its own
+     * tests; not as a side effect of making storage configurable.
+     *
+     * ── WHY NOT READ THE SETTINGS SYNCHRONOUSLY FROM A CACHE ────────────────────
+     *
+     * That is exactly what this does. The distinction worth stating is that the
+     * snapshot is populated only by reads that SUCCEEDED and named a bucket —
+     * never by the seeded defaults, which are the unconfigured state — so this
+     * method returns a bucket somebody configured, or nothing at all.
+     */
+    getBucket() {
+        const bucket = this.storageConfig.lastKnownBucket();
+        if (!bucket) {
+            throw storage_not_configured_error_1.StorageNotConfiguredError.unresolved();
+        }
+        return bucket;
+    }
+    // ---------------------------------------------------------------------------
+    // Resolution and the delegate cache
+    // ---------------------------------------------------------------------------
+    /**
+     * The client for the configuration in force, or a 503.
+     *
+     * ⚠ The resolved configuration holds a plaintext secret access key. It is a
+     * local here and is handed only to `fingerprintStorageConfig` and to the
+     * `S3StorageProvider` constructor; it is never assigned to a field, never
+     * logged, and never reaches an error body.
+     */
+    async delegate() {
+        const resolution = await this.storageConfig.resolve();
+        if (!resolution.configured) {
+            throw storage_not_configured_error_1.StorageNotConfiguredError.missing(resolution.provider, resolution.missing);
+        }
+        return this.delegateFor(resolution.config);
+    }
+    delegateFor(config) {
+        const fingerprint = (0, storage_config_1.fingerprintStorageConfig)(config);
+        const index = this.delegates.findIndex((entry) => entry.fingerprint === fingerprint);
+        if (index >= 0) {
+            const [hit] = this.delegates.splice(index, 1);
+            this.delegates.unshift(hit);
+            return hit.provider;
+        }
+        const label = (0, storage_config_1.describeStorageConfig)(config);
+        this.logger.log(`Building storage client: ${label}`);
+        // The ACTIVE DRIVER builds the provider (`StorageDriver.build`): this class
+        // knows nothing about which object store it is. The secrets travel in the
+        // closure only for the duration of the build.
+        const driver = (0, storage_driver_1.requireStorageDriver)(config.provider);
+        const provider = Promise.resolve(driver.build((0, storage_driver_context_1.storageDriverContext)({
+            settings: config.settings,
+            secret: async (name) => config.secrets[name] ?? null,
+            logger: this.logger,
+            config: this.configService,
+        })));
+        const entry = { fingerprint, provider, label };
+        this.delegates.unshift(entry);
+        this.evictOverflow();
+        // A failed build must not be cached: the next call tries again.
+        provider.catch(() => {
+            this.delegates = this.delegates.filter((candidate) => candidate !== entry);
+        });
+        return provider;
+    }
+    evictOverflow() {
+        while (this.delegates.length > DELEGATE_CACHE_LIMIT) {
+            const evicted = this.delegates.pop();
+            if (!evicted) {
+                return;
+            }
+            this.logger.log(`Releasing superseded storage client: ${evicted.label}`);
+            // A provider that cannot be destroyed is a leaked socket pool, not a
+            // failed request: the caller is in the middle of an upload that has
+            // nothing to do with this. Log and carry on rather than turning
+            // somebody else's successful configuration change into a 500. Not every
+            // driver's provider holds anything to release, so `destroy` is optional.
+            void evicted.provider
+                .then((built) => built.destroy?.())
+                .catch((error) => this.logger.warn(`Failed to release a superseded storage client: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+};
+exports.ResolvingStorageProvider = ResolvingStorageProvider;
+exports.ResolvingStorageProvider = ResolvingStorageProvider = ResolvingStorageProvider_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [storage_config_service_1.StorageConfigService,
+        config_1.ConfigService])
+], ResolvingStorageProvider);
+//# sourceMappingURL=resolving-storage.provider.js.map

package/dist/storage/providers/resolving-storage.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolving-storage.provider.js","sourceRoot":"","sources":["../../../src/storage/providers/resolving-storage.provider.ts"],"names":[],"mappings":"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"}

package/dist/storage/providers/s3/s3-storage.provider.d.ts

@@ -0,0 +1,263 @@
+import { type S3ClientConfig } from '@aws-sdk/client-s3';
+import { Readable } from 'node:stream';
+import type { StorageProviderKind } from '@marinoscar/platform-contract/storage';
+import { StorageProvider } from '../storage-provider.interface';
+import { StorageUploadOptions, StorageUploadResult, MultipartUploadInit, UploadPart, SignedUrlOptions, SignedPutUrlOptions } from '../storage-provider.types';
+/**
+ * The multipart part size used when nothing else says otherwise: 10 MiB.
+ *
+ * Was `configService.get('storage.partSize', 10485760)` inline; it moved out
+ * here when the constructor stopped injecting `ConfigService` (#373 part 2) so
+ * the default is stated once rather than re-typed at whichever call site
+ * happens to need it. The value is unchanged.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_S3_PART_SIZE = 10485760;
+/**
+ * Everything this provider needs to talk to an object store.
+ *
+ * ── WHY A CONFIG OBJECT AND NOT `ConfigService` (#373 part 2) ───────────────
+ *
+ * Because there is no longer ONE configuration for the life of the process.
+ * Storage is administrator-editable at runtime now, so the provider that
+ * actually talks to S3 must be constructible more than once — once per distinct
+ * configuration — and a class that reads its settings out of the environment in
+ * its constructor cannot be. Taking a plain object turns "which bucket am I?"
+ * from something this class decides into something its caller decides, which is
+ * what lets `ResolvingStorageProvider` build one of these per configuration and
+ * throw it away when the configuration changes.
+ *
+ * It also makes this class trivially testable and, notably, FREE OF NEST: it is
+ * no longer `@Injectable()` and is never constructed by the container.
+ *
+ * ⚠ `secretAccessKey` is plaintext, necessarily — an S3 client cannot sign
+ * without it. Nothing in this class logs it, and nothing should.
+ *
+ * @stability experimental
+ */
+export interface S3StorageProviderConfig {
+    /**
+     * Which vendor's flavour of the S3 protocol this instance is talking to.
+     *
+     * THE ONLY FIELD THAT CHANGES HOW THE CLIENT IS BUILT (#374) — see
+     * {@link buildS3ClientConfig}. It is carried rather than inferred from the
+     * shape of the rest: "has an endpoint" and "is R2" are different questions,
+     * and inferring one from the other is precisely the conflation
+     * `forcePathStyle: !!endpoint` used to make.
+     *
+     * It is also what {@link S3StorageProvider.kind} answers with.
+     */
+    provider: StorageProviderKind;
+    /** Bucket every operation addresses. */
+    bucket: string;
+    /** Signing region. */
+    region: string;
+    /** Explicit origin, or absent for the SDK's own AWS host. Never `''`. */
+    endpoint?: string;
+    /** Identifier half of the credential. */
+    accessKeyId: string;
+    /** ⚠ Plaintext secret half. */
+    secretAccessKey: string;
+    /**
+     * `https://host/bucket/key` (true) over `https://bucket.host/key` (false).
+     *
+     * OPTIONAL AND NULLABLE, AND NEITHER IS `false`: absent or `null` means "use
+     * this provider's convention" ({@link buildS3ClientConfig} — path style for
+     * `s3compatible`, virtual-host style for `s3` and `r2`), while `false` is an
+     * operator saying virtual-host style about a deployment that might otherwise
+     * have defaulted the other way.
+     *
+     * `null` is accepted beside absent because that is how the stored setting
+     * spells "unset" (`systemStorageSchema.forcePathStyle` is tri-state), and
+     * `ResolvingStorageProvider` hands this configuration straight through from
+     * there. Collapsing `null` on the way in would put the default below out of
+     * reach of every settings-configured deployment, which is the defect this
+     * shape exists to prevent.
+     */
+    forcePathStyle?: boolean | null;
+    /** Multipart part size in bytes. Defaults to {@link DEFAULT_S3_PART_SIZE}. */
+    partSize?: number;
+}
+/**
+ * The `S3Client` options for one provider kind — the whole of what differs
+ * between AWS S3, Cloudflare R2 and an S3-compatible endpoint (#374).
+ *
+ * ── WHY ONE DRIVER AND NOT THREE CLASSES ────────────────────────────────────
+ *
+ * Because this function IS the difference. All three speak the same protocol
+ * through the same SDK; the thirteen method bodies below are byte-for-byte the
+ * same work, and `getSignedPutUrl`'s rationale alone runs forty lines that
+ * would then exist in triplicate and drift. Three classes would be three copies
+ * of everything that is identical, to express the four lines that are not.
+ *
+ * ── WHAT THIS FUNCTION DECIDES, AND WHAT IT DOES NOT ────────────────────────
+ *
+ * It decides the PATH-STYLE DEFAULT and the CHECKSUM FLAGS. It deliberately
+ * does NOT decide the endpoint or the region: both are already resolved, per
+ * provider, by `resolveS3Config` in `../../drivers/s3/s3-config.ts` —
+ * R2's account-scoped host from `deriveR2Endpoint`, R2's `auto` and an
+ * S3-compatible endpoint's `us-east-1` from the two exported fallback
+ * constants. Re-deriving either here would be a second copy of a rule that has
+ * exactly one definition today, and the failure mode of a second copy is a
+ * settings page reporting one host while the client talks to another. What
+ * arrives here is therefore already correct; this function's job is only what
+ * the settings namespace cannot express.
+ *
+ * ── THE TABLE (#374), AS IT IS ACTUALLY ENFORCED ────────────────────────────
+ *
+ *   | kind           | endpoint            | region      | forcePathStyle | checksums     |
+ *   | -------------- | ------------------- | ----------- | -------------- | ------------- |
+ *   | `s3`           | unset (SDK's host)  | operator's  | false          | SDK default   |
+ *   | `r2`           | derived from acct   | `auto`      | false          | WHEN_REQUIRED |
+ *   | `s3compatible` | operator's          | `us-east-1` | true*          | SDK default   |
+ *
+ * The first two columns are `resolveStorageConfig`'s; the last two are this
+ * function's. The endpoint and region cells marked "operator's" and the two
+ * derived ones are all fallbacks — a value an administrator typed always wins,
+ * for every provider.
+ *
+ * (*) A DEFAULT, not a rule. `forcePathStyle` is tri-state: an administrator
+ * who states `true` or `false` wins for every provider, and `null` (the shipped
+ * default) or an absent key is what lets this row apply. See the field's own
+ * note.
+ *
+ * `packages/platform-api/test/storage/providers/s3/s3-storage.provider.spec.ts` asserts the
+ * whole row end to end, from a settings literal to the arguments
+ * `new S3Client(...)` was actually called with, rather than each half alone.
+ *
+ * ── WHY IT IS EXPORTED (#375) ───────────────────────────────────────────────
+ *
+ * Because #375's admin surface builds `S3Client`s this class does not own: the
+ * connection test drives `HeadBucket`, and the bucket provisioner drives
+ * `CreateBucket`/`PutPublicAccessBlock`/`PutBucketEncryption`/`PutBucketCors` —
+ * none of which is a `StorageProvider` operation, and none of which belongs on
+ * that interface (see the rule in #375's own header: the interface and its nine
+ * consumers are untouched by this feature).
+ *
+ * Those clients MUST be built the same way this one is, or the test would be
+ * testing a differently-configured client than the one that will do the work —
+ * a `forcePathStyle` that differs by a default is the exact discrepancy that
+ * makes a MinIO connection test pass and every upload fail. Exporting the
+ * function is additive: no signature changed, no caller changed, and there is
+ * still exactly one place that knows what each vendor's SDK flavour wants.
+ *
+ * @stability experimental
+ */
+export declare function buildS3ClientConfig(config: S3StorageProviderConfig): S3ClientConfig;
+/**
+ * S3-compatible storage provider implementation
+ * Supports AWS S3, MinIO, LocalStack, and other S3-compatible storage services
+ *
+ * Constructed from a {@link S3StorageProviderConfig} rather than resolved by
+ * Nest — see that type. One instance is bound to one configuration for its
+ * whole life; a configuration change produces a new instance and
+ * {@link S3StorageProvider.destroy}s the old one.
+ *
+ * @stability experimental
+ */
+export declare class S3StorageProvider implements StorageProvider {
+    private readonly logger;
+    private readonly s3Client;
+    private readonly bucket;
+    private readonly partSize;
+    /**
+     * Which vendor this client is actually talking to (`s3`, `r2` or
+     * `s3compatible`): the {@link StorageProvider.kind} of this driver, carried
+     * by the client built from the configuration, so "which provider is in
+     * force?" has an authoritative answer on the object that IS the answer
+     * rather than being inferred from the shape of a config.
+     */
+    readonly kind: StorageProviderKind;
+    /**
+     * Alias of {@link S3StorageProvider.kind}, kept for existing callers.
+     *
+     * @deprecated Use `kind`.
+     */
+    get providerId(): StorageProviderKind;
+    constructor(config: S3StorageProviderConfig);
+    /**
+     * Release this client's sockets.
+     *
+     * Called by `ResolvingStorageProvider` when a configuration change makes this
+     * instance obsolete. Without it, every settings edit and every credential
+     * rotation would leak an `S3Client`'s connection pool for the life of the
+     * process — the same leak `SmtpEmailProvider` closes by calling
+     * `transport.close()` on the transporter it replaces.
+     */
+    destroy(): void;
+    /**
+     * Simple upload using AWS SDK Upload helper
+     * Automatically handles multipart uploads for large files
+     */
+    upload(key: string, stream: Readable, options: StorageUploadOptions): Promise<StorageUploadResult>;
+    /**
+     * Initialize multipart upload
+     */
+    initMultipartUpload(key: string, options: StorageUploadOptions): Promise<MultipartUploadInit>;
+    /**
+     * Generate signed URL for uploading a specific part
+     */
+    getSignedUploadUrl(key: string, uploadId: string, partNumber: number, expiresIn?: number): Promise<string>;
+    /**
+     * Complete multipart upload
+     */
+    completeMultipartUpload(key: string, uploadId: string, parts: UploadPart[]): Promise<StorageUploadResult>;
+    /**
+     * Abort multipart upload
+     */
+    abortMultipartUpload(key: string, uploadId: string): Promise<void>;
+    /**
+     * Download file as stream
+     */
+    download(key: string): Promise<Readable>;
+    /**
+     * Generate signed download URL
+     */
+    getSignedDownloadUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Generate a signed URL for a single-shot `PUT` of a whole object.
+     *
+     * `PutObjectCommand`, deliberately — not `UploadPartCommand`. See the block
+     * comment on `getSignedPutUrl` in `../storage-provider.interface.ts` for why
+     * a one-part multipart upload was rejected for this.
+     *
+     * ⚠ `ContentType` IS ONLY SET WHEN THE CALLER SUPPLIED ONE. S3 signs the
+     * headers it is given: presigning with a `Content-Type` the uploader then
+     * does not send exactly produces a `SignatureDoesNotMatch` on a machine
+     * nobody is watching, and the error names the signature rather than the
+     * header that caused it. Omitting it leaves the uploader free, which is the
+     * right default for a caller that is guessing.
+     *
+     * The URL itself is NEVER logged, here or anywhere else — it is a bearer
+     * write capability for `key` until it expires. The debug line below names
+     * the key only, matching `getSignedDownloadUrl` beside it.
+     */
+    getSignedPutUrl(key: string, options?: SignedPutUrlOptions): Promise<string>;
+    /**
+     * Delete file
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Get file metadata
+     */
+    getMetadata(key: string): Promise<Record<string, string> | null>;
+    /**
+     * Set file metadata
+     * Uses CopyObject with REPLACE metadata directive
+     *
+     * ⚠ `CopySource` IS PERCENT-ENCODED AND `Key` IS NOT. That asymmetry is the
+     * S3 API's, not a slip — see `encodeCopySource` for what sending the
+     * raw key here did to any key containing a space, a `+` or a `%`.
+     */
+    setMetadata(key: string, metadata: Record<string, string>): Promise<void>;
+    /**
+     * Check if file exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get bucket name
+     */
+    getBucket(): string;
+}
+//# sourceMappingURL=s3-storage.provider.d.ts.map

package/dist/storage/providers/s3/s3-storage.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-storage.provider.d.ts","sourceRoot":"","sources":["../../../../src/storage/providers/s3/s3-storage.provider.ts"],"names":[],"mappings":"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"}