ocel 0.0.1-alpha.1 → 0.0.1

package/dist/bucket/objects.js

@@ -0,0 +1,350 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { SignedAudience, SignedOperation, } from "../gen/proto/app/bucket/v1/bucket_pb.js";
+import { ObjectNotFoundError, PreconditionFailedError } from "./errors.js";
+const singleRequestCeiling = 16 * 1024 * 1024;
+const partSize = 8 * 1024 * 1024;
+const partsInFlight = 4;
+function info(wire, key) {
+    return {
+        key: wire?.key || key,
+        size: Number(wire?.size ?? 0n),
+        etag: wire?.etag ?? "",
+        contentType: wire?.contentType ?? "",
+        uploadedAt: wire?.uploadedAt ? timestampDate(wire.uploadedAt) : undefined,
+        metadata: wire?.metadata ?? {},
+    };
+}
+function timestampDate(ts) {
+    return new Date(Number(ts.seconds) * 1000 + Math.floor(ts.nanos / 1_000_000));
+}
+function refused(key, status) {
+    if (status === 404)
+        return new ObjectNotFoundError(key);
+    if (status === 412 || status === 409)
+        return new PreconditionFailedError(key);
+    return undefined;
+}
+function wireRefusal(key, error) {
+    if (error instanceof ConnectError) {
+        if (error.code === Code.NotFound)
+            return new ObjectNotFoundError(key);
+        if (error.code === Code.FailedPrecondition)
+            return new PreconditionFailedError(key);
+    }
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        if (code === Code.NotFound)
+            return new ObjectNotFoundError(key);
+        if (code === Code.FailedPrecondition)
+            return new PreconditionFailedError(key);
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+async function sized(body) {
+    if (typeof body === "string")
+        return { bytes: new TextEncoder().encode(body) };
+    if (body instanceof Uint8Array)
+        return { bytes: body };
+    if (typeof Blob !== "undefined" && body instanceof Blob) {
+        return body.size <= singleRequestCeiling
+            ? { bytes: new Uint8Array(await body.arrayBuffer()) }
+            : { stream: body.stream() };
+    }
+    return { stream: body };
+}
+async function* chunked(stream, size) {
+    const reader = stream.getReader();
+    let buffered = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (value) {
+                buffered.push(value);
+                length += value.byteLength;
+            }
+            while (length >= size) {
+                const joined = concat(buffered, length);
+                yield joined.subarray(0, size);
+                const rest = joined.subarray(size);
+                buffered = rest.byteLength > 0 ? [rest] : [];
+                length = rest.byteLength;
+            }
+            if (done)
+                break;
+        }
+        if (length > 0)
+            yield concat(buffered, length);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+function concat(chunks, length) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(length);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}
+/** Builds the object operations against a resolved runtime context. */
+export function createObjects(deps) {
+    const send = deps.fetch ?? ((...args) => globalThis.fetch(...args));
+    const sign = async (key, operation, audience, constraints) => {
+        const { client, bucket } = deps.runtime();
+        const res = await client.sign({
+            bucket,
+            key,
+            operation,
+            audience,
+            expiresIn: constraints?.expiresIn
+                ? { seconds: BigInt(constraints.expiresIn), nanos: 0 }
+                : undefined,
+            constraints: {
+                contentType: constraints?.contentType ?? "",
+                maxSize: BigInt(constraints?.maxSize ?? 0),
+                downloadFilename: constraints?.downloadFilename ?? "",
+                ifNoneMatch: constraints?.ifNoneMatch ?? "",
+                ifMatch: constraints?.ifMatch ?? "",
+                cacheControl: constraints?.cacheControl ?? "",
+                metadata: constraints?.metadata ?? {},
+            },
+        });
+        const target = res.target;
+        if (!target)
+            throw new Error(`the runtime signed nothing for "${key}"`);
+        return target;
+    };
+    const putSingle = async (key, bytes, options) => {
+        const target = await sign(key, SignedOperation.PUT, SignedAudience.INTERNAL, {
+            contentType: options.contentType,
+            ifNoneMatch: options.ifNoneMatch,
+            ifMatch: options.ifMatch,
+            cacheControl: options.cacheControl,
+            metadata: options.metadata,
+        });
+        const headers = { ...target.headers };
+        if (options.contentType)
+            headers["content-type"] = options.contentType;
+        if (options.cacheControl)
+            headers["cache-control"] = options.cacheControl;
+        if (options.ifNoneMatch)
+            headers["if-none-match"] = options.ifNoneMatch;
+        if (options.ifMatch)
+            headers["if-match"] = options.ifMatch;
+        const res = await send(target.url, {
+            method: target.method || "PUT",
+            body: bytes,
+            headers,
+            signal: options.signal,
+        });
+        if (!res.ok) {
+            throw refused(key, res.status) ?? new Error(`writing "${key}" was refused (${res.status})`);
+        }
+    };
+    const putMultipart = async (key, parts, options) => {
+        const { client, bucket } = deps.runtime();
+        const { uploadId } = await client.createMultipart({
+            bucket,
+            key,
+            contentType: options.contentType ?? "",
+            cacheControl: options.cacheControl ?? "",
+            metadata: options.metadata ?? {},
+        });
+        const completed = [];
+        const inFlight = new AbortController();
+        const giveUp = () => inFlight.abort();
+        options.signal?.addEventListener("abort", giveUp);
+        let next = 1;
+        try {
+            for (;;) {
+                const batch = [];
+                while (batch.length < partsInFlight) {
+                    const { done, value } = await parts.next();
+                    if (done)
+                        break;
+                    batch.push({ partNumber: next++, bytes: value });
+                }
+                if (batch.length === 0)
+                    break;
+                const signed = await client.signParts({
+                    bucket,
+                    key,
+                    uploadId,
+                    partNumbers: batch.map((part) => part.partNumber),
+                    audience: SignedAudience.INTERNAL,
+                });
+                const byNumber = new Map(signed.parts.map((part) => [part.partNumber, part]));
+                await Promise.all(batch.map(async (part) => {
+                    const target = byNumber.get(part.partNumber);
+                    if (!target)
+                        throw new Error(`the runtime signed no url for part ${part.partNumber}`);
+                    const res = await send(target.url, {
+                        method: "PUT",
+                        body: part.bytes,
+                        headers: { ...target.headers },
+                        signal: inFlight.signal,
+                    });
+                    if (!res.ok) {
+                        throw new Error(`part ${part.partNumber} of "${key}" was refused (${res.status})`);
+                    }
+                    completed.push({
+                        partNumber: part.partNumber,
+                        etag: res.headers.get("etag") ?? "",
+                    });
+                }));
+            }
+            completed.sort((a, b) => a.partNumber - b.partNumber);
+            await client.completeMultipart({
+                bucket,
+                key,
+                uploadId,
+                parts: completed,
+                ifNoneMatch: options.ifNoneMatch ?? "",
+                ifMatch: options.ifMatch ?? "",
+            });
+        }
+        catch (error) {
+            inFlight.abort();
+            await parts.return(undefined).catch(() => { });
+            await client.abortMultipart({ bucket, key, uploadId }).catch(() => { });
+            throw wireRefusal(key, error);
+        }
+        finally {
+            options.signal?.removeEventListener("abort", giveUp);
+        }
+    };
+    const head = async (key) => {
+        const { client, bucket } = deps.runtime();
+        const res = await client.head({ bucket, key });
+        return res.object ? info(res.object, key) : null;
+    };
+    return {
+        async put(key, body, options = {}) {
+            const source = await sized(body);
+            if (source.bytes && source.bytes.byteLength <= singleRequestCeiling) {
+                await putSingle(key, source.bytes, options);
+            }
+            else {
+                const stream = source.stream ??
+                    new ReadableStream({
+                        start(controller) {
+                            controller.enqueue(source.bytes);
+                            controller.close();
+                        },
+                    });
+                await putMultipart(key, chunked(stream, partSize), options);
+            }
+            const stored = await head(key);
+            if (!stored)
+                throw new ObjectNotFoundError(key);
+            return stored;
+        },
+        async get(key, options = {}) {
+            const stored = await head(key);
+            if (!stored)
+                return null;
+            const target = await sign(key, SignedOperation.GET, SignedAudience.INTERNAL);
+            const headers = {};
+            if (options.range) {
+                const { offset, length } = options.range;
+                headers.range = `bytes=${offset}-${length === undefined ? "" : offset + length - 1}`;
+            }
+            const res = await send(target.url, { headers });
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`reading "${key}" was refused (${res.status})`);
+            const body = res.body;
+            return {
+                info: stored,
+                body,
+                text: () => new Response(body).text(),
+                json: () => new Response(body).json(),
+                bytes: async () => new Uint8Array(await new Response(body).arrayBuffer()),
+            };
+        },
+        head,
+        async delete(key) {
+            const { client, bucket } = deps.runtime();
+            const keys = Array.isArray(key) ? key : [key];
+            if (keys.length === 0)
+                return;
+            await client.delete({ bucket, keys });
+        },
+        list(options = {}) {
+            const page = async ({ cursor } = {}) => {
+                const { client, bucket } = deps.runtime();
+                const res = await client.list({
+                    bucket,
+                    prefix: options.prefix ?? "",
+                    limit: options.limit ?? 0,
+                    cursor: cursor ?? "",
+                });
+                return {
+                    objects: res.objects.map((entry) => info(entry, entry.key)),
+                    cursor: res.nextCursor,
+                };
+            };
+            return {
+                page,
+                async *[Symbol.asyncIterator]() {
+                    let cursor;
+                    for (;;) {
+                        const listed = await page({ cursor });
+                        yield* listed.objects;
+                        if (!listed.cursor)
+                            return;
+                        cursor = listed.cursor;
+                    }
+                },
+            };
+        },
+        async copy(source, destination) {
+            const { client, bucket } = deps.runtime();
+            try {
+                const res = await client.copy({ bucket, sourceKey: source, destinationKey: destination });
+                return info(res.object, destination);
+            }
+            catch (error) {
+                throw wireRefusal(source, error);
+            }
+        },
+        async signedUrl(key, options = {}) {
+            const target = await sign(key, SignedOperation.GET, SignedAudience.EXTERNAL, {
+                expiresIn: options.expiresIn,
+                downloadFilename: typeof options.download === "string"
+                    ? options.download
+                    : options.download
+                        ? key.split("/").pop()
+                        : undefined,
+            });
+            return target.url;
+        },
+        async signedUpload(key, options = {}) {
+            const target = await sign(key, SignedOperation.POST_UPLOAD, SignedAudience.EXTERNAL, {
+                expiresIn: options.expiresIn,
+                maxSize: options.maxSize,
+                contentType: options.contentType,
+            });
+            return {
+                url: target.url,
+                method: target.method || "POST",
+                headers: target.headers,
+                fields: target.fields,
+            };
+        },
+        publicUrl(key) {
+            const { publicBaseUrl } = deps.runtime();
+            if (!publicBaseUrl) {
+                throw new Error(`this bucket has no public address, so "${key}" has no public url: declare the bucket with \`public: true\` and give the project a domain to serve it from`);
+            }
+            const path = key.split("/").map(encodeURIComponent).join("/");
+            return `${publicBaseUrl.replace(/\/$/, "")}/${path}`;
+        },
+    };
+}

package/dist/bucket/route.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage } from "node:http";
+import type { Bucket } from "./bucket.js";
+import { type BucketContext } from "./bucket-context.js";
+import type { UploadRequest } from "./types.js";
+export type RouteRequest = UploadRequest | IncomingMessage;
+export interface RouteOptions {
+    runtime?: BucketContext;
+}
+export interface RouteHandlers {
+    GET: (req: RouteRequest) => Promise<Response>;
+    POST: (req: RouteRequest, middlewareReq?: unknown) => Promise<Response>;
+}
+export declare function createRouteHandler(bucket: Bucket, options?: RouteOptions): RouteHandlers;

package/dist/bucket/route.js

@@ -0,0 +1,247 @@
+import { z } from "zod";
+import { UploadState } from "../gen/proto/app/bucket/v1/bucket_pb.js";
+import { resolveBucketContext } from "./bucket-context.js";
+import { generateKey } from "./keys.js";
+import { decodeMetadata, encodeMetadata } from "./metadata.js";
+function isWebRequest(req) {
+    return typeof req.json === "function";
+}
+function headerOf(req, name) {
+    const headers = req.headers;
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    const value = headers[name.toLowerCase()];
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+function requestUrl(req) {
+    const raw = req.url ?? "/";
+    if (/^https?:\/\//i.test(raw))
+        return raw;
+    const proto = headerOf(req, "x-forwarded-proto") ?? "http";
+    const host = headerOf(req, "host") ?? "localhost";
+    return `${proto}://${host}${raw}`;
+}
+async function requestJson(req) {
+    if (isWebRequest(req))
+        return req.json();
+    const node = req;
+    if (node.body !== undefined)
+        return node.body;
+    if (node.readableEnded || node.complete)
+        return {};
+    const chunks = [];
+    for await (const chunk of node)
+        chunks.push(chunk);
+    const text = Buffer.concat(chunks).toString("utf8");
+    return text ? JSON.parse(text) : {};
+}
+const presignBody = z.object({
+    uploader: z.string(),
+    files: z.array(z.object({
+        name: z.string(),
+        size: z.number().int().nonnegative(),
+        mimeType: z.string(),
+    })),
+    input: z.unknown().optional(),
+});
+const completeBody = z.object({
+    sessionId: z.string().min(1),
+});
+const callbackBody = z.object({
+    sessionId: z.string(),
+    signature: z.string(),
+    file: z.object({
+        key: z.string(),
+        name: z.string(),
+        size: z.number().int().nonnegative(),
+        mimeType: z.string(),
+    }),
+});
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+function resolveLimit(value, metadata) {
+    if (typeof value === "function") {
+        return value({ metadata });
+    }
+    return value;
+}
+function mimeMatches(patterns, mimeType) {
+    return patterns.some((p) => {
+        if (p === "*/*" || p === "*")
+            return true;
+        if (p.endsWith("/*"))
+            return mimeType.startsWith(`${p.slice(0, -1)}`);
+        return p === mimeType;
+    });
+}
+function validateFiles(up, files, metadata) {
+    const maxCount = resolveLimit(up.upload.limits?.maxFileCount, metadata);
+    const minCount = resolveLimit(up.upload.limits?.minFileCount, metadata);
+    const maxSize = resolveLimit(up.upload.limits?.maxFileSize, metadata);
+    if (files.length === 0)
+        return "no files provided";
+    if (maxCount !== undefined && files.length > maxCount) {
+        return `too many files (max ${maxCount})`;
+    }
+    if (minCount !== undefined && files.length < minCount) {
+        return `too few files (min ${minCount})`;
+    }
+    for (const file of files) {
+        if (up.upload.accept && !mimeMatches(up.upload.accept, file.mimeType)) {
+            return `file type '${file.mimeType}' is not accepted`;
+        }
+        if (maxSize !== undefined && file.size > maxSize) {
+            return `file '${file.name}' exceeds max size ${maxSize}`;
+        }
+    }
+    return undefined;
+}
+function deriveCallbackBaseUrl(req) {
+    const u = new URL(requestUrl(req));
+    return `${u.origin}${u.pathname}`;
+}
+function opOf(req) {
+    return new URL(requestUrl(req)).searchParams.get("op");
+}
+function stateToString(state) {
+    switch (state) {
+        case UploadState.SUCCEEDED:
+            return "succeeded";
+        case UploadState.EXPIRED:
+            return "expired";
+        default:
+            return "pending";
+    }
+}
+async function handlePresign(bucket, ctx, req, middlewareReq) {
+    const parsed = presignBody.safeParse(await requestJson(req));
+    if (!parsed.success)
+        return json({ error: "invalid presign request" }, 400);
+    const up = bucket.uploaders[parsed.data.uploader];
+    if (!up) {
+        return json({ error: `unknown uploader '${parsed.data.uploader}'` }, 404);
+    }
+    let input;
+    if (up.auth.input) {
+        const validated = up.auth.input.safeParse(parsed.data.input);
+        if (!validated.success)
+            return json({ error: "invalid input" }, 400);
+        input = validated.data;
+    }
+    let metadata;
+    try {
+        metadata = await up.auth.middleware({ req: middlewareReq, input });
+    }
+    catch (err) {
+        return json({ error: errorMessage(err, "unauthorized") }, 401);
+    }
+    const files = parsed.data.files;
+    const invalid = validateFiles(up, files, metadata);
+    if (invalid)
+        return json({ error: invalid }, 400);
+    const presignFiles = files.map((file) => ({
+        key: generateKey(up.upload.path, { file, metadata }),
+        name: file.name,
+        size: BigInt(file.size),
+        mimeType: file.mimeType,
+    }));
+    const res = await ctx.client.presignUpload({
+        bucket: ctx.bucket,
+        files: presignFiles,
+        metadata: encodeMetadata({ uploader: parsed.data.uploader, metadata }),
+        contentDisposition: up.upload.contentDisposition ?? "",
+        callbackBaseUrl: deriveCallbackBaseUrl(req),
+    });
+    return json({
+        sessionId: res.sessionId,
+        files: res.files.map((t) => ({
+            url: t.url,
+            key: t.key,
+            name: t.name,
+            contentDisposition: t.contentDisposition || undefined,
+            headers: t.headers && Object.keys(t.headers).length > 0 ? t.headers : undefined,
+            method: t.method || undefined,
+            fields: t.fields && Object.keys(t.fields).length > 0 ? t.fields : undefined,
+        })),
+    });
+}
+async function handleCallback(bucket, ctx, req) {
+    const parsed = callbackBody.safeParse(await requestJson(req));
+    if (!parsed.success)
+        return json({ error: "invalid callback request" }, 400);
+    const { sessionId, signature, file } = parsed.data;
+    const verify = await ctx.client.verifyUploadSignature({
+        sessionId,
+        signature,
+        file: {
+            key: file.key,
+            name: file.name,
+            size: BigInt(file.size),
+            mimeType: file.mimeType,
+        },
+    });
+    if (!verify.valid)
+        return json({ error: "invalid signature" }, 401);
+    const envelope = decodeMetadata(verify.metadata);
+    const up = bucket.uploaders[envelope.uploader];
+    if (!up)
+        return json({ error: `unknown uploader "${envelope.uploader}"` }, 404);
+    const completed = {
+        key: file.key,
+        name: file.name,
+        size: file.size,
+        mimeType: file.mimeType,
+        path: file.key,
+    };
+    await up.upload.onUploadComplete?.({
+        metadata: envelope.metadata,
+        file: completed,
+    });
+    return json({ ok: true });
+}
+async function handleComplete(ctx, sessionId) {
+    if (!sessionId)
+        return json({ error: "missing sessionId" }, 400);
+    const res = await ctx.client.completeUpload({ sessionId });
+    return json({
+        state: stateToString(res.state),
+        error: res.error || undefined,
+    });
+}
+function sessionOf(req) {
+    return new URL(requestUrl(req)).searchParams.get("sessionId");
+}
+function errorMessage(err, fallback) {
+    return err instanceof Error && err.message ? err.message : fallback;
+}
+export function createRouteHandler(bucket, options = {}) {
+    let ctx = options.runtime;
+    const getCtx = () => (ctx ??= resolveBucketContext(bucket));
+    async function POST(req, middlewareReq) {
+        const op = opOf(req);
+        if (op === "presign") {
+            return handlePresign(bucket, getCtx(), req, middlewareReq ?? req);
+        }
+        if (op === "callback")
+            return handleCallback(bucket, getCtx(), req);
+        if (op === "complete") {
+            const body = completeBody.safeParse(await requestJson(req));
+            return handleComplete(getCtx(), body.success ? body.data.sessionId : sessionOf(req));
+        }
+        return json({ error: `unknown op '${op}'` }, 400);
+    }
+    async function GET(req) {
+        const op = opOf(req);
+        if (op === "poll" || op === "complete")
+            return handleComplete(getCtx(), sessionOf(req));
+        return json({ error: `unknown op '${op}'` }, 400);
+    }
+    return { GET, POST };
+}

package/dist/bucket/server-only.js

@@ -0,0 +1,5 @@
+const host = globalThis;
+if (host.window !== undefined && host.window.document !== undefined) {
+    throw new Error("ocel/bucket/next reaches this deployment's runtime with its session token, so it may only be imported by server code. Import ocel/bucket/client from a Client Component instead.");
+}
+export {};

package/dist/bucket/types.d.ts

@@ -0,0 +1,63 @@
+import type { z } from "zod";
+export type MaybePromise<T> = T | Promise<T>;
+export type UploadStatusState = "pending" | "succeeded" | "expired";
+export interface UploadRequest {
+    readonly url: string;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}
+export interface FileInfo {
+    name: string;
+    size: number;
+    mimeType: string;
+}
+export interface CompletedFile {
+    key: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    path: string;
+}
+export type ParsedInput<TInput> = TInput extends z.ZodType ? z.infer<TInput> : undefined;
+export type LimitValue<TMetadata, T> = T | ((ctx: {
+    metadata: TMetadata;
+}) => T);
+export interface Limits<TMetadata> {
+    maxFileSize?: LimitValue<TMetadata, number>;
+    maxFileCount?: LimitValue<TMetadata, number>;
+    minFileCount?: LimitValue<TMetadata, number>;
+}
+export interface StructuredPath {
+    prefix?: string;
+    randomSuffix?: boolean;
+}
+export type PathFn<TMetadata> = (ctx: {
+    file: FileInfo;
+    metadata: TMetadata;
+}) => string;
+export type PathConfig<TMetadata> = StructuredPath | PathFn<TMetadata>;
+export interface UploaderAuth<TReq, TInput extends z.ZodType | undefined, TMetadata> {
+    input?: TInput;
+    middleware: (ctx: {
+        req: TReq;
+        input: ParsedInput<TInput>;
+    }) => MaybePromise<TMetadata>;
+}
+export interface UploaderUpload<TMetadata> {
+    accept?: string[];
+    limits?: Limits<TMetadata>;
+    path?: PathConfig<TMetadata>;
+    contentDisposition?: string;
+    onUploadComplete?: (ctx: {
+        metadata: TMetadata;
+        file: CompletedFile;
+    }) => MaybePromise<void>;
+}
+export interface Uploader<TInputParsed = unknown, TMetadata = unknown, TReq = UploadRequest> {
+    readonly auth: UploaderAuth<TReq, z.ZodType | undefined, TMetadata>;
+    readonly upload: UploaderUpload<TMetadata>;
+    readonly __input?: TInputParsed;
+}
+export type AnyUploader = Uploader<any, any, any>;

package/dist/bucket/uploader.d.ts

@@ -0,0 +1,3 @@
+import type { z } from "zod";
+import type { ParsedInput, Uploader, UploaderAuth, UploaderUpload, UploadRequest } from "./types.js";
+export declare function uploader<TInput extends z.ZodType | undefined = undefined, TMetadata = unknown, TReq = UploadRequest>(auth: UploaderAuth<TReq, TInput, TMetadata>, upload?: UploaderUpload<TMetadata>): Uploader<ParsedInput<TInput>, TMetadata, TReq>;

package/dist/bucket/uploader.js

@@ -0,0 +1,6 @@
+export function uploader(auth, upload = {}) {
+    return {
+        auth: auth,
+        upload,
+    };
+}