Writing a storage provider

import type { Readable } from 'node:stream';

interface StorageProvider {
    readonly id: string;                        // stored on every asset row
    readonly capabilities: StorageCapabilities;
    put(object: PutObject): Promise<StoredObject>;
    get(storageKey: string): Promise<Readable>;
    remove(storageKey: string): Promise<void>;
    directUrl?(storageKey: string, options: DirectUrlOptions): Promise<string>;
    verify?(): Promise<void>;                   // run at boot; a throw refuses the start
}

interface StorageCapabilities {
    directUrl: boolean;            // can sign a short-lived URL with pinned headers
    contentTypeMetadata: boolean;  // can store a content type with the bytes
    streamingPut: boolean;         // streams the body rather than buffering it
}

interface PutObject {
    workspaceId: string;
    assetId: string;
    fileName: string;
    contentType: string;
    body: Readable;
    isVariant?: boolean;           // a derivative (thumb, preview)
}

interface StoredObject {
    storageKey: string;            // you choose it
    size: number;                  // bytes actually written
    checksum: string;              // hex sha256 of what was written
}

interface DirectUrlOptions {
    disposition: 'inline' | 'attachment';
    fileName: string;
    contentType: string;
    expiresInSeconds: number;
}

// packages/media-provider-http-store/src/http-store-provider.ts
import { createHash } from 'node:crypto';
import { Readable } from 'node:stream';
import type { ReadableStream as WebReadableStream } from 'node:stream/web';
import {
    ObjectNotFoundError,
    type PutObject,
    type StorageProvider,
    type StoredObject
} from '@orthacms/media-domain';

export interface HttpStoreConfig {
    baseUrl: string;                    // e.g. https://objects.acme.example/cms
    token: string;
    keyPrefix?: string;
    fetch?: typeof globalThis.fetch;    // test seam
}

// One safe path segment from an uploader-supplied file name.
const sanitize = (name: string): string =>
    name.replace(/[^\w.-]+/g, '_').replace(/^\.+/, '') || 'file';

export function createHttpStoreProvider(config: HttpStoreConfig): StorageProvider {
    const doFetch = config.fetch ?? globalThis.fetch;
    const base = config.baseUrl.replace(/\/+$/, '');
    const prefix = config.keyPrefix?.replace(/^\/+|\/+$/g, '');
    const auth = { authorization: `Bearer ${config.token}` };
    const urlFor = (key: string) =>
        `${base}/${key.split('/').map(encodeURIComponent).join('/')}`;

    const keyFor = (object: PutObject): string =>
        [
            prefix,
            object.workspaceId,
            object.assetId,
            object.isVariant ? 'variants' : undefined, // derivatives never collide with originals
            sanitize(object.fileName)
        ]
            .filter(Boolean)
            .join('/');

    return {
        id: 'http-store',
        capabilities: { directUrl: false, contentTypeMetadata: true, streamingPut: false },

        async put(object: PutObject): Promise<StoredObject> {
            const storageKey = keyFor(object);

            // Buffer and meter first. A body that fails mid-stream rejects
            // here, before anything is written: all-or-nothing by construction.
            const hash = createHash('sha256');
            const chunks: Buffer[] = [];
            for await (const chunk of object.body) {
                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
                hash.update(buffer);
                chunks.push(buffer);
            }
            const bytes = Buffer.concat(chunks);

            const response = await doFetch(urlFor(storageKey), {
                method: 'PUT',
                headers: { ...auth, 'content-type': object.contentType },
                body: bytes
            });
            if (!response.ok) {
                // Remove any partial write: the key is never returned to a caller.
                await doFetch(urlFor(storageKey), { method: 'DELETE', headers: auth }).catch(
                    () => undefined
                );
                throw new Error(`http-store refused ${storageKey}: HTTP ${response.status}`);
            }
            return { storageKey, size: bytes.length, checksum: hash.digest('hex') };
        },

        async get(storageKey: string): Promise<Readable> {
            const response = await doFetch(urlFor(storageKey), { headers: auth });
            if (response.status === 404) {
                throw new ObjectNotFoundError(storageKey); // before any byte flows
            }
            if (!response.ok || !response.body) {
                // Not "not found": an outage must not be dressed as a 404.
                throw new Error(`http-store could not read ${storageKey}: HTTP ${response.status}`);
            }
            return Readable.fromWeb(response.body as unknown as WebReadableStream);
        },

        async remove(storageKey: string): Promise<void> {
            const response = await doFetch(urlFor(storageKey), { method: 'DELETE', headers: auth });
            if (!response.ok && response.status !== 404) {
                throw new Error(`http-store could not remove ${storageKey}: HTTP ${response.status}`);
            }
        },

        async verify(): Promise<void> {
            const response = await doFetch(`${base}/`, { method: 'HEAD', headers: auth });
            if (!response.ok) {
                throw new Error(`http-store at ${base} refused the token: HTTP ${response.status}`);
            }
        }
    };
}

npm install --save-dev @orthacms/media-provider-testkit

// packages/media-provider-http-store/src/http-store-provider.spec.ts
import { describeStorageProvider } from '@orthacms/media-provider-testkit';
import { createHttpStoreProvider } from './http-store-provider';

// An in-memory stand-in for the HTTP object store.
function fakeStore() {
    const objects = new Map<string, Uint8Array>();
    const fetch = (async (input: string | URL | Request, init: RequestInit = {}) => {
        const key = decodeURIComponent(new URL(String(input)).pathname.replace(/^\/cms\/?/, ''));
        switch (init.method ?? 'GET') {
            case 'PUT':
                objects.set(key, new Uint8Array(init.body as Uint8Array));
                return new Response(null, { status: 201 });
            case 'DELETE':
                return new Response(null, { status: objects.delete(key) ? 204 : 404 });
            case 'HEAD':
                return new Response(null, { status: 200 });
            default: {
                const bytes = objects.get(key);
                return bytes ? new Response(bytes) : new Response(null, { status: 404 });
            }
        }
    }) as typeof globalThis.fetch;
    return { fetch, objects };
}

let store = fakeStore();

describeStorageProvider('http-store', {
    create: () => {
        store = fakeStore();
        return createHttpStoreProvider({
            baseUrl: 'https://objects.test/cms',
            token: 'test-token',
            fetch: store.fetch
        });
    },
    storedKeys: () => [...store.objects.keys()]
});

// apps/server/src/plugins.ts
import { createHttpStoreProvider } from '@acme/media-provider-http-store';

MediaServerPlugin({
    provider: createHttpStoreProvider({
        baseUrl: process.env.MEDIA_HTTP_STORE_URL!,
        token: process.env.MEDIA_HTTP_STORE_TOKEN!
    }),
    config: config.plugins.media
});