@fungi.computer/burrow 0.0.0-stage → 0.0.1

package/dist/cloudflare.js

@@ -0,0 +1,595 @@
+/// <reference types="@cloudflare/workers-types" />
+import { listServerRefs } from "isomorphic-git";
+import http from "isomorphic-git/http/web";
+import * as Exit from "effect/Exit";
+import * as Schema from "effect/Schema";
+const artifactsErrorSchema = Schema.Struct({
+    code: Schema.Literals([
+        "NOT_FOUND",
+        "ALREADY_EXISTS",
+        "IMPORT_IN_PROGRESS",
+        "FORK_IN_PROGRESS",
+    ]),
+});
+const REPOSITORY_NAME = /^[a-zA-Z0-9._-]{1,128}$/;
+const REMOTE_PATH = /^\/git\/([a-zA-Z0-9._-]+)\/([a-zA-Z0-9._-]+)\.git$/;
+const RESPONSE_HEADERS = ["cache-control", "content-type", "pragma"];
+const REPOSITORY_READY_POLL_INTERVAL_MS = 500;
+const REPOSITORY_READY_TIMEOUT_MS = 120_000;
+const REPOSITORY_METADATA_RETRY_DELAYS_MS = [
+    20, 40, 80, 160, 320, 640, 800,
+];
+const repositoryStatusPageSchema = Schema.Struct({
+    repos: Schema.Array(Schema.Struct({
+        name: Schema.String,
+        status: Schema.Literals(["ready", "importing", "forking"]),
+    })),
+    total: Schema.Number,
+    cursor: Schema.optional(Schema.String),
+});
+/** A repository did not finish importing or forking within the readiness window. */
+export class ArtifactsForkStuckError extends Error {
+    repository;
+    status;
+    name = "ArtifactsForkStuckError";
+    constructor(repository, status) {
+        super(`Artifacts repository ${repository} did not become ready (${status})`);
+        this.repository = repository;
+        this.status = status;
+    }
+}
+async function readRepositoryStatus(binding, name) {
+    let cursor;
+    do {
+        const options = cursor === undefined ? { limit: 200 } : { limit: 200, cursor };
+        const raw = await binding.list(options);
+        const page = Schema.decodeUnknownSync(repositoryStatusPageSchema)(raw);
+        const repository = page.repos.find((item) => item.name === name);
+        if (repository)
+            return repository.status;
+        cursor = page.cursor;
+    } while (cursor !== undefined);
+    return "missing";
+}
+async function repositoryHandleWhenReady(binding, name) {
+    const deadline = Date.now() + REPOSITORY_READY_TIMEOUT_MS;
+    let status = "missing";
+    while (Date.now() < deadline) {
+        status = await readRepositoryStatus(binding, name);
+        if (status === "ready" || status === "missing") {
+            try {
+                const repository = await binding.get(name);
+                // Workers get resolves the repository; REST get only addresses it.
+                // Metadata promotion requires the latter's live provider check.
+                if (repository.info !== undefined)
+                    await repository.info();
+                return repository;
+            }
+            catch (error) {
+                const code = error instanceof Error ? artifactsErrorCode(error) : undefined;
+                // Namespace listing and handle availability can disagree during a fork.
+                // Only the provider's documented readiness refusals extend this wait;
+                // NOT_FOUND still allows ordinary repository discovery to create it.
+                if (code === "FORK_IN_PROGRESS")
+                    status = "forking";
+                else if (code === "IMPORT_IN_PROGRESS")
+                    status = "importing";
+                else
+                    throw error;
+            }
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(REPOSITORY_READY_POLL_INTERVAL_MS, remaining)));
+    }
+    throw new ArtifactsForkStuckError(name, status);
+}
+function repositoryName(name) {
+    if (!REPOSITORY_NAME.test(name))
+        throw new TypeError("Invalid repository name");
+    return name;
+}
+function repositoryMetadata(repository, parentRepository) {
+    if (repository.id.length === 0 ||
+        !REPOSITORY_NAME.test(repository.name) ||
+        repository.defaultBranch !== "main")
+        throw new Error("Artifacts repository identity is invalid");
+    artifactsRemote(repository.remote, repository.name);
+    if (parentRepository !== null) {
+        repositoryName(parentRepository);
+        if (parentRepository === repository.name)
+            throw new Error("Artifacts repository parent identity is invalid");
+    }
+    return Object.freeze({
+        id: repository.id,
+        name: repository.name,
+        defaultBranch: repository.defaultBranch,
+        remote: repository.remote,
+        parentRepository,
+    });
+}
+function repositoryIdentity(repository) {
+    return Object.freeze({
+        id: repository.id,
+        name: repository.name,
+        defaultBranch: repository.defaultBranch,
+    });
+}
+function artifactsErrorCode(error) {
+    const decoded = Schema.decodeUnknownExit(artifactsErrorSchema)(error);
+    return Exit.isSuccess(decoded) ? decoded.value.code : undefined;
+}
+async function withRevokedInitialToken(options) {
+    let repository;
+    const operation = Promise.resolve().then(async () => {
+        repository = await options.lookup();
+        return options.use(repository);
+    });
+    const outcome = await operation.then((value) => ({ kind: "succeeded", value }), (error) => ({ kind: "failed", error }));
+    const revocation = await Promise.resolve()
+        .then(async () => {
+        // A transient read-back failure must not skip revocation. Retry the lookup
+        // in the cleanup path so a token returned by create/fork is still revoked.
+        const owner = repository ?? (await options.lookup());
+        if (!(await owner.revokeToken(options.token)))
+            throw new Error("Artifacts initial token could not be revoked");
+    })
+        .then(() => ({ kind: "revoked" }), (error) => ({ kind: "failed", error }));
+    if (outcome.kind === "failed") {
+        if (revocation.kind === "failed")
+            throw new AggregateError([outcome.error, revocation.error], "Artifacts operation failed and token cleanup failed");
+        if (outcome.error instanceof Error)
+            throw outcome.error;
+        throw new Error("Artifacts operation failed", { cause: outcome.error });
+    }
+    if (revocation.kind === "failed") {
+        if (revocation.error instanceof Error)
+            throw revocation.error;
+        throw new Error("Artifacts token cleanup failed", {
+            cause: revocation.error,
+        });
+    }
+    return outcome.value;
+}
+async function recordPendingWithRetry(repositories, metadata, initialToken) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await repositories.recordPending(metadata, initialToken);
+            return;
+        }
+        catch (error) {
+            const delayMs = REPOSITORY_METADATA_RETRY_DELAYS_MS[attempt];
+            if (delayMs === undefined)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+}
+async function finishPendingRepository(binding, repositories, name) {
+    const pending = await repositories.readPending(name);
+    if (pending === null)
+        return null;
+    const metadata = parseStoredMetadata(pending.metadata, name);
+    const repository = await repositoryHandleWhenReady(binding, name);
+    try {
+        // Maintained Workers types define false as "not found". Replay uses the
+        // persisted plaintext, so this concerns this exact token; unrelated repo
+        // tokens do not affect promotion.
+        await repository.revokeToken(pending.initialToken);
+    }
+    catch {
+        // The provider error may echo its argument; never attach this plaintext
+        // token-bearing failure as a cause that a caller might log.
+        throw new Error("Artifacts initial token cleanup could not be confirmed");
+    }
+    await repositories.activate(metadata, pending.initialToken);
+    return metadata;
+}
+async function readDefaultBranchHead(binding, repositories, name, gitHttp = http) {
+    const safeName = repositoryName(name);
+    const metadata = await requireRepositoryMetadata(binding, repositories, safeName);
+    const repository = await repositoryHandleWhenReady(binding, safeName);
+    const remote = artifactsRemote(metadata.remote, metadata.name).url;
+    const token = await repository.createToken("read", 60);
+    return withRevokedInitialToken({
+        lookup: () => Promise.resolve(repository),
+        token: token.id,
+        use: async () => {
+            const refs = await listServerRefs({
+                http: gitHttp,
+                url: remote.toString(),
+                headers: { Authorization: `Bearer ${token.plaintext}` },
+                prefix: "refs/heads/main",
+            });
+            const mainRefs = refs.filter((ref) => ref.ref === "refs/heads/main");
+            if (mainRefs.length === 0)
+                return null;
+            const [main] = mainRefs;
+            if (mainRefs.length !== 1 || !main || !/^[0-9a-f]{40}$/u.test(main.oid))
+                throw new Error("Artifacts main ref is ambiguous or invalid");
+            return main.oid;
+        },
+    });
+}
+async function readRefs(binding, repositories, name, gitHttp = http) {
+    const safeName = repositoryName(name);
+    const metadata = await requireRepositoryMetadata(binding, repositories, safeName);
+    const repository = await repositoryHandleWhenReady(binding, safeName);
+    const remote = artifactsRemote(metadata.remote, metadata.name).url;
+    const token = await repository.createToken("read", 60);
+    return withRevokedInitialToken({
+        lookup: () => Promise.resolve(repository),
+        token: token.id,
+        use: async () => {
+            const refs = await listServerRefs({
+                http: gitHttp,
+                url: remote.toString(),
+                headers: { Authorization: `Bearer ${token.plaintext}` },
+            });
+            return Object.freeze(refs.map(({ ref, oid }) => ({ name: ref, hash: oid })));
+        },
+    });
+}
+function artifactsRemote(remote, repository) {
+    let target;
+    try {
+        target = new URL(remote);
+    }
+    catch {
+        throw new TypeError("Artifacts returned an invalid Git remote");
+    }
+    const suffix = ".artifacts.cloudflare.net";
+    const account = target.hostname.toLowerCase().endsWith(suffix)
+        ? target.hostname.slice(0, -suffix.length)
+        : "";
+    const match = REMOTE_PATH.exec(target.pathname);
+    if (target.protocol !== "https:" ||
+        account.length === 0 ||
+        account.includes(".") ||
+        target.port.length > 0 ||
+        target.username.length > 0 ||
+        target.password.length > 0 ||
+        target.search.length > 0 ||
+        target.hash.length > 0 ||
+        !match?.[1] ||
+        match[2] !== repository)
+        throw new TypeError("Artifacts returned an invalid Git remote");
+    return { url: target, namespace: match[1] };
+}
+function parseStoredMetadata(metadata, expectedName) {
+    const parsed = repositoryMetadata(metadata, metadata.parentRepository);
+    if (parsed.name !== expectedName)
+        throw new Error("Artifacts repository metadata identity conflicts");
+    return parsed;
+}
+function sameRepositoryMetadata(left, right) {
+    return (left.id === right.id &&
+        left.name === right.name &&
+        left.defaultBranch === right.defaultBranch &&
+        left.remote === right.remote &&
+        left.parentRepository === right.parentRepository);
+}
+async function finishOrReadCreatedRepository(binding, repositories, expected) {
+    const finished = await finishPendingRepository(binding, repositories, expected.name);
+    const saved = finished ?? (await repositories.read(expected.name));
+    if (saved === null)
+        throw new Error("Artifacts repository creation was not recorded");
+    const verified = parseStoredMetadata(saved, expected.name);
+    if (!sameRepositoryMetadata(verified, expected))
+        throw new Error("Artifacts repository creation metadata conflicts");
+    await repositoryHandleWhenReady(binding, expected.name);
+    return verified;
+}
+async function knownRepositoryMetadata(binding, repositories, name) {
+    await finishPendingRepository(binding, repositories, name);
+    const stored = await repositories.read(name);
+    return stored === null ? null : parseStoredMetadata(stored, name);
+}
+async function existingRepositoryMetadata(binding, repositories, name) {
+    const stored = await knownRepositoryMetadata(binding, repositories, name);
+    if (stored !== null) {
+        await repositoryHandleWhenReady(binding, name);
+        return stored;
+    }
+    try {
+        await repositoryHandleWhenReady(binding, name);
+    }
+    catch (error) {
+        if (error instanceof Error && artifactsErrorCode(error) === "NOT_FOUND")
+            return null;
+        throw error;
+    }
+    return waitForRecordedRepositoryMetadata(binding, repositories, name);
+}
+async function requireRepositoryMetadata(binding, repositories, name) {
+    const known = await knownRepositoryMetadata(binding, repositories, name);
+    if (known !== null)
+        return known;
+    try {
+        await repositoryHandleWhenReady(binding, name);
+    }
+    catch (error) {
+        if (error instanceof Error && artifactsErrorCode(error) === "NOT_FOUND")
+            throw new Error("Artifacts repository metadata is unavailable", {
+                cause: error,
+            });
+        throw error;
+    }
+    return waitForRecordedRepositoryMetadata(binding, repositories, name);
+}
+async function waitForRecordedRepositoryMetadata(binding, repositories, name) {
+    for (const delayMs of REPOSITORY_METADATA_RETRY_DELAYS_MS) {
+        const metadata = await knownRepositoryMetadata(binding, repositories, name);
+        if (metadata !== null)
+            return metadata;
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    const metadata = await knownRepositoryMetadata(binding, repositories, name);
+    if (metadata !== null)
+        return metadata;
+    throw new Error("Artifacts repository creation race was not recorded");
+}
+function gitTarget(remote, repository, operation) {
+    const { url: target } = artifactsRemote(remote, repository);
+    const service = operation.startsWith("upload-pack")
+        ? "git-upload-pack"
+        : "git-receive-pack";
+    if (operation.endsWith("advertisement")) {
+        target.pathname += "/info/refs";
+        target.searchParams.set("service", service);
+    }
+    else {
+        target.pathname += `/${service}`;
+    }
+    return target;
+}
+function requestMethod(operation) {
+    return operation.endsWith("advertisement") ? "GET" : "POST";
+}
+function gitContentType(operation) {
+    if (operation === "upload-pack-advertisement")
+        return "application/x-git-upload-pack-advertisement";
+    if (operation === "receive-pack-advertisement")
+        return "application/x-git-receive-pack-advertisement";
+    if (operation === "upload-pack")
+        return "application/x-git-upload-pack-request";
+    return "application/x-git-receive-pack-request";
+}
+function gitAcceptType(operation) {
+    if (operation === "upload-pack-advertisement")
+        return "application/x-git-upload-pack-advertisement";
+    if (operation === "receive-pack-advertisement")
+        return "application/x-git-receive-pack-advertisement";
+    if (operation === "upload-pack")
+        return "application/x-git-upload-pack-result";
+    return "application/x-git-receive-pack-result";
+}
+function readScope(operation) {
+    return operation.startsWith("upload-pack") ? "read" : "write";
+}
+/** Execute Git with an already-held repo credential. The custody owner chooses
+ * metadata and credential; caller URLs and authorization headers never enter. */
+export async function exchangeCloudflareArtifactsGit(metadata, input, credential, gitFetch) {
+    const name = repositoryName(input.repository);
+    if (metadata.name !== name)
+        throw new Error("Artifacts repository mismatch");
+    const remote = gitTarget(metadata.remote, name, input.operation);
+    const method = requestMethod(input.operation);
+    const headers = new Headers({
+        authorization: `Bearer ${credential}`,
+        accept: gitAcceptType(input.operation),
+    });
+    if (method === "POST")
+        headers.set("content-type", gitContentType(input.operation) ?? "application/octet-stream");
+    if (input.protocol !== undefined)
+        headers.set("Git-Protocol", input.protocol);
+    const request = {
+        method,
+        headers,
+        redirect: "manual",
+        signal: input.signal ?? null,
+    };
+    if ("body" in input)
+        request.body = input.body;
+    const upstream = await gitFetch(remote, request);
+    if (upstream.status >= 300 && upstream.status < 400)
+        throw new Error("Artifacts Git upstream redirected");
+    return upstream;
+}
+async function exchange(binding, repositories, input, gitFetch = (input, init) => fetch(input, init)) {
+    const name = repositoryName(input.repository);
+    const metadata = await requireRepositoryMetadata(binding, repositories, name);
+    const repository = await repositoryHandleWhenReady(binding, name);
+    // Preserve the existing refusal before minting if registered metadata is invalid.
+    artifactsRemote(metadata.remote, name);
+    const token = await repository.createToken(readScope(input.operation), 300);
+    let revokePromise;
+    const revoke = () => {
+        revokePromise ??= repository.revokeToken(token.id).then((revoked) => {
+            if (!revoked)
+                throw new Error("Artifacts Git token could not be revoked");
+        });
+        return revokePromise;
+    };
+    try {
+        const upstream = await exchangeCloudflareArtifactsGit(metadata, input, token.plaintext, gitFetch);
+        const responseHeaders = new Headers();
+        for (const header of RESPONSE_HEADERS) {
+            const value = upstream.headers.get(header);
+            if (value !== null)
+                responseHeaders.set(header, value);
+        }
+        if (upstream.body === null) {
+            await revoke();
+            return new Response(null, {
+                status: upstream.status,
+                headers: responseHeaders,
+            });
+        }
+        const upstreamBody = upstream.body;
+        const reader = upstreamBody.getReader();
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const result = await reader.read();
+                    if (result.done) {
+                        controller.close();
+                        await revoke();
+                    }
+                    else {
+                        controller.enqueue(result.value);
+                    }
+                }
+                catch (error) {
+                    const cancellation = await reader.cancel(error).then(() => ({ kind: "cancelled" }), (cancelError) => cancelError === error
+                        ? { kind: "same-error" }
+                        : { kind: "failed", error: cancelError });
+                    const revocation = await revoke().then(() => ({ kind: "revoked" }), (revokeError) => ({
+                        kind: "failed",
+                        error: revokeError,
+                    }));
+                    const cleanupFailures = [
+                        ...(cancellation.kind === "failed" ? [cancellation.error] : []),
+                        ...(revocation.kind === "failed" ? [revocation.error] : []),
+                    ];
+                    controller.error(cleanupFailures.length === 0
+                        ? error
+                        : new AggregateError([error, ...cleanupFailures], "Artifacts Git stream read and cleanup failed", { cause: error }));
+                }
+            },
+            async cancel(reason) {
+                try {
+                    await reader.cancel(reason);
+                }
+                finally {
+                    await revoke();
+                }
+            },
+        });
+        return new Response(body, {
+            status: upstream.status,
+            headers: responseHeaders,
+        });
+    }
+    catch (error) {
+        await revoke();
+        throw error;
+    }
+}
+/** Configure the Artifacts owner once; provider remotes and credentials stay private. */
+export function createCloudflareArtifacts(options) {
+    const binding = options.namespace;
+    const repositories = options.repositories;
+    const gitHttp = options.gitHttp ?? http;
+    const gitFetch = options.gitFetch ?? ((input, init) => fetch(input, init));
+    const recoverForkRepository = async (input) => {
+        const template = repositoryName(input.template);
+        const destination = repositoryName(input.repository);
+        const existing = await existingRepositoryMetadata(binding, repositories, destination);
+        if (existing === null)
+            return null;
+        if (existing.parentRepository !== template)
+            throw new Error("Artifacts fork destination belongs to another source");
+        const mainHead = await readDefaultBranchHead(binding, repositories, destination);
+        if (mainHead === null)
+            throw new Error("Artifacts fork destination has no main commit");
+        return {
+            repository: repositoryIdentity(existing),
+            mainHead,
+            disposition: "existing",
+        };
+    };
+    return Object.freeze({
+        ensureRepository: async (name) => {
+            const safeName = repositoryName(name);
+            const existing = await existingRepositoryMetadata(binding, repositories, safeName);
+            if (existing !== null)
+                return repositoryIdentity(existing);
+            let created;
+            try {
+                created = await binding.create(safeName, {
+                    readOnly: false,
+                    setDefaultBranch: "main",
+                });
+            }
+            catch (error) {
+                if (!(error instanceof Error))
+                    throw error;
+                if (artifactsErrorCode(error) !== "ALREADY_EXISTS")
+                    throw error;
+                const raced = await waitForRecordedRepositoryMetadata(binding, repositories, safeName);
+                return repositoryIdentity(raced);
+            }
+            const metadata = repositoryMetadata(created, null);
+            if (metadata.name !== safeName)
+                throw new Error("Artifacts create returned another repository");
+            await recordPendingWithRetry(repositories, metadata, created.token);
+            const activated = await finishOrReadCreatedRepository(binding, repositories, metadata);
+            return repositoryIdentity(activated);
+        },
+        forkRepository: async (input) => {
+            const recovered = await recoverForkRepository(input);
+            if (recovered !== null)
+                return recovered;
+            const templateName = repositoryName(input.template);
+            const destination = repositoryName(input.repository);
+            const templateHead = await readDefaultBranchHead(binding, repositories, templateName);
+            if (templateHead === null || templateHead !== input.expectedMainHead)
+                throw new Error("Artifacts template main changed before fork");
+            const template = await repositoryHandleWhenReady(binding, templateName);
+            let forked;
+            try {
+                forked = await template.fork(destination, {
+                    readOnly: false,
+                    defaultBranchOnly: true,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof Error) ||
+                    artifactsErrorCode(error) !== "ALREADY_EXISTS")
+                    throw error;
+                const stored = await waitForRecordedRepositoryMetadata(binding, repositories, destination);
+                if (stored.parentRepository !== templateName)
+                    throw new Error("Artifacts fork destination belongs to another source", { cause: error });
+                const mainHead = await readDefaultBranchHead(binding, repositories, destination);
+                if (mainHead === null)
+                    throw new Error("Artifacts fork destination has no main commit", {
+                        cause: error,
+                    });
+                const recovered = {
+                    repository: repositoryIdentity(stored),
+                    mainHead,
+                    disposition: "existing",
+                };
+                return recovered;
+            }
+            const metadata = repositoryMetadata(forked, templateName);
+            if (metadata.name !== destination)
+                throw new Error("Artifacts fork returned another repository");
+            await recordPendingWithRetry(repositories, metadata, forked.token);
+            const activated = await finishOrReadCreatedRepository(binding, repositories, metadata);
+            const mainHead = await readDefaultBranchHead(binding, repositories, destination);
+            if (mainHead === null || mainHead !== templateHead)
+                throw new Error("Artifacts fork main does not match template main");
+            return {
+                repository: repositoryIdentity(activated),
+                mainHead,
+                disposition: "created",
+            };
+        },
+        recoverForkRepository,
+        resolveRepository: async (name) => {
+            const safeName = repositoryName(name);
+            const metadata = await requireRepositoryMetadata(binding, repositories, safeName);
+            await repositoryHandleWhenReady(binding, safeName);
+            return repositoryIdentity(metadata);
+        },
+        readDefaultBranchHead: (name) => readDefaultBranchHead(binding, repositories, name, gitHttp),
+        readBranchHeads: (name) => readRefs(binding, repositories, name, gitHttp).then((refs) => refs
+            .filter((ref) => ref.name.startsWith("refs/heads/"))
+            .map((ref) => ref.hash)),
+        readRefs: (name) => readRefs(binding, repositories, name, gitHttp),
+        exchangeGit: (input) => exchange(binding, repositories, input, gitFetch),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { Artifacts, ArtifactsRepository, ArtifactsForkResult, GitExchange, } from "./artifacts.js";
+export { createCloudflareArtifacts, type CloudflareArtifactsNamespace, type CloudflareArtifactsOptions, } from "./cloudflare.js";
+export { createArtifactsRestNamespace, ArtifactsRestError, type ArtifactsRestOptions, } from "./rest.js";
+export type { ArtifactsNamespace, ArtifactsCommit, ArtifactsRepositoryInfo, } from "./namespace.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createCloudflareArtifacts, } from "./cloudflare.js";
+export { createArtifactsRestNamespace, ArtifactsRestError, } from "./rest.js";