canopycms 0.0.68-int.98 → 0.1.0

package/dist/worker/github-gateway-wire.d.ts

@@ -0,0 +1,590 @@
+import { z } from 'zod';
+/** Carries a push's JSON request, so the request body is free for its bundle. Base64url JSON. */
+export declare const PUSH_REQUEST_HEADER = "canopy-push-request";
+/** The content type of a bundle, either way. */
+export declare const BUNDLE_CONTENT_TYPE = "application/x-git-bundle";
+/** The largest JSON request body, in bytes: `have`'s 10 000 IDs, or a pull request body. */
+export declare const MAX_JSON_REQUEST_BYTES: number;
+/** The largest JSON answer, in bytes: a fetch's ref map for every GitHub branch. */
+export declare const MAX_JSON_ANSWER_BYTES: number;
+export declare const fetchRequest: z.ZodObject<{
+    have: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    have: string[];
+}, {
+    have: string[];
+}>;
+export declare const pushRequest: z.ZodObject<{
+    branch: z.ZodString;
+    sha: z.ZodString;
+    lease: z.ZodOptional<z.ZodString>;
+    prerequisites: z.ZodArray<z.ZodString, "many">;
+    /** Whether the request body is a bundle; without one it is empty. */
+    bundle: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    branch: string;
+    sha: string;
+    prerequisites: string[];
+    bundle: boolean;
+    lease?: string | undefined;
+}, {
+    branch: string;
+    sha: string;
+    prerequisites: string[];
+    bundle: boolean;
+    lease?: string | undefined;
+}>;
+export declare const requests: {
+    readonly prepare: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly health: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly defaultBranch: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly isProtectedBranch: z.ZodObject<{
+        branch: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        branch: string;
+    }, {
+        branch: string;
+    }>;
+    readonly createPullRequest: z.ZodObject<{
+        title: z.ZodString;
+        body: z.ZodString;
+        head: z.ZodString;
+        base: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+    }, {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+    }>;
+    readonly updatePullRequest: z.ZodObject<{
+        number: z.ZodNumber;
+        title: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodLiteral<"closed">>;
+    }, "strict", z.ZodTypeAny, {
+        number: number;
+        title?: string | undefined;
+        state?: "closed" | undefined;
+        body?: string | undefined;
+    }, {
+        number: number;
+        title?: string | undefined;
+        state?: "closed" | undefined;
+        body?: string | undefined;
+    }>;
+    readonly getPullRequest: z.ZodObject<{
+        number: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        number: number;
+    }, {
+        number: number;
+    }>;
+    readonly createOrUpdatePullRequest: z.ZodObject<{
+        markReadyIfDraft: z.ZodOptional<z.ZodBoolean>;
+        mergeSectionIntoBody: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodString;
+        body: z.ZodString;
+        head: z.ZodString;
+        base: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+        markReadyIfDraft?: boolean | undefined;
+        mergeSectionIntoBody?: boolean | undefined;
+    }, {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+        markReadyIfDraft?: boolean | undefined;
+        mergeSectionIntoBody?: boolean | undefined;
+    }>;
+    readonly convertPullRequestToDraft: z.ZodObject<{
+        number: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        number: number;
+    }, {
+        number: number;
+    }>;
+    readonly deleteBranch: z.ZodObject<{
+        branch: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        branch: string;
+    }, {
+        branch: string;
+    }>;
+    readonly authSnapshot: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly termination: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly completeLifecycle: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+};
+export declare const answers: {
+    readonly prepare: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly health: z.ZodObject<{
+        ready: z.ZodBoolean;
+        fatalError: z.ZodNullable<z.ZodString>;
+        preflight: z.ZodEnum<["not-an-app", "verified", "unverified", "pending"]>;
+        clerkConfigured: z.ZodBoolean;
+        protectedBranches: z.ZodObject<{
+            configured: z.ZodArray<z.ZodString, "many">;
+            githubDefault: z.ZodNullable<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            configured: string[];
+            githubDefault: string | null;
+        }, {
+            configured: string[];
+            githubDefault: string | null;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        ready: boolean;
+        protectedBranches: {
+            configured: string[];
+            githubDefault: string | null;
+        };
+        preflight: "pending" | "not-an-app" | "verified" | "unverified";
+        fatalError: string | null;
+        clerkConfigured: boolean;
+    }, {
+        ready: boolean;
+        protectedBranches: {
+            configured: string[];
+            githubDefault: string | null;
+        };
+        preflight: "pending" | "not-an-app" | "verified" | "unverified";
+        fatalError: string | null;
+        clerkConfigured: boolean;
+    }>;
+    readonly defaultBranch: z.ZodObject<{
+        branch: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        branch: string;
+    }, {
+        branch: string;
+    }>;
+    readonly isProtectedBranch: z.ZodObject<{
+        protected: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        protected: boolean;
+    }, {
+        protected: boolean;
+    }>;
+    readonly createPullRequest: z.ZodObject<{
+        number: z.ZodNumber;
+        url: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        number: number;
+        url: string;
+    }, {
+        number: number;
+        url: string;
+    }>;
+    readonly updatePullRequest: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly getPullRequest: z.ZodObject<{
+        merged: z.ZodBoolean;
+        merged_at: z.ZodNullable<z.ZodString>;
+        state: z.ZodEnum<["open", "closed"]>;
+        node_id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        merged: boolean;
+        state: "open" | "closed";
+        merged_at: string | null;
+        node_id: string;
+    }, {
+        merged: boolean;
+        state: "open" | "closed";
+        merged_at: string | null;
+        node_id: string;
+    }>;
+    readonly createOrUpdatePullRequest: z.ZodObject<{
+        number: z.ZodNumber;
+        url: z.ZodString;
+    } & {
+        created: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        number: number;
+        created: boolean;
+        url: string;
+    }, {
+        number: number;
+        created: boolean;
+        url: string;
+    }>;
+    readonly convertPullRequestToDraft: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly deleteBranch: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly authSnapshot: z.ZodObject<{
+        users: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            email: z.ZodString;
+            avatarUrl: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            id: string;
+            email: string;
+            avatarUrl?: string | undefined;
+        }, {
+            name: string;
+            id: string;
+            email: string;
+            avatarUrl?: string | undefined;
+        }>, "many">;
+        groups: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            memberCount: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            id: string;
+            description?: string | undefined;
+            memberCount?: number | undefined;
+        }, {
+            name: string;
+            id: string;
+            description?: string | undefined;
+            memberCount?: number | undefined;
+        }>, "many">;
+        memberships: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        groups: {
+            name: string;
+            id: string;
+            description?: string | undefined;
+            memberCount?: number | undefined;
+        }[];
+        users: {
+            name: string;
+            id: string;
+            email: string;
+            avatarUrl?: string | undefined;
+        }[];
+        memberships: Record<string, string[]>;
+    }, {
+        groups: {
+            name: string;
+            id: string;
+            description?: string | undefined;
+            memberCount?: number | undefined;
+        }[];
+        users: {
+            name: string;
+            id: string;
+            email: string;
+            avatarUrl?: string | undefined;
+        }[];
+        memberships: Record<string, string[]>;
+    }>;
+    readonly termination: z.ZodObject<{
+        notice: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<["auto-scaling", "spot"]>;
+            reason: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            reason: string;
+            kind: "auto-scaling" | "spot";
+        }, {
+            reason: string;
+            kind: "auto-scaling" | "spot";
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        notice: {
+            reason: string;
+            kind: "auto-scaling" | "spot";
+        } | null;
+    }, {
+        notice: {
+            reason: string;
+            kind: "auto-scaling" | "spot";
+        } | null;
+    }>;
+    readonly completeLifecycle: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+};
+export type JsonOperation = keyof typeof requests;
+/** Where each JSON operation is POSTed. */
+export declare const JSON_ROUTES: Readonly<Record<JsonOperation, string>>;
+export declare const FETCH_ROUTE = "/v1/fetch";
+export declare const PUSH_ROUTE = "/v1/push";
+export declare const BUNDLE_ROUTE = "/v1/bundle";
+export declare const fetchStarted: z.ZodObject<{
+    job: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    job: string;
+}, {
+    job: string;
+}>;
+/** A fetch job's state as a poll reads it; a failed one answers its error instead. */
+export declare const fetchPoll: z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
+    state: z.ZodLiteral<"running">;
+    progress: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    progress: number;
+    state: "running";
+}, {
+    progress: number;
+    state: "running";
+}>, z.ZodObject<{
+    state: z.ZodLiteral<"done">;
+    progress: z.ZodNumber;
+    /** Every GitHub branch and its tip, as pairs: a `Map` has no JSON form of its own. */
+    refs: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>, "many">;
+    bundleId: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    progress: number;
+    state: "done";
+    refs: [string, string][];
+    bundleId: string | null;
+}, {
+    progress: number;
+    state: "done";
+    refs: [string, string][];
+    bundleId: string | null;
+}>]>;
+export declare const pushAnswer: z.ZodUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"pushed">;
+    moved: z.ZodLiteral<false>;
+    pastStaleLease: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    kind: "pushed";
+    moved: false;
+    pastStaleLease: boolean;
+}, {
+    kind: "pushed";
+    moved: false;
+    pastStaleLease: boolean;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"pushed">;
+    moved: z.ZodLiteral<true>;
+    from: z.ZodNullable<z.ZodString>;
+    to: z.ZodString;
+    pastStaleLease: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    kind: "pushed";
+    from: string | null;
+    to: string;
+    moved: true;
+    pastStaleLease: boolean;
+}, {
+    kind: "pushed";
+    from: string | null;
+    to: string;
+    moved: true;
+    pastStaleLease: boolean;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"need-objects">;
+    usable: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    kind: "need-objects";
+    usable: string[];
+}, {
+    kind: "need-objects";
+    usable: string[];
+}>]>;
+/**
+ * A JSON answer's body, `{ value }` or `{ error }` and nothing else; null for anything else.
+ */
+export declare function readAnswerBody(json: unknown): {
+    value: unknown;
+    error?: undefined;
+} | {
+    error: unknown;
+} | null;
+declare const errorEnvelope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"refusal">;
+    push: z.ZodBoolean;
+    operation: z.ZodEnum<["push", "delete", "pull-request"]>;
+    branch: z.ZodString;
+    reason: z.ZodEnum<["invalid", "protected", "settings", "not-a-commit", "too-long"]>;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    push: boolean;
+    message: string;
+    branch: string;
+    reason: "settings" | "protected" | "invalid" | "not-a-commit" | "too-long";
+    kind: "refusal";
+    operation: "push" | "pull-request" | "delete";
+}, {
+    push: boolean;
+    message: string;
+    branch: string;
+    reason: "settings" | "protected" | "invalid" | "not-a-commit" | "too-long";
+    kind: "refusal";
+    operation: "push" | "pull-request" | "delete";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"push">;
+    pushKind: z.ZodEnum<["rejected", "rejected-after-stale-lease"]>;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    message: string;
+    kind: "push";
+    pushKind: "rejected" | "rejected-after-stale-lease";
+}, {
+    message: string;
+    kind: "push";
+    pushKind: "rejected" | "rejected-after-stale-lease";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"transient">;
+    code: z.ZodEnum<["github-fetch-failed", "bundle-rejected", "prerequisite-gone", "bundle-gone", "mirror-corrupt", "objects-still-needed", "ref-kept-moving", "default-branch-unread"]>;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    code: "github-fetch-failed" | "bundle-rejected" | "prerequisite-gone" | "bundle-gone" | "mirror-corrupt" | "objects-still-needed" | "ref-kept-moving" | "default-branch-unread";
+    message: string;
+    kind: "transient";
+}, {
+    code: "github-fetch-failed" | "bundle-rejected" | "prerequisite-gone" | "bundle-gone" | "mirror-corrupt" | "objects-still-needed" | "ref-kept-moving" | "default-branch-unread";
+    message: string;
+    kind: "transient";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"http">;
+    name: z.ZodString;
+    message: z.ZodString;
+    status: z.ZodNumber;
+    /** Octokit's `response`, when the error carried one: the headers that cross, and its body. */
+    response: z.ZodOptional<z.ZodObject<{
+        headers: z.ZodRecord<z.ZodString, z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, "strict", z.ZodTypeAny, {
+        headers: Record<string, string>;
+        data?: unknown;
+    }, {
+        headers: Record<string, string>;
+        data?: unknown;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    status: number;
+    message: string;
+    kind: "http";
+    response?: {
+        headers: Record<string, string>;
+        data?: unknown;
+    } | undefined;
+}, {
+    name: string;
+    status: number;
+    message: string;
+    kind: "http";
+    response?: {
+        headers: Record<string, string>;
+        data?: unknown;
+    } | undefined;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    name: z.ZodString;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    message: string;
+    kind: "error";
+}, {
+    name: string;
+    message: string;
+    kind: "error";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    status: z.ZodNumber;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    status: number;
+    message: string;
+    kind: "refused";
+}, {
+    status: number;
+    message: string;
+    kind: "refused";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"unknown-job">;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    message: string;
+    kind: "unknown-job";
+}, {
+    message: string;
+    kind: "unknown-job";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"stopping">;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    message: string;
+    kind: "stopping";
+}, {
+    message: string;
+    kind: "stopping";
+}>]>;
+export type ErrorEnvelope = z.infer<typeof errorEnvelope>;
+/**
+ * An Octokit error as it crosses the socket: the fields the task runner's classifiers read
+ * (`status`, `response.headers`, `response.data`, the message), rebuilt on the worker's side. Not
+ * a gateway class: a GitHub answer stays a GitHub answer (`isPermanentTaskFailure`,
+ * `isRateLimitSignal403`, `isNoCommitsBetweenError`, `isRefAlreadyGoneError`).
+ * @internal Exported for tests.
+ */
+export declare class GitHubRequestError extends Error {
+    readonly status: number;
+    readonly response?: {
+        headers: Record<string, string>;
+        data?: unknown;
+    } | undefined;
+    constructor(name: string, message: string, status: number, response?: {
+        headers: Record<string, string>;
+        data?: unknown;
+    } | undefined);
+}
+/**
+ * The GitHub gateway could not be reached, or broke off an answer: it is not running, restarting,
+ * or stopping. Transient.
+ */
+export declare class GitHubGatewayUnreachableError extends Error {
+    constructor(message: string);
+}
+/**
+ * The gateway answered that it is draining for a stop. Unreachable for every purpose, and more:
+ * the task runner releases a task it hits with no retry spent, since the stop, not the task, is
+ * why it failed, and a restart's grace could otherwise outlast the task's retries.
+ */
+export declare class GitHubGatewayStoppingError extends GitHubGatewayUnreachableError {
+    constructor(message: string);
+}
+/** The gateway refused a request before any operation ran, or answered outside the wire format. */
+export declare class GitHubGatewayProtocolError extends Error {
+    constructor(message: string);
+}
+/**
+ * The gateway, or node in front of it, refused a request for its shape or size: the same request
+ * is refused again, as the in-process gateway's own refusal of an oversize field is, so the task
+ * runner fails it for good. The HTTP status is `refusedWith`, never `status`, which every
+ * classifier reads as GitHub's (a 404 there means a branch already gone).
+ */
+export declare class GatewayRequestRefusedError extends GitHubGatewayProtocolError {
+    readonly refusedWith: number;
+    constructor(message: string, refusedWith: number);
+}
+/** The error for a request refused with `status` before any operation ran. */
+export declare function refusedRequestError(message: string, status: number | undefined): Error;
+/**
+ * The envelope for an error leaving the gateway. Every string in it is scrubbed as an error is,
+ * by the exact token forms and `redactCredentials`'s patterns (worker/gateway-egress.ts): a
+ * credentialed operation already did (`LocalGitHubGateway.credentialed`), and this is the last
+ * place anything could slip past it. No stack, no
+ * `cause` and no Octokit `request` crosses. A thrown value that is not an Error crosses as a fixed
+ * message and is logged here instead: its string form can be anything, a stack included.
+ */
+export declare function encodeError(err: unknown): ErrorEnvelope;
+/**
+ * The error an envelope describes, as the worker throws it: the gateway's own classes keep their
+ * class, fields and message; an Octokit error becomes a {@link GitHubRequestError}.
+ */
+export declare function decodeError(value: unknown): Error;
+/** A poll for a fetch job the gateway does not hold; the client fetches anew, once. */
+export declare class UnknownFetchJobError extends Error {
+    constructor(message: string);
+}
+/** A push's JSON request, as {@link PUSH_REQUEST_HEADER} carries it. */
+export declare function encodePushHeader(request: z.infer<typeof pushRequest>): string;
+/** {@link encodePushHeader}'s inverse; throws on anything that is not base64url JSON. */
+export declare function decodePushHeader(value: string): unknown;
+export {};