canopycms 0.0.68-int.98 → 0.1.0

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

@@ -1,8 +1,8 @@
 import type { CanopyOctokitAuthOptions, OctokitAuthStrategyOptions } from '../github-service.js';
 /**
  * How the worker authenticates to GitHub, for both halves of its access:
- * Octokit (the REST API) and git-over-HTTPS (push/fetch, which carries the
- * credential in the remote URL).
+ * Octokit (the REST API) and git-over-HTTPS (push/fetch, which the gateway
+ * hands the credential in a per-command config file).
  *
  * Two shapes are supported, and they are equals — nothing here deprecates,
  * warns on, or nudges away from the token.
@@ -18,7 +18,7 @@ import type { CanopyOctokitAuthOptions, OctokitAuthStrategyOptions } from '../gi
  *   a year, acts as the person who created it, and dies when they leave the
  *   organisation. The cost is that its installation tokens last about an
  *   hour, so the credential must be minted on demand rather than read once at
- *   boot — which is why `CmsWorker.buildGitHubUrl()` is async.
+ *   boot — which is why the gateway resolves it per operation (github-gateway.ts).
  */
 export interface GitHubAuthConfig {
     /**
@@ -35,7 +35,7 @@ export interface GitHubAuthConfig {
      * `canopycms-cdk`'s EC2 worker supplies it from three CDK props — see
      * `packages/canopycms-cdk/worker/github-app-auth.ts`, which is also the
      * worked example an adopter driving `CmsWorker` from their own entrypoint
-     * should copy, and `docs/adopter-migration.md` for that case written out.
+     * should copy, and `CHANGELOG.md` for that case written out.
      *
      * Exactly one of this and `githubToken` must be set: configuring both is an
      * error, and so is configuring neither.
@@ -58,7 +58,7 @@ export interface GitHubAuthConfig {
      * 59 minutes and mints a new one after that, so `refreshCredential()` below
      * is a no-op on that path. It does NOT recover a rotated private key or an
      * early-revoked token — see
-     * .claude/future-tasks/worker-app-auth-cannot-recover-a-rotated-key.md.
+     * safeinsights/canopycms#894.
      */
     refreshGitHubToken?: () => Promise<string | undefined>;
     /**
@@ -68,8 +68,8 @@ export interface GitHubAuthConfig {
      *
      * Core's own backstop, not a substitute for one the provider keeps: a
      * failing publish retries on a 5s/10s/20s backoff (task-queue.ts), and
-     * `CmsWorker` calls `refreshCredential` after every failed task attempt AND
-     * every failed git sync, so a burst of failures would otherwise reach an
+     * the gateway calls `refreshCredential` after every operation that failed
+     * reaching GitHub other than with a 422, so a burst of failures would otherwise reach an
      * adopter-supplied `refreshGitHubToken` every few seconds. The AWS provider
      * (`packages/canopycms-cdk/worker/credential-refresh.ts`) already enforces
      * its own five-minute floor; an adopter's own provider has none unless they
@@ -165,7 +165,7 @@ export interface ResolvedGitHubAuth {
      * `refreshGitHubTokenMinIntervalMs`, and swaps the result in.
      *
      * Nothing needs rebuilding afterwards, on either path. Both consumers read
-     * the credential per use — `resolveGitToken` on every `buildGitHubUrl()`,
+     * the credential per use — `resolveGitToken` for every GitHub-bound git operation,
      * and Octokit through a strategy hook that reads it per request — so a
      * swapped token is live at the next use with no cache to invalidate.
      *
@@ -179,7 +179,7 @@ export interface ResolvedGitHubAuth {
 /**
  * Choose how this worker authenticates, ONCE, from its config.
  *
- * Called from `CmsWorker.ensureGitHubAuth()`, which start() invokes inside
+ * Called where `CmsWorker` creates its GitHub gateway, which start() does inside
  * its try — NOT from the constructor, so that a half-configured worker still
  * constructs and the throw lands where start()'s catch can record it in
  * worker-status.json. Resolved once, so both consumers (Octokit and the git

package/dist/worker/github-auth.js

@@ -38,7 +38,7 @@ function dynamicTokenAuth(getToken) {
 /**
  * Choose how this worker authenticates, ONCE, from its config.
  *
- * Called from `CmsWorker.ensureGitHubAuth()`, which start() invokes inside
+ * Called where `CmsWorker` creates its GitHub gateway, which start() does inside
  * its try — NOT from the constructor, so that a half-configured worker still
  * constructs and the throw lands where start()'s catch can record it in
  * worker-status.json. Resolved once, so both consumers (Octokit and the git
@@ -74,7 +74,7 @@ export function resolveWorkerGitHubAuth(config) {
             // key does not expire, and `@octokit/auth-app`'s own cache mints a new
             // installation token when the old one expires. A rotated key or an
             // early-revoked token is NOT recovered here — see
-            // .claude/future-tasks/worker-app-auth-cannot-recover-a-rotated-key.md.
+            // safeinsights/canopycms#894.
             refreshCredential: async () => { },
         };
     }
@@ -125,10 +125,10 @@ export function resolveWorkerGitHubAuth(config) {
             // Stamped BEFORE the await, not after, for the same reason
             // credential-refresh.ts's does: stamping after lets two overlapping
             // calls each see an unstamped clock and both reach the provider, which
-            // is the floor not holding. Overlap is real here -- the task loop and
-            // the git-sync loop both call `refreshCredential`, on separate loops
-            // `scheduleLoop` does not serialise against each other -- so this is
-            // what collapses them into one provider call. A provider that THROWS
+            // is the floor not holding. Overlap is real here -- the gateway stops
+            // waiting for a re-read after its timeout without cancelling it, and the
+            // next failure arms another -- so this is what collapses them into one
+            // provider call. A provider that THROWS
             // still counts as reached: the stamp already landed by the time the
             // rejection surfaces, so a failing provider is bounded by the floor
             // too, and this call is not counted in `refreshesStarted` below unless
@@ -137,16 +137,15 @@ export function resolveWorkerGitHubAuth(config) {
             const refresh = ++refreshesStarted;
             const refreshed = await config.refreshGitHubToken();
             // Falsy covers both "nothing rotated" (`undefined`) and an empty secret:
-            // an empty token would build `https://x-access-token:@github.com/…`,
-            // which git sends anonymously, so keeping the known-bad-but-real token
+            // an empty token would send an empty basic credential, which GitHub
+            // treats as anonymous, so keeping the known-bad-but-real token
             // fails more legibly than replacing it with nothing.
             if (!refreshed)
                 return;
             // A refresh that STARTED before one already applied read the store
-            // earlier, so its value can only be older. Refreshes do overlap: the task
-            // loop and the git-sync loop both call this, and
-            // CmsWorker.refreshGitHubCredential stops waiting after `taskTimeoutMs`
-            // without cancelling. Only a refresh that returned a value counts as
+            // earlier, so its value can only be older. Refreshes do overlap: the
+            // gateway stops waiting for one after `taskTimeoutMs` without cancelling
+            // it, and may start the next. Only a refresh that returned a value counts as
             // applied -- one that returned `undefined` (a provider's floor, say) says
             // nothing about how recent it is, so it must not block a slower real read.
             if (refresh < newestRefreshApplied)
@@ -219,9 +218,8 @@ async function mintInstallationToken(app, timeoutMs) {
     });
     const minted = await Promise.race([minting, timedOut]);
     if (!minted) {
-        // An empty token would build `https://x-access-token:@github.com/…`, which
-        // git sends as an anonymous request and GitHub answers with a 403 that
-        // says nothing about the credential.
+        // An empty token would send an empty basic credential, which GitHub
+        // answers as anonymous, with a 403 that says nothing about the credential.
         throw new Error('GitHub App authentication returned an empty installation token');
     }
     return minted;

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

@@ -0,0 +1,62 @@
+import type { GitHubGateway } from './github-gateway.js';
+export interface GitHubGatewayServerOptions {
+    /**
+     * The period over which a bundle download must keep up {@link MIN_DOWNLOAD_BYTES_PER_SECOND}, or
+     * be cut off, so a client that opens a bundle and stops reading, or reads a trickle, cannot
+     * keep its file. Default {@link DEFAULT_DOWNLOAD_STALL_MS}.
+     */
+    downloadStallMs?: number;
+    /** The slowest average a bundle download may keep up. Default {@link MIN_DOWNLOAD_BYTES_PER_SECOND}. */
+    minDownloadBytesPerSecond?: number;
+}
+/** Where the server listens: a socket systemd passed (`fd`), or a path it binds itself. */
+export type GitHubGatewayListen = {
+    fd: number;
+} | {
+    path: string;
+};
+export interface GitHubGatewayServer {
+    /**
+     * Resolves once nothing is under way: no request is being handled, and no fetch job runs.
+     */
+    idle(): Promise<void>;
+    /**
+     * Stop as a SIGTERM asks: answer new requests `stopping` (`GitHubGatewayStoppingError`, whose
+     * task the worker releases with no retry spent), let those under way finish for at most
+     * `graceMs`, then close every connection, whatever is still on it. The bound is time, not only
+     * {@link idle}: a client that trickles a request body would otherwise hold the stop open. A fetch job is not waited for; stopping one is the gateway's own.
+     */
+    drain(graceMs: number): Promise<void>;
+    /** Stop accepting, and close every connection. */
+    close(): Promise<void>;
+}
+/**
+ * Serve `gateway` on a unix socket.
+ *
+ * Who can connect is the socket node's permissions. In production the worker and the gateway run
+ * as different users, so systemd creates the socket and passes it as `fd`, and the socket unit
+ * sets its owner and mode (`SocketUser=`, `SocketMode=`). A `path`, for development and tests,
+ * where both ends are the same user, is bound here: only inside a directory this process owns and
+ * no one else can enter, so no other user can reach, plant or swap the node, which is then made
+ * `0600`.
+ *
+ * `gateway.prepare()` starts once the server holds its socket, and every operation but
+ * {@link UNPREPARED_OPERATIONS} waits for it; a failure is the gateway's fatal error, answered to
+ * each of them.
+ */
+export declare function serveGitHubGateway(gateway: GitHubGateway, listen: GitHubGatewayListen, options?: GitHubGatewayServerOptions): Promise<GitHubGatewayServer>;
+/**
+ * The worker's {@link GitHubGateway} for a gateway served at `socketPath`. Every answer is
+ * validated before the worker sees it, and every error is rebuilt (worker/github-gateway-wire.ts,
+ * `decodeError`), so the task runner classifies it as it would in-process. A
+ * gateway it cannot reach throws {@link GitHubGatewayUnreachableError}.
+ */
+export declare function connectGitHubGateway(socketPath: string, options?: GitHubGatewayClientOptions): GitHubGateway;
+export interface GitHubGatewayClientOptions {
+    /**
+     * How long a fetch job may go without a sign of life from the gateway's git before the worker
+     * stops waiting for it (transient); the job itself runs on. Default
+     * {@link DEFAULT_FETCH_INACTIVITY_MS}; the worker's task timeout is the natural value.
+     */
+    fetchInactivityMs?: number;
+}