@orthacms/media-provider-s3 0.3.0 → 0.4.0

package/dist/lib/fake-s3-client.d.ts

@@ -0,0 +1,50 @@
+import { S3Client } from '@aws-sdk/client-s3';
+/** One object, as the fake holds it. */
+interface FakeObject {
+    body: Buffer;
+    contentType?: string;
+}
+/**
+ * A stand-in `S3Client` that answers the four commands this adapter sends.
+ *
+ * **What it is for and what it is not.** It exercises *our* code — key shapes,
+ * the metering that produces size and checksum, the error mapping, the abort
+ * path — offline and in milliseconds. It is not a claim that the adapter works
+ * against S3: a fake agrees with whatever the code does, which is exactly the
+ * failure mode MinIO and a real bucket exist to catch. Both are named in
+ * `AGENTS.md` as required before this provider is trusted with a deployment.
+ *
+ * Exported from `src/` rather than hidden in a spec so the eventual MinIO suite
+ * can be written as the same cases against a different client.
+ */
+export declare class FakeS3Client {
+    private readonly buckets;
+    readonly objects: Map<string, FakeObject>;
+    /** Every command class name this client was asked to send, in order. */
+    readonly sent: string[];
+    /** Buckets that exist. `HeadBucket` fails for anything else. */
+    constructor(buckets?: Set<string>);
+    /** The provider only ever calls `send`, so that is all this implements. */
+    send(command: {
+        constructor: {
+            name: string;
+        };
+        input: Record<string, unknown>;
+    }): Promise<unknown>;
+    /** Keys currently held, sorted — the harness for the contract suite. */
+    keys(): string[];
+    /**
+     * A **real** `S3Client` with only its `send` replaced.
+     *
+     * Hand-rolling the whole client does not work and should not be attempted:
+     * `lib-storage` reads the client's own `config` — `requestHandler` for
+     * progress events, `endpointProvider` to build the uploaded object's
+     * `Location` — so a plain object fails inside the SDK rather than in our
+     * code. Keeping the real client means the command construction, the
+     * endpoint resolution and the middleware stack are all genuine, and only
+     * the network hop is stubbed.
+     */
+    asClient(): S3Client;
+}
+export {};
+//# sourceMappingURL=fake-s3-client.d.ts.map

package/dist/lib/fake-s3-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-s3-client.d.ts","sourceRoot":"","sources":["../../src/lib/fake-s3-client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,wCAAwC;AACxC,UAAU,UAAU;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAqBD;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IAKT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,QAAQ,CAAC,OAAO,0BAAiC;IACjD,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAM;IAC7B,gEAAgE;gBACnC,OAAO,GAAE,GAAG,CAAC,MAAM,CAAuB;IAEvE,2EAA2E;IACrE,IAAI,CAAC,OAAO,EAAE;QAChB,WAAW,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,OAAO,CAAC;IAuCpB,wEAAwE;IACxE,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,QAAQ;CAcvB"}

package/dist/lib/fake-s3-client.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeS3Client = void 0;
+const node_stream_1 = require("node:stream");
+const client_s3_1 = require("@aws-sdk/client-s3");
+/** The error shape this family of services uses for a missing key. */
+function notFound(name) {
+    return Object.assign(new Error(name), {
+        name,
+        $metadata: { httpStatusCode: 404 }
+    });
+}
+/** Drains whatever `Body` the SDK was handed into one buffer. */
+async function collect(body) {
+    if (Buffer.isBuffer(body))
+        return body;
+    if (typeof body === 'string')
+        return Buffer.from(body);
+    const chunks = [];
+    for await (const chunk of body) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * A stand-in `S3Client` that answers the four commands this adapter sends.
+ *
+ * **What it is for and what it is not.** It exercises *our* code — key shapes,
+ * the metering that produces size and checksum, the error mapping, the abort
+ * path — offline and in milliseconds. It is not a claim that the adapter works
+ * against S3: a fake agrees with whatever the code does, which is exactly the
+ * failure mode MinIO and a real bucket exist to catch. Both are named in
+ * `AGENTS.md` as required before this provider is trusted with a deployment.
+ *
+ * Exported from `src/` rather than hidden in a spec so the eventual MinIO suite
+ * can be written as the same cases against a different client.
+ */
+class FakeS3Client {
+    buckets;
+    objects = new Map();
+    /** Every command class name this client was asked to send, in order. */
+    sent = [];
+    /** Buckets that exist. `HeadBucket` fails for anything else. */
+    constructor(buckets = new Set(['bucket'])) {
+        this.buckets = buckets;
+    }
+    /** The provider only ever calls `send`, so that is all this implements. */
+    async send(command) {
+        const kind = command.constructor.name;
+        this.sent.push(kind);
+        const key = command.input['Key'];
+        switch (kind) {
+            case 'PutObjectCommand': {
+                this.objects.set(key, {
+                    body: await collect(command.input['Body']),
+                    contentType: command.input['ContentType']
+                });
+                return { ETag: '"fake"' };
+            }
+            case 'GetObjectCommand': {
+                const object = this.objects.get(key);
+                if (!object)
+                    throw notFound('NoSuchKey');
+                return {
+                    Body: node_stream_1.Readable.from(object.body),
+                    ContentType: object.contentType
+                };
+            }
+            case 'DeleteObjectCommand': {
+                // S3 answers 204 whether or not the key was there.
+                this.objects.delete(key);
+                return {};
+            }
+            case 'HeadBucketCommand': {
+                if (!this.buckets.has(command.input['Bucket'])) {
+                    throw notFound('NotFound');
+                }
+                return {};
+            }
+            default:
+                throw new Error(`FakeS3Client cannot answer ${kind}`);
+        }
+    }
+    /** Keys currently held, sorted — the harness for the contract suite. */
+    keys() {
+        return [...this.objects.keys()].sort();
+    }
+    /**
+     * A **real** `S3Client` with only its `send` replaced.
+     *
+     * Hand-rolling the whole client does not work and should not be attempted:
+     * `lib-storage` reads the client's own `config` — `requestHandler` for
+     * progress events, `endpointProvider` to build the uploaded object's
+     * `Location` — so a plain object fails inside the SDK rather than in our
+     * code. Keeping the real client means the command construction, the
+     * endpoint resolution and the middleware stack are all genuine, and only
+     * the network hop is stubbed.
+     */
+    asClient() {
+        const client = new client_s3_1.S3Client({
+            region: 'auto',
+            endpoint: 'https://fake.s3.test',
+            forcePathStyle: true,
+            credentials: {
+                accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+                secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
+            }
+        });
+        client.send = ((command) => this.send(command));
+        return client;
+    }
+}
+exports.FakeS3Client = FakeS3Client;

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

@@ -1,15 +1,71 @@
+import { S3Client } from '@aws-sdk/client-s3';
 import type { StorageProvider } from '@orthacms/media-server';
-/** AWS S3 provider settings. */
+/**
+ * Settings for an **S3-compatible** object store.
+ *
+ * Written endpoint-first rather than AWS-first on purpose: `endpoint` plus
+ * `forcePathStyle` is the whole difference between AWS S3, Cloudflare R2,
+ * MinIO, DigitalOcean Spaces, Backblaze B2, Wasabi, Scaleway, Hetzner, Supabase
+ * Storage and Tigris. One adapter, ten services — which is why this is one
+ * package and not ten.
+ */
 export interface S3StorageConfig {
+    /** Bucket every object lands in. */
     bucket: string;
-    region: string;
+    /**
+     * Region. Required by AWS; most S3-compatible services ignore it but the
+     * signer still needs a value, so it defaults to `auto` (what R2 expects).
+     */
+    region?: string;
+    /**
+     * Full endpoint URL for a non-AWS service — e.g.
+     * `https://<account>.r2.cloudflarestorage.com`, or `http://localhost:9000`
+     * for MinIO. Omit for AWS S3 itself.
+     */
+    endpoint?: string;
+    /**
+     * Address objects as `<endpoint>/<bucket>/<key>` rather than
+     * `<bucket>.<endpoint>/<key>`. Required by MinIO and most self-hosted
+     * gateways; harmless for R2.
+     */
+    forcePathStyle?: boolean;
+    /**
+     * Explicit credentials. **Omit them** on a deployment with an instance
+     * role, IRSA or any other ambient credential source — the SDK's own
+     * provider chain is what should resolve those, and passing blanks here
+     * would shadow it with credentials that cannot sign.
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /** Prefix every key with this, e.g. to share a bucket between environments. */
+    keyPrefix?: string;
+    /**
+     * An already-built client, for a deployment that needs custom middleware,
+     * a proxy agent or a retry strategy — and for tests, which drive this
+     * adapter against a stub rather than a network.
+     *
+     * When present, every other connection setting here is ignored: the client
+     * carries them.
+     */
+    client?: S3Client;
 }
 /**
- * Placeholder S3 {@link StorageProvider}. It proves the routing seam
- * end-to-end — the composition root can register it under a name and a resolver
- * can route to it — without an AWS dependency. Every method throws until the
- * real adapter (put/get via the AWS SDK, signed `url`) lands. The signature
- * matches `createLocalStorageProvider`, so switching is a config change.
+ * The S3-compatible {@link StorageProvider}.
+ *
+ * Three things here are load-bearing and easy to lose in a refactor:
+ *
+ * 1. **`put` is all-or-nothing.** A multipart upload that fails leaves parts
+ *    billed and invisible, and the key never reached a caller — so nothing can
+ *    reclaim them. The `catch` aborts the upload, which is what removes them.
+ * 2. **size and checksum are measured here, not taken from the response.** The
+ *    core persists both and the reclaim path trusts them; `ETag` is not a
+ *    sha256 and is not even an MD5 for a multipart object.
+ * 3. **`get` rejects with `ObjectNotFoundError`**, mapped from the several
+ *    shapes this family of services uses. A raw `NoSuchKey` escaping makes a
+ *    missing blob a 500 where the route means to answer 404.
  */
 export declare function createS3StorageProvider(config: S3StorageConfig): StorageProvider;
 //# sourceMappingURL=s3-storage-provider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"s3-storage-provider.d.ts","sourceRoot":"","sources":["../../src/lib/s3-storage-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,wBAAwB,CAAC;AAE5E,gCAAgC;AAChC,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAClB;AAYD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAEnC,MAAM,EAAE,eAAe,GACxB,eAAe,CAiBjB"}
+{"version":3,"file":"s3-storage-provider.d.ts","sourceRoot":"","sources":["../../src/lib/s3-storage-provider.ts"],"names":[],"mappings":"AAEA,OAAO,EAIH,QAAQ,EAEX,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAGR,eAAe,EAElB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC5B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CACrB;AAiCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,eAAe,GACxB,eAAe,CAsJjB"}

package/dist/lib/s3-storage-provider.js

@@ -1,37 +1,174 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createS3StorageProvider = createS3StorageProvider;
-/** Raised by every method until the AWS adapter is implemented. */
-class S3NotImplementedError extends Error {
-    constructor() {
-        super('@orthacms/media-provider-s3 is a stub — the AWS S3 adapter is not implemented yet.');
-        this.name = 'S3NotImplementedError';
-    }
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const lib_storage_1 = require("@aws-sdk/lib-storage");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const media_server_1 = require("@orthacms/media-server");
+/** How many bytes one multipart part carries. The SDK's own minimum is 5 MB. */
+const PART_SIZE = 5 * 1024 * 1024;
+/** How many parts are in flight at once for one upload. */
+const QUEUE_SIZE = 4;
+/** Reduces a file name to one safe key segment. Mirrors the other providers. */
+function sanitize(fileName) {
+    const cleaned = fileName.replace(/[^A-Za-z0-9_.-]+/g, '_');
+    // `.` and `..` survive the character class and are not names. S3 keys are
+    // opaque strings so neither would traverse anything — but a key that
+    // round-trips differently between two providers is a key the core cannot
+    // treat as opaque, and `..` in a key breaks most bucket browsers.
+    return cleaned === '.' || cleaned === '..' ? `_${cleaned}` : cleaned;
+}
+/** True for the several ways this family of services says "no such object". */
+function isMissing(error) {
+    const candidate = error;
+    return (candidate?.name === 'NoSuchKey' ||
+        candidate?.name === 'NotFound' ||
+        candidate?.Code === 'NoSuchKey' ||
+        candidate?.$metadata?.httpStatusCode === 404);
 }
 /**
- * Placeholder S3 {@link StorageProvider}. It proves the routing seam
- * end-to-end — the composition root can register it under a name and a resolver
- * can route to it — without an AWS dependency. Every method throws until the
- * real adapter (put/get via the AWS SDK, signed `url`) lands. The signature
- * matches `createLocalStorageProvider`, so switching is a config change.
+ * The S3-compatible {@link StorageProvider}.
+ *
+ * Three things here are load-bearing and easy to lose in a refactor:
+ *
+ * 1. **`put` is all-or-nothing.** A multipart upload that fails leaves parts
+ *    billed and invisible, and the key never reached a caller — so nothing can
+ *    reclaim them. The `catch` aborts the upload, which is what removes them.
+ * 2. **size and checksum are measured here, not taken from the response.** The
+ *    core persists both and the reclaim path trusts them; `ETag` is not a
+ *    sha256 and is not even an MD5 for a multipart object.
+ * 3. **`get` rejects with `ObjectNotFoundError`**, mapped from the several
+ *    shapes this family of services uses. A raw `NoSuchKey` escaping makes a
+ *    missing blob a 500 where the route means to answer 404.
  */
-function createS3StorageProvider(
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-config) {
-    // Implementations omit their params (the interface allows a narrower
-    // signature) — there is nothing to act on until the AWS adapter lands.
+function createS3StorageProvider(config) {
+    if (!config.bucket?.trim()) {
+        throw new Error('createS3StorageProvider requires a bucket. Set it in the host config, ' +
+            'e.g. `storage: { bucket: process.env.MEDIA_S3_BUCKET }`.');
+    }
+    const clientConfig = {
+        region: config.region ?? 'auto',
+        ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+        ...(config.forcePathStyle ? { forcePathStyle: true } : {}),
+        // Absent means "use the SDK's provider chain" — an instance role, IRSA,
+        // a shared config file. Passing an object with blank strings instead
+        // would shadow all of that with credentials that cannot sign.
+        ...(config.credentials ? { credentials: config.credentials } : {})
+    };
+    const client = config.client ?? new client_s3_1.S3Client(clientConfig);
+    const bucket = config.bucket;
+    const prefix = config.keyPrefix?.replace(/^\/+|\/+$/g, '');
+    const keyFor = (object) => [
+        prefix,
+        object.workspaceId,
+        object.assetId,
+        object.isVariant ? 'variants' : undefined,
+        sanitize(object.fileName)
+    ]
+        .filter(Boolean)
+        .join('/');
     return {
-        put() {
-            throw new S3NotImplementedError();
+        id: 's3',
+        capabilities: {
+            directUrl: true,
+            contentTypeMetadata: true,
+            streamingPut: true
+        },
+        async put(object) {
+            const storageKey = keyFor(object);
+            // Metered on the way through rather than buffered: an upload is
+            // bounded by `maxUploadBytes`, not by the heap, and `lib-storage`
+            // streams it in parts.
+            const hash = (0, node_crypto_1.createHash)('sha256');
+            let size = 0;
+            const meter = new node_stream_1.PassThrough();
+            meter.on('data', (chunk) => {
+                hash.update(chunk);
+                size += chunk.byteLength;
+            });
+            object.body.pipe(meter);
+            // A source that fails mid-stream must fail the upload, not stall
+            // it: `Upload` is waiting on a stream that will never end.
+            object.body.on('error', (error) => meter.destroy(error));
+            const upload = new lib_storage_1.Upload({
+                client,
+                partSize: PART_SIZE,
+                queueSize: QUEUE_SIZE,
+                params: {
+                    Bucket: bucket,
+                    Key: storageKey,
+                    Body: meter,
+                    // The object metadata is what makes `contentTypeMetadata`
+                    // true here and false for a filesystem. It is the
+                    // uploader's own claim, so the download route still
+                    // hardens the response; this only keeps the object
+                    // self-describing for anything reading the bucket directly.
+                    ContentType: object.contentType
+                }
+            });
+            try {
+                await upload.done();
+            }
+            catch (error) {
+                // Without this the failed multipart upload's parts sit in the
+                // bucket, billed, invisible to `ListObjects`, and unreachable:
+                // the key was never returned, so nothing can reclaim them.
+                await upload.abort().catch(() => undefined);
+                throw error;
+            }
+            return { storageKey, size, checksum: hash.digest('hex') };
+        },
+        async get(storageKey) {
+            try {
+                const response = await client.send(new client_s3_1.GetObjectCommand({ Bucket: bucket, Key: storageKey }));
+                if (!response.Body) {
+                    throw new media_server_1.ObjectNotFoundError(storageKey);
+                }
+                return response.Body;
+            }
+            catch (error) {
+                if (isMissing(error)) {
+                    throw new media_server_1.ObjectNotFoundError(storageKey, error);
+                }
+                throw error;
+            }
         },
-        get() {
-            throw new S3NotImplementedError();
+        async remove(storageKey) {
+            try {
+                await client.send(new client_s3_1.DeleteObjectCommand({ Bucket: bucket, Key: storageKey }));
+            }
+            catch (error) {
+                // S3 answers 204 for a key that was never there, so this is
+                // already idempotent — but a gateway that answers 404 instead
+                // must not turn a best-effort, post-commit reclaim into an
+                // error nobody can act on.
+                if (!isMissing(error))
+                    throw error;
+            }
         },
-        remove() {
-            throw new S3NotImplementedError();
+        async directUrl(storageKey, options) {
+            // The disposition and content type are **pinned on the URL**, not
+            // left to the object's metadata. A redirect discards the app's own
+            // `Content-Disposition`, `nosniff` and CSP, and `mime_type` is the
+            // uploader's unverified claim — so an uploaded `.html` served
+            // inline from the bucket would be stored XSS. These two response
+            // overrides are the whole reason this provider may declare
+            // `capabilities.directUrl`.
+            const fileName = options.fileName.replace(/"/g, '');
+            return (0, s3_request_presigner_1.getSignedUrl)(client, new client_s3_1.GetObjectCommand({
+                Bucket: bucket,
+                Key: storageKey,
+                ResponseContentDisposition: `${options.disposition}; filename="${fileName}"`,
+                ResponseContentType: options.contentType
+            }), { expiresIn: options.expiresInSeconds });
         },
-        url() {
-            throw new S3NotImplementedError();
+        async verify() {
+            // One HEAD at boot. A wrong bucket, a dead endpoint or an expired
+            // key fails the start instead of the first upload, hours later,
+            // with nothing in the message naming the cause.
+            await client.send(new client_s3_1.HeadBucketCommand({ Bucket: bucket }));
         }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@orthacms/media-provider-s3",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "@orthacms/media-provider-s3 — part of Ortha CMS.",
     "license": "MIT",
     "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/media/provider-s3",
@@ -25,7 +25,10 @@
         "dist"
     ],
     "dependencies": {
-        "@orthacms/media-server": "^0.3.0",
+        "@aws-sdk/client-s3": "^3.716.0",
+        "@aws-sdk/lib-storage": "^3.716.0",
+        "@aws-sdk/s3-request-presigner": "^3.716.0",
+        "@orthacms/media-server": "^0.4.0",
         "tslib": "^2.3.0"
     },
     "publishConfig": {