canopycms 0.0.68-int.98 → 0.1.0

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

@@ -0,0 +1,238 @@
+import type { Readable } from 'node:stream';
+import type { Octokit, RestEndpointMethodTypes } from '@octokit/rest';
+import type { AuthCacheSnapshot } from '../auth/cache.js';
+import { type CreateOrUpdatePullRequestParams } from '../github-service.js';
+import { type ResolvedGitHubAuth } from './github-auth.js';
+import { type GitHubRefUpdate } from './github-mirror.js';
+import { type GatewayInstanceOptions } from './gateway-instance.js';
+/** What a {@link GitHubGateway.fetch} brought back. */
+export interface GitHubFetchResult {
+    /** Every GitHub branch, mapped to its tip, as this fetch left the mirror. */
+    refs: ReadonlyMap<string, string>;
+    /**
+     * Opens ({@link GitHubGateway.openBundle}) a bundle of every branch, less the commits in the
+     * request's `have` and their history; null when that leaves nothing to send.
+     */
+    bundleId: string | null;
+}
+/** The most `have` IDs one fetch takes. */
+export declare const MAX_FETCH_HAVE = 10000;
+export interface GitHubPushRequest {
+    branch: string;
+    /** The commit to put at `refs/heads/<branch>` on GitHub, already in remote.git. */
+    sha: string;
+    /** The commit GitHub must still be at for the push to replace it (`--force-with-lease`). */
+    lease?: string;
+    /**
+     * At most {@link MAX_PUSH_PREREQUISITES} commits the caller would build a bundle of the branch
+     * on, so an answer of `need-objects` can say which of them the gateway can use.
+     */
+    prerequisites: readonly string[];
+}
+/**
+ * What a push did to GitHub's ref, and whether it got there by the plain retry after GitHub
+ * refused a stale lease, which proves GitHub was not at the lease's commit.
+ */
+export type GitHubPushOutcome = GitHubRefUpdate & {
+    pastStaleLease: boolean;
+};
+/**
+ * A push's answer: `pushed`, or `need-objects` when no GitHub branch contains `sha` and the caller
+ * must send it as a bundle built on `usable`, the request's prerequisites a GitHub branch
+ * contains (none, when empty).
+ */
+export type GitHubPushAnswer = ({
+    kind: 'pushed';
+} & GitHubPushOutcome) | {
+    kind: 'need-objects';
+    usable: readonly string[];
+};
+/**
+ * A push to GitHub failed: `rejected` on the first attempt, `rejected-after-stale-lease` on the
+ * plain retry after GitHub refused a stale lease. The message is the failure's own: git's output,
+ * for a refusal, which the task runner classifies. A {@link RefusedPushError} from the first
+ * attempt is thrown as itself.
+ */
+export declare class GitHubPushError extends Error {
+    readonly kind: 'rejected' | 'rejected-after-stale-lease';
+    constructor(kind: 'rejected' | 'rejected-after-stale-lease', message: string);
+}
+/** A moved ref for a log line: `<old7>..<new7>`, or `new branch at <new7>`. */
+export declare function describeMove(update: Extract<GitHubRefUpdate, {
+    moved: true;
+}>): string;
+/** The fields of a pull request the worker reads. */
+export type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['response']['data'], 'merged' | 'merged_at' | 'state' | 'node_id'>;
+export type GitHubCreateOrUpdatePullRequest = Omit<CreateOrUpdatePullRequestParams, 'octokit' | 'owner' | 'repo' | 'signal'>;
+/**
+ * Everything the worker does with GitHub, and the only place the credential and Octokit are used.
+ * Octokit errors propagate with their status, headers and response data, so the task runner's
+ * classifiers read them as they would Octokit's own; what it returns, throws and logs is first
+ * scrubbed of the credential (worker/gateway-egress.ts, which names its exceptions). What it
+ * refuses to do, whatever it is asked, is worker/branch-policy.ts's, and throws
+ * `GatewayRefusalError`. The gateway re-reads its own credential after a failure
+ * (`LocalGitHubGateway.credentialed`); the worker never asks it to.
+ */
+export interface GitHubGateway {
+    /**
+     * At startup, before anything uses the credential: prove a GitHub App credential works, refuse
+     * a state directory the Lambda could write or this process cannot own outright, and try to
+     * create the mirror. Runs once; every later call answers the first one's outcome. Fatal: an App
+     * credential that fails for a lasting reason, and either state-directory refusal. Not fatal:
+     * creating the mirror, which the next operation retries.
+     */
+    prepare(): Promise<void>;
+    /**
+     * Whether the gateway is ready, waiting for a `prepare()` under way (until `signal` aborts), and
+     * what the worker reports of it.
+     */
+    health(signal?: AbortSignal): Promise<GitHubGatewayHealth>;
+    /** GitHub's default branch. */
+    defaultBranch(signal?: AbortSignal): Promise<string>;
+    /** Whether `branch` is in the gateway's protected set (worker/branch-policy.ts). */
+    isProtectedBranch(branch: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Fetch every GitHub branch, and answer with all of them and a bundle of the commits `have`
+     * lacks. `have` is the caller's own tips, at most {@link MAX_FETCH_HAVE} object IDs; any the
+     * gateway does not hold as a commit is ignored. A new fetch replaces a bundle not yet opened.
+     * `onProgress` is told of each sign of life from the gateway's git while the caller waits.
+     */
+    fetch(request: {
+        have: readonly string[];
+    }, signal?: AbortSignal, onProgress?: () => void): Promise<GitHubFetchResult>;
+    /**
+     * The bundle a fetch answered with, readable once. Throws {@link GitHubTransientError}
+     * (`bundle-gone`) when a later fetch replaced it or it was already opened.
+     */
+    openBundle(bundleId: string): Promise<Readable>;
+    /**
+     * Push `sha` to GitHub's `refs/heads/<branch>`, after fetching GitHub. Without `bundle`, it
+     * pushes when a GitHub branch already contains `sha`, and otherwise answers `need-objects`.
+     * With one (exactly one head, `<sha> refs/heads/<branch>`, built on commits a GitHub branch
+     * contains), it takes the bundle into a quarantine, checking every object, and pushes from
+     * there; pushed objects never enter the mirror. A refused lease is retried once without one,
+     * which succeeds only as a fast-forward. Throws {@link RefusedPushError} for a push the worker
+     * never makes (an object that is not a commit included), {@link GitHubPushError} when GitHub
+     * refuses it, {@link GitHubTransientError} for what a later attempt can clear, and anything
+     * else as is.
+     */
+    push(request: GitHubPushRequest, bundle?: Readable, signal?: AbortSignal): Promise<GitHubPushAnswer>;
+    createPullRequest(request: {
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+    }, signal?: AbortSignal): Promise<{
+        number: number;
+        url: string;
+    }>;
+    updatePullRequest(number: number, update: {
+        title?: string;
+        body?: string;
+        state?: 'closed';
+    }, signal?: AbortSignal): Promise<void>;
+    getPullRequest(number: number, signal?: AbortSignal): Promise<GitHubPullRequest>;
+    createOrUpdatePullRequest(request: GitHubCreateOrUpdatePullRequest, signal?: AbortSignal): Promise<{
+        number: number;
+        url: string;
+        created: boolean;
+    }>;
+    convertPullRequestToDraft(number: number, signal?: AbortSignal): Promise<void>;
+    deleteBranch(branch: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * The auth provider's users, groups and memberships, which the worker writes to the auth cache:
+     * the gateway holds the provider's key. Throws when none is configured.
+     */
+    authSnapshot(signal?: AbortSignal): Promise<AuthCacheSnapshot>;
+    /**
+     * A notice once this instance is being terminated; null when none arrived within one poll's
+     * wait. Once a notice has arrived every call answers it again.
+     */
+    termination(signal?: AbortSignal): Promise<GatewayTerminationNotice | null>;
+    /**
+     * Tell the instance's Auto Scaling group the drain is done, so termination proceeds. Refused
+     * (a plain Error) until THIS gateway's own termination watch has seen an Auto Scaling notice,
+     * so a hostile worker cannot shorten the instance's life; the provider runs at most once, and
+     * a later call answers the first one's outcome. Takes no identifier: the gateway's own config
+     * and the instance's metadata say which lifecycle action.
+     */
+    completeLifecycle(signal?: AbortSignal): Promise<void>;
+}
+/** The instance's termination, as the gateway's watcher saw it. */
+export interface GatewayTerminationNotice {
+    kind: 'auto-scaling' | 'spot';
+    /** What `CmsWorker.stop()` records. */
+    reason: string;
+}
+/** What {@link GitHubGateway.health} reports. */
+export interface GitHubGatewayHealth {
+    /** `prepare()` has succeeded. */
+    ready: boolean;
+    /** `prepare()`'s failure, scrubbed: the gateway's fatal error. Null before it or after a success. */
+    fatalError: string | null;
+    /**
+     * The GitHub App check at `prepare()`: `not-an-app` on the token path, `verified`, `unverified`
+     * when it failed in a way that looked transient (the credential is minted again on first use),
+     * or `pending` before it has run.
+     */
+    preflight: 'not-an-app' | 'verified' | 'unverified' | 'pending';
+    /** Whether the gateway holds a Clerk secret key. */
+    clerkConfigured: boolean;
+    /** The protected set (worker/branch-policy.ts): configured names and globs, and GitHub's default as last read. */
+    protectedBranches: {
+        configured: string[];
+        githubDefault: string | null;
+    };
+}
+/** `GatewayInstanceOptions` carries the termination watch and the lifecycle completion. */
+export interface LocalGitHubGatewayOptions extends GatewayInstanceOptions {
+    githubOwner: string;
+    githubRepo: string;
+    auth: ResolvedGitHubAuth;
+    /** Whether `auth` is a GitHub App's, which `prepare()` proves before anything uses it. */
+    githubApp: boolean;
+    /** Holds the mirror; see `CmsWorkerConfig.stateDirectory`. */
+    stateDirectory: string;
+    /**
+     * The shared workspace. Absent in a gateway run as its own process, which cannot see the
+     * workspace; its `efs-unreadable` self-check stands in for the state-directory check below.
+     */
+    workspacePath?: string;
+    /** simple-git's inactivity timeout, and the bound on a credential re-read. */
+    timeoutMs: number;
+    /**
+     * Test seam: the repository standing in for GitHub, resolved once per operation. Default:
+     * `https://github.com/<owner>/<repo>.git`, which never carries the token.
+     */
+    remoteUrl?: string | (() => string | Promise<string>);
+    /** Test seam: the Octokit client. Default: built from `auth`. */
+    octokit?: Octokit;
+    /** The configured base branch, which the gateway never pushes, deletes or opens a PR from. */
+    baseBranch?: string;
+    /** Further branches it protects alike: names and `*` globs (worker/branch-policy.ts). */
+    protectedBranches?: readonly string[];
+    /**
+     * Fetches the auth provider's snapshot with the provider's key; its presence is
+     * `health().clerkConfigured`. Without it, `authSnapshot()` throws.
+     */
+    authSnapshot?: () => Promise<AuthCacheSnapshot>;
+    /** Test seam: how long a fetched snapshot is answered again (default {@link AUTH_SNAPSHOT_REUSE_MS}). */
+    authSnapshotReuseMs?: number;
+    /** The largest pushed bundle taken in, in bytes. Default 1 GiB. */
+    maxBundleBytes?: number;
+    /**
+     * Test seam: how long a completed GitHub fetch is reused (default {@link FETCH_COALESCE_MS}), so
+     * a test can change "GitHub" between two operations and have the second see it.
+     */
+    fetchCoalesceMs?: number;
+    /** Test seam: how long an operation waits for a re-read in flight (default {@link REFRESH_JOIN_CAP_MS}). */
+    refreshJoinCapMs?: number;
+    /**
+     * Test seam: whether `prepare()` starts the first GitHub fetch (default true), for a test that
+     * counts the gateway's own fetches or sessions from its first operation. A served gateway is
+     * prepared as its server starts.
+     */
+    prefetch?: boolean;
+}
+/** The in-process {@link GitHubGateway}. */
+export declare function createLocalGitHubGateway(options: LocalGitHubGatewayOptions): GitHubGateway;