@procedures/gh 0.55.0 → 0.55.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @procedures/gh
 
+## 0.55.1
+
+### Patch Changes
+
+- 3a8881e: `@procedures/gh` has a client of the REST API of GitHub for programs that send many requests: `createRestClient`. It sends each request with `httpRequest` of `@procedures/http`, so a request starts no process.
+  
+  - A GET with a stored answer is a conditional request with `if-none-match`. For an answer 304, the client gives the stored answer with the status 200.
+  - A sliding window of `@mark1russell7/service/limiter` holds the secondary limit of 900 points in each minute. A request that changes data waits one second after the request before it.
+  - After a refusal for the rate, the client sends no request until the time that GitHub gives in `retry-after` or `x-ratelimit-reset`.
+  - No error text of the client has the token or the body of an answer.
+  
+  The package has two new dependencies: `@procedures/http` and `@mark1russell7/service`.
+- @procedures/client@0.55.1
+  - @procedures/shell@0.55.1
+  - @procedures/http@0.55.1
+
 ## 0.55.0
 
 ### Patch Changes

package/README.md

@@ -55,6 +55,31 @@ The GitHub CLI (`gh`) as procedures: pull requests, workflow runs, artifacts, re
 - With `paginate: true`, the pages of an array become one array. The pages of an object become an array of the pages.
 - The method is an input, and `PUT` or `DELETE` can replace or remove data. Thus `gh.api` declares `writes: ["network"]` and keeps the default: destructive.
 
+### The REST client
+
+`createRestClient` is a client of the REST API for a program that sends many requests, for example a dispatcher of runners. It does not use `gh`, so a request starts no process.
+
+```typescript
+import { createRestClient } from "@procedures/gh";
+
+const github = createRestClient({ token: () => readToken() });
+const answer = await github.request({ method: "GET", path: "/repos/owner/name/actions/runs", query: { status: "queued" } }, signal);
+```
+
+- The client sends each request with `httpRequest` of `@procedures/http`, with its host policy and its limits of size and time.
+- The token is a text, or a function that gives it before each request. A token of a GitHub App changes each hour.
+- Each status is an answer: `{ status, body, cached }`. The client throws only when it gets no answer, or when a wait is too long.
+- A GET with a stored answer is a conditional request. For an answer 304, the client gives the stored answer with the status 200 and `cached: true`.
+- GitHub does not count an answer 304 for the primary limit. The client keeps 1,000 answers. The option `cacheEntries` changes the count.
+- A sliding window of `@mark1russell7/service/limiter` holds the secondary limit: 900 points in each minute.
+- A GET costs 1 point. A POST, a PUT, a PATCH or a DELETE costs 5 points, and it waits one second after the write before it.
+- After a refusal for the rate (429, or 403 with a sign of the rate), the client waits the time of `retry-after` or until `x-ratelimit-reset`.
+- With no time in the headers, the wait is one minute. Each refusal in a sequence doubles it, to 16 minutes.
+- A request whose wait is longer than `maxWaitMs` (60 seconds) throws a `RestRateError` at once, and sends nothing.
+- The client refuses a path with a query, a segment `.` or `..`, a backslash or a space. Thus a request stays on its endpoint.
+- No error text of the client has the token or the body of an answer.
+- `state()` gives the counts of the client: the requests, the answers 304, the refusals for the rate and the wait.
+
 ## Use
 
 ```typescript
@@ -81,3 +106,5 @@ Under the root of a host (`mark --fs-root`, `procedure-server --fs-root`, `MCP_F
 ## Tests
 
 `pnpm --filter @procedures/gh test` runs the procedures with a fake shell. The tests examine each argument list, the JSON of `gh`, the failures and the values that cannot become options.
+
+The tests of the REST client use a fake transport and a fake clock. They examine the headers, the stored answers, the window of points, the waits after a refusal and the checks of a path.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./module.js";
 export * from "./types.js";
+export * from "./rest.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAE3B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -1,4 +1,6 @@
 // The root registers nothing: import "<package>/register", or give the module to createRegistry()
 export * from "./module.js";
 export * from "./types.js";
+// The REST client: conditional requests and the limits of the rate, with no process for each request
+export * from "./rest.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,qGAAqG;AACrG,cAAc,WAAW,CAAC"}

package/dist/rest.d.ts

@@ -0,0 +1,141 @@
+/**
+ * A client of the REST API of GitHub for a program that sends many requests: a dispatcher, a
+ * crawler or a loop that polls. It sends each request with `@procedures/http`, not with the `gh`
+ * CLI, so a request starts no process.
+ *
+ * - A GET with a stored answer is a conditional request. GitHub does not count an answer 304 for
+ *   the primary limit, and the client then gives the stored answer.
+ * - A sliding window of `@mark1russell7/service/limiter` holds the secondary limit: 900 points in
+ *   each minute. A GET costs 1 point, and a POST, a PUT, a PATCH or a DELETE costs 5 points.
+ * - A request that changes data waits one second after the request before it.
+ * - After a refusal for the rate, the client sends no request until the time that GitHub gives.
+ */
+import type { Clock } from "@mark1russell7/service/clock";
+/** The methods of a REST request. */
+export type RestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** One request to the REST API. */
+export interface RestRequest {
+    readonly method: RestMethod;
+    /** This path is the endpoint after the base URL, for example `/repos/octo/app/actions/runs`. It has no query. */
+    readonly path: string;
+    /** These fields are the query of the URL. The client sorts them, so one query has one URL. */
+    readonly query?: Readonly<Record<string, string>> | undefined;
+    /** This value is the JSON body. `null` and `undefined` are no body, and a GET has no body. */
+    readonly body?: unknown;
+}
+/** The answer to one request. */
+export interface RestAnswer {
+    /** This number is the status of the answer. A 304 with a stored answer gives 200. */
+    readonly status: number;
+    /** This value is the JSON body, or `null` for an empty body. */
+    readonly body: unknown;
+    /** This field is `true` when the body is the stored answer of an answer 304. */
+    readonly cached: boolean;
+}
+/** One exchange that a transport sends. */
+export interface RestExchange {
+    readonly method: RestMethod;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    /** This value is the JSON body, or `undefined` for no body. */
+    readonly body: unknown;
+}
+/** The reply of a transport: the status, the headers and the JSON body. */
+export interface RestReply {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string | readonly string[]>>;
+    readonly body: unknown;
+}
+/** A transport sends one exchange. It throws only when it gets no reply: each status is a reply. */
+export type RestTransport = (exchange: RestExchange, signal: AbortSignal) => Promise<RestReply>;
+/** The options of a REST client. */
+export interface RestClientOptions {
+    /** This value is the token, or a function that gives it before each request. A token of a GitHub App changes each hour. */
+    readonly token: string | (() => string | Promise<string>);
+    /** This URL is the base of the API. The default is `https://api.github.com`. */
+    readonly baseUrl?: string | undefined;
+    /** This text is the version of the API. The default is `2022-11-28`. */
+    readonly apiVersion?: string | undefined;
+    /** This text is the `user-agent` header. The default is `procedures-gh`. */
+    readonly userAgent?: string | undefined;
+    /** This count is the points of the secondary limit in each minute. The default is 900. */
+    readonly pointsPerMinute?: number | undefined;
+    /** This count is the most stored answers. The default is 1,000, and 0 stores no answer. */
+    readonly cacheEntries?: number | undefined;
+    /** This time is the longest wait of a request for the limits, in milliseconds. The default is 60,000. */
+    readonly maxWaitMs?: number | undefined;
+    /** This transport sends each exchange. The default sends it with `httpRequest` of `@procedures/http`. */
+    readonly transport?: RestTransport | undefined;
+    /** This clock gives the monotonic time and the timers. The default is the clock of the platform. */
+    readonly clock?: Clock | undefined;
+}
+/** The counts of a REST client, for a log or a measure. */
+export interface RestClientState {
+    /** This count is the exchanges that the transport sent. */
+    readonly sent: number;
+    /** This count is the answers 304 that gave a stored answer. */
+    readonly notModified: number;
+    /** This count is the refusals for the rate. */
+    readonly rateRefusals: number;
+    /** This count is the stored answers. */
+    readonly cacheEntries: number;
+    /** This number is the last `x-ratelimit-remaining` of GitHub, or `null` before it. */
+    readonly remaining: number | null;
+    /** This time is the wait until the client sends again after a refusal for the rate, in milliseconds. */
+    readonly blockedForMs: number;
+}
+/** A client of the REST API of GitHub. */
+export interface RestClient {
+    /** This method sends one request. It throws when it gets no answer or when the wait for a limit is too long. */
+    request(request: RestRequest, signal: AbortSignal): Promise<RestAnswer>;
+    /** This method gives the counts of the client. */
+    state(): RestClientState;
+}
+/** This error tells that a request did not start because the wait for a limit is longer than `maxWaitMs`. */
+export declare class RestRateError extends Error {
+    readonly name = "RestRateError";
+    /** This time is the wait until the request can start, in milliseconds. */
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
+/** The base URL of the REST API of GitHub. */
+export declare const GITHUB_API_URL: string;
+/** The version of the REST API that the client asks for. */
+export declare const GITHUB_API_VERSION: string;
+/** The points of the secondary limit of GitHub in each minute. */
+export declare const GITHUB_POINTS_PER_MINUTE: number;
+/** The points of a GET, and of a request that changes data. */
+export declare const GITHUB_POINTS: {
+    readonly read: number;
+    readonly write: number;
+};
+/** The wait after a refusal for the rate with no time in its headers: one minute, then two times longer, to 16 minutes. */
+export declare const RATE_WAIT_MS: {
+    readonly first: number;
+    readonly last: number;
+};
+/** The longest wait that the headers of an answer can set: one hour and one minute. */
+export declare const LONGEST_RATE_WAIT_MS: number;
+/**
+ * This function decides the wait after a refusal for the rate, in milliseconds, by the rules of
+ * GitHub. A `retry-after` header gives the wait. With `x-ratelimit-remaining` 0, the wait ends at
+ * `x-ratelimit-reset`, on the time of the `date` header. Else the wait is one minute, two times
+ * longer for each refusal in a sequence, to 16 minutes.
+ */
+export declare function rateWaitMs(reply: RestReply, strikes: number): number;
+/**
+ * This function tells if a reply is a refusal for the rate. GitHub refuses with 429, or with 403
+ * and one of these: `x-ratelimit-remaining` 0, a `retry-after` header, or a message about a rate limit.
+ */
+export declare function isRateRefusal(reply: RestReply): boolean;
+/**
+ * The default transport: `httpRequest` of `@procedures/http`, with its host policy and its limits of size and time.
+ * A redirect to another origin does not send the token. The transport parses the JSON itself, so an error text has no part of the body.
+ */
+export declare const httpTransport: RestTransport;
+/**
+ * This function makes a client of the REST API of GitHub. It refuses options that are not valid with
+ * a `RangeError` or a `TypeError`. No error text of the client has the token or the body of an answer.
+ */
+export declare function createRestClient(options: RestClientOptions): RestClient;
+//# sourceMappingURL=rest.d.ts.map

package/dist/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../src/rest.ts"],"names":[],"mappings":"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"}

package/dist/rest.js

@@ -0,0 +1,296 @@
+/**
+ * A client of the REST API of GitHub for a program that sends many requests: a dispatcher, a
+ * crawler or a loop that polls. It sends each request with `@procedures/http`, not with the `gh`
+ * CLI, so a request starts no process.
+ *
+ * - A GET with a stored answer is a conditional request. GitHub does not count an answer 304 for
+ *   the primary limit, and the client then gives the stored answer.
+ * - A sliding window of `@mark1russell7/service/limiter` holds the secondary limit: 900 points in
+ *   each minute. A GET costs 1 point, and a POST, a PUT, a PATCH or a DELETE costs 5 points.
+ * - A request that changes data waits one second after the request before it.
+ * - After a refusal for the rate, the client sends no request until the time that GitHub gives.
+ */
+import { realClock } from "@mark1russell7/service/clock";
+import { keyedLimiter, memoryStore, retryAfterSeconds } from "@mark1russell7/service/limiter";
+import { httpRequest } from "@procedures/http";
+/** This error tells that a request did not start because the wait for a limit is longer than `maxWaitMs`. */
+export class RestRateError extends Error {
+    name = "RestRateError";
+    /** This time is the wait until the request can start, in milliseconds. */
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** The base URL of the REST API of GitHub. */
+export const GITHUB_API_URL = "https://api.github.com";
+/** The version of the REST API that the client asks for. */
+export const GITHUB_API_VERSION = "2022-11-28";
+/** The points of the secondary limit of GitHub in each minute. */
+export const GITHUB_POINTS_PER_MINUTE = 900;
+/** The points of a GET, and of a request that changes data. */
+export const GITHUB_POINTS = { read: 1, write: 5 };
+/** The wait after a refusal for the rate with no time in its headers: one minute, then two times longer, to 16 minutes. */
+export const RATE_WAIT_MS = { first: 60_000, last: 960_000 };
+/** The longest wait that the headers of an answer can set: one hour and one minute. */
+export const LONGEST_RATE_WAIT_MS = 3_660_000;
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const isCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+/** This function gives one header of a reply with its name in lowercase, or `undefined`. */
+function header(reply, name) {
+    for (const [key, value] of Object.entries(reply.headers)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        return typeof value === "string" ? value : value.join(", ");
+    }
+    return undefined;
+}
+/** This function reads a whole number of 0 or more from a header, or gives `null`. */
+function wholeNumber(text) {
+    if (text === undefined || !/^\s*\d{1,15}\s*$/.test(text))
+        return null;
+    return Number(text.trim());
+}
+/** This function examines the path of a request. A path that can leave its endpoint is refused. */
+function checkedPath(path) {
+    if (typeof path !== "string" || !path.startsWith("/") || path.includes("//") || /[?#\\\s\u0000-\u001f\u007f]/.test(path)) {
+        throw new TypeError("The path of a REST request is not a path that starts with / and has no query.");
+    }
+    const segments = path.split("/").slice(1);
+    if (segments.some((segment) => /^(\.|%2e){1,2}$/i.test(segment))) {
+        throw new TypeError("The path of a REST request has a segment . or ..");
+    }
+    return path;
+}
+/**
+ * This function decides the wait after a refusal for the rate, in milliseconds, by the rules of
+ * GitHub. A `retry-after` header gives the wait. With `x-ratelimit-remaining` 0, the wait ends at
+ * `x-ratelimit-reset`, on the time of the `date` header. Else the wait is one minute, two times
+ * longer for each refusal in a sequence, to 16 minutes.
+ */
+export function rateWaitMs(reply, strikes) {
+    const retryAfter = wholeNumber(header(reply, "retry-after"));
+    if (retryAfter !== null)
+        return Math.min(retryAfter * 1000, LONGEST_RATE_WAIT_MS);
+    const remaining = wholeNumber(header(reply, "x-ratelimit-remaining"));
+    const reset = wholeNumber(header(reply, "x-ratelimit-reset"));
+    const date = Date.parse(header(reply, "date") ?? "");
+    if (remaining === 0 && reset !== null && Number.isFinite(date)) {
+        return Math.min(Math.max(reset * 1000 - date, 0) + 1000, LONGEST_RATE_WAIT_MS);
+    }
+    return Math.min(RATE_WAIT_MS.first * 2 ** Math.max(strikes, 0), RATE_WAIT_MS.last);
+}
+/**
+ * This function tells if a reply is a refusal for the rate. GitHub refuses with 429, or with 403
+ * and one of these: `x-ratelimit-remaining` 0, a `retry-after` header, or a message about a rate limit.
+ */
+export function isRateRefusal(reply) {
+    if (reply.status === 429)
+        return true;
+    if (reply.status !== 403)
+        return false;
+    if (wholeNumber(header(reply, "x-ratelimit-remaining")) === 0)
+        return true;
+    if (header(reply, "retry-after") !== undefined)
+        return true;
+    const message = typeof reply.body === "object" && reply.body !== null ? reply.body.message : undefined;
+    return typeof message === "string" && /rate limit/i.test(message);
+}
+/**
+ * The default transport: `httpRequest` of `@procedures/http`, with its host policy and its limits of size and time.
+ * A redirect to another origin does not send the token. The transport parses the JSON itself, so an error text has no part of the body.
+ */
+export const httpTransport = async (exchange, signal) => {
+    const reply = await httpRequest({ method: exchange.method, url: exchange.url, headers: { ...exchange.headers }, json: exchange.body, responseType: "text" }, { signal });
+    const text = typeof reply.body === "string" ? reply.body : "";
+    let body = null;
+    if (text.trim().length > 0) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`The answer ${reply.status} to ${exchange.method} ${new URL(exchange.url).pathname.slice(0, 200)} is not JSON.`);
+        }
+    }
+    return { status: reply.status, headers: reply.headers, body };
+};
+/** This function waits on the clock. The signal ends the wait with an error. */
+function pause(clock, ms, signal, what) {
+    // A wait on a clock with a signal has no function in @mark1russell7/algebra/clock yet. This copy goes when it has one.
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new Error(`The signal stopped the request ${what}.`));
+            return;
+        }
+        const stop = () => {
+            cancel();
+            reject(new Error(`The signal stopped the request ${what}.`));
+        };
+        const cancel = clock.after(ms, () => {
+            signal.removeEventListener("abort", stop);
+            resolve();
+        });
+        signal.addEventListener("abort", stop, { once: true });
+    });
+}
+/**
+ * This function makes a client of the REST API of GitHub. It refuses options that are not valid with
+ * a `RangeError` or a `TypeError`. No error text of the client has the token or the body of an answer.
+ */
+export function createRestClient(options) {
+    const base = new URL(options.baseUrl ?? GITHUB_API_URL);
+    if (base.protocol !== "https:" || base.search !== "" || base.hash !== "" || base.username !== "" || base.password !== "") {
+        throw new TypeError("The base URL of a REST client is not an https URL with no query and no credential.");
+    }
+    const basePath = base.pathname.replace(/\/+$/, "");
+    const apiVersion = options.apiVersion ?? GITHUB_API_VERSION;
+    const userAgent = options.userAgent ?? "procedures-gh";
+    for (const [name, value] of [["version", apiVersion], ["user agent", userAgent]]) {
+        if (typeof value !== "string" || value.length === 0 || /[\r\n]/.test(value)) {
+            throw new TypeError(`The ${name} of a REST client is not a text with a character and no line break.`);
+        }
+    }
+    const pointsPerMinute = options.pointsPerMinute ?? GITHUB_POINTS_PER_MINUTE;
+    if (!Number.isSafeInteger(pointsPerMinute) || pointsPerMinute < GITHUB_POINTS.write) {
+        throw new RangeError(`The points of a REST client in each minute are not a whole number of ${GITHUB_POINTS.write} or more.`);
+    }
+    const cacheEntries = options.cacheEntries ?? 1000;
+    if (!isCount(cacheEntries))
+        throw new RangeError("The stored answers of a REST client are not a whole number of 0 or more.");
+    const maxWaitMs = options.maxWaitMs ?? 60_000;
+    if (!isCount(maxWaitMs))
+        throw new RangeError("The longest wait of a REST client is not a whole number of milliseconds of 0 or more.");
+    if (typeof options.token !== "string" && typeof options.token !== "function") {
+        throw new TypeError("The token of a REST client is not a text or a function.");
+    }
+    const transport = options.transport ?? httpTransport;
+    const clock = options.clock ?? realClock;
+    const store = memoryStore(clock);
+    const points = keyedLimiter("github-points", { key: "token", policy: { type: "sliding-window", limit: { value: pointsPerMinute, unit: "count" }, window: { value: 60, unit: "s" } }, store: { kind: "local" }, evict: { maxKeys: { value: 1, unit: "count" } } }, store);
+    const writes = keyedLimiter("github-writes", { key: "token", policy: { type: "sliding-window", limit: { value: 1, unit: "count" }, window: { value: 1, unit: "s" } }, store: { kind: "local" }, evict: { maxKeys: { value: 1, unit: "count" } } }, store);
+    const cache = new Map();
+    let blockedUntil = Number.NEGATIVE_INFINITY;
+    let strikes = 0;
+    let remaining = null;
+    let sent = 0;
+    let notModified = 0;
+    let rateRefusals = 0;
+    const token = async () => {
+        const value = typeof options.token === "string" ? options.token : await options.token();
+        if (typeof value !== "string" || value.length === 0 || /[\s]/.test(value)) {
+            throw new TypeError("The token of a REST client is not a text with a character and no space or line break.");
+        }
+        return value;
+    };
+    /** This function waits until the limiter permits a take, or throws when the wait passes the deadline. */
+    const admit = async (limiter, units, deadline, signal, what) => {
+        for (;;) {
+            const decision = limiter.tryTakeSync("token", units);
+            if (decision.allowed)
+                return;
+            if (decision.cause === "capacity")
+                throw new RangeError(`The request ${what} costs more points than a minute has.`);
+            const wait = Math.max(1, retryAfterSeconds(decision.retryAfter)) * 1000;
+            if (clock.now() + wait > deadline)
+                throw new RestRateError(`The request ${what} waits ${wait} ms for the limit of the rate, more than its longest wait.`, wait);
+            await pause(clock, wait, signal, what);
+        }
+    };
+    /** This function waits until the block of a refusal for the rate ends, or throws when the block passes the deadline. */
+    const unblocked = async (deadline, signal, what) => {
+        for (;;) {
+            const blocked = Math.ceil(blockedUntil - clock.now());
+            if (blocked <= 0)
+                return;
+            if (clock.now() + blocked > deadline) {
+                throw new RestRateError(`GitHub refused a request for the rate. The request ${what} waits ${blocked} ms, more than its longest wait.`, blocked);
+            }
+            await pause(clock, blocked, signal, what);
+        }
+    };
+    const urlOf = (request) => {
+        const url = new URL(base.origin);
+        url.pathname = basePath + checkedPath(request.path);
+        const query = request.query ?? {};
+        if (typeof query !== "object" || query === null)
+            throw new TypeError("The query of a REST request is not a record of texts.");
+        for (const key of Object.keys(query).sort()) {
+            const value = query[key];
+            if (typeof value !== "string")
+                throw new TypeError(`The query field ${JSON.stringify(key)} of a REST request is not a text.`);
+            url.searchParams.append(key, value);
+        }
+        return url.href;
+    };
+    return {
+        async request(request, signal) {
+            if (typeof request !== "object" || request === null || !METHODS.includes(request.method)) {
+                throw new TypeError("The method of a REST request is not GET, POST, PUT, PATCH or DELETE.");
+            }
+            const what = `${request.method} ${typeof request.path === "string" ? request.path.slice(0, 200) : "?"}`;
+            const url = urlOf(request);
+            const read = request.method === "GET";
+            const body = request.body === null ? undefined : request.body;
+            if (read && body !== undefined)
+                throw new TypeError(`The request ${what} is a GET with a body.`);
+            if (signal.aborted)
+                throw new Error(`The signal stopped the request ${what}.`);
+            const deadline = clock.now() + maxWaitMs;
+            await unblocked(deadline, signal, what);
+            if (!read)
+                await admit(writes, 1, deadline, signal, what);
+            await admit(points, read ? GITHUB_POINTS.read : GITHUB_POINTS.write, deadline, signal, what);
+            // A refusal for the rate can come during the waits for the limiters, so the client examines the block again.
+            await unblocked(deadline, signal, what);
+            const headers = {
+                accept: "application/vnd.github+json",
+                authorization: `Bearer ${await token()}`,
+                "user-agent": userAgent,
+                "x-github-api-version": apiVersion,
+            };
+            const stored = read && cacheEntries > 0 ? cache.get(url) : undefined;
+            if (stored !== undefined)
+                headers["if-none-match"] = stored.etag;
+            sent += 1;
+            const reply = await transport({ method: request.method, url, headers, body }, signal);
+            if (!isCount(reply.status))
+                throw new Error(`The transport gave the request ${what} a status that is not a number.`);
+            const left = wholeNumber(header(reply, "x-ratelimit-remaining"));
+            if (left !== null)
+                remaining = left;
+            if (isRateRefusal(reply)) {
+                rateRefusals += 1;
+                blockedUntil = Math.max(blockedUntil, clock.now() + rateWaitMs(reply, strikes));
+                strikes += 1;
+                return { status: reply.status, body: reply.body ?? null, cached: false };
+            }
+            strikes = 0;
+            if (left === 0)
+                blockedUntil = Math.max(blockedUntil, clock.now() + rateWaitMs(reply, 0));
+            if (read && reply.status === 304 && stored !== undefined) {
+                notModified += 1;
+                cache.delete(url);
+                cache.set(url, stored);
+                return { status: 200, body: structuredClone(stored.body), cached: true };
+            }
+            if (read && cacheEntries > 0) {
+                const etag = header(reply, "etag");
+                if (reply.status === 200 && etag !== undefined && etag.length > 0) {
+                    cache.delete(url);
+                    cache.set(url, { etag, body: structuredClone(reply.body ?? null) });
+                    while (cache.size > cacheEntries)
+                        cache.delete(cache.keys().next().value);
+                }
+                else {
+                    cache.delete(url);
+                }
+            }
+            return { status: reply.status, body: reply.body ?? null, cached: false };
+        },
+        state() {
+            return { sent, notModified, rateRefusals, cacheEntries: cache.size, remaining, blockedForMs: Math.max(0, blockedUntil - clock.now()) };
+        },
+    };
+}
+//# sourceMappingURL=rest.js.map

package/dist/rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.js","sourceRoot":"","sources":["../src/rest.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/gh",
-  "version": "0.55.0",
-  "description": "The GitHub CLI as procedures: pull requests, workflow runs and artifacts, releases, issues and the GitHub API, with an argument list and no shell.",
+  "version": "0.55.1",
+  "description": "The GitHub CLI as procedures: pull requests, workflow runs and artifacts, releases, issues and the GitHub API, with an argument list and no shell. Also a REST client with conditional requests and the limits of the rate.",
   "keywords": [
     "procedures",
     "github",
@@ -53,11 +53,11 @@
     "./dist/register.js"
   ],
   "devDependencies": {
-    "typescript": "^7.0.2",
-    "@types/node": "^22.0.0",
     "@mark1russell7/cue": "^2.1.1",
-    "vitest": "^5.0.3",
-    "@procedures/fs": "0.55.0"
+    "@procedures/fs": "0.55.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=22"
@@ -66,8 +66,10 @@
     "procedures": "./dist/register.js"
   },
   "dependencies": {
-    "@procedures/client": "0.55.0",
-    "@procedures/shell": "0.55.0",
+    "@mark1russell7/service": "^0.8.6",
+    "@procedures/client": "0.55.1",
+    "@procedures/http": "0.55.1",
+    "@procedures/shell": "0.55.1",
     "zod": "^4.6.5"
   },
   "publishConfig": {

package/src/index.ts

@@ -1,3 +1,5 @@
 // The root registers nothing: import "<package>/register", or give the module to createRegistry()
 export * from "./module.js";
 export * from "./types.js";
+// The REST client: conditional requests and the limits of the rate, with no process for each request
+export * from "./rest.js";

package/src/rest.ts

@@ -0,0 +1,396 @@
+/**
+ * A client of the REST API of GitHub for a program that sends many requests: a dispatcher, a
+ * crawler or a loop that polls. It sends each request with `@procedures/http`, not with the `gh`
+ * CLI, so a request starts no process.
+ *
+ * - A GET with a stored answer is a conditional request. GitHub does not count an answer 304 for
+ *   the primary limit, and the client then gives the stored answer.
+ * - A sliding window of `@mark1russell7/service/limiter` holds the secondary limit: 900 points in
+ *   each minute. A GET costs 1 point, and a POST, a PUT, a PATCH or a DELETE costs 5 points.
+ * - A request that changes data waits one second after the request before it.
+ * - After a refusal for the rate, the client sends no request until the time that GitHub gives.
+ */
+
+import type { Cancel, Clock } from "@mark1russell7/service/clock";
+import { realClock } from "@mark1russell7/service/clock";
+import { keyedLimiter, memoryStore, retryAfterSeconds, type LocalLimiter } from "@mark1russell7/service/limiter";
+import { httpRequest } from "@procedures/http";
+
+/** The methods of a REST request. */
+export type RestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** One request to the REST API. */
+export interface RestRequest {
+  readonly method: RestMethod;
+  /** This path is the endpoint after the base URL, for example `/repos/octo/app/actions/runs`. It has no query. */
+  readonly path: string;
+  /** These fields are the query of the URL. The client sorts them, so one query has one URL. */
+  readonly query?: Readonly<Record<string, string>> | undefined;
+  /** This value is the JSON body. `null` and `undefined` are no body, and a GET has no body. */
+  readonly body?: unknown;
+}
+
+/** The answer to one request. */
+export interface RestAnswer {
+  /** This number is the status of the answer. A 304 with a stored answer gives 200. */
+  readonly status: number;
+  /** This value is the JSON body, or `null` for an empty body. */
+  readonly body: unknown;
+  /** This field is `true` when the body is the stored answer of an answer 304. */
+  readonly cached: boolean;
+}
+
+/** One exchange that a transport sends. */
+export interface RestExchange {
+  readonly method: RestMethod;
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  /** This value is the JSON body, or `undefined` for no body. */
+  readonly body: unknown;
+}
+
+/** The reply of a transport: the status, the headers and the JSON body. */
+export interface RestReply {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string | readonly string[]>>;
+  readonly body: unknown;
+}
+
+/** A transport sends one exchange. It throws only when it gets no reply: each status is a reply. */
+export type RestTransport = (exchange: RestExchange, signal: AbortSignal) => Promise<RestReply>;
+
+/** The options of a REST client. */
+export interface RestClientOptions {
+  /** This value is the token, or a function that gives it before each request. A token of a GitHub App changes each hour. */
+  readonly token: string | (() => string | Promise<string>);
+  /** This URL is the base of the API. The default is `https://api.github.com`. */
+  readonly baseUrl?: string | undefined;
+  /** This text is the version of the API. The default is `2022-11-28`. */
+  readonly apiVersion?: string | undefined;
+  /** This text is the `user-agent` header. The default is `procedures-gh`. */
+  readonly userAgent?: string | undefined;
+  /** This count is the points of the secondary limit in each minute. The default is 900. */
+  readonly pointsPerMinute?: number | undefined;
+  /** This count is the most stored answers. The default is 1,000, and 0 stores no answer. */
+  readonly cacheEntries?: number | undefined;
+  /** This time is the longest wait of a request for the limits, in milliseconds. The default is 60,000. */
+  readonly maxWaitMs?: number | undefined;
+  /** This transport sends each exchange. The default sends it with `httpRequest` of `@procedures/http`. */
+  readonly transport?: RestTransport | undefined;
+  /** This clock gives the monotonic time and the timers. The default is the clock of the platform. */
+  readonly clock?: Clock | undefined;
+}
+
+/** The counts of a REST client, for a log or a measure. */
+export interface RestClientState {
+  /** This count is the exchanges that the transport sent. */
+  readonly sent: number;
+  /** This count is the answers 304 that gave a stored answer. */
+  readonly notModified: number;
+  /** This count is the refusals for the rate. */
+  readonly rateRefusals: number;
+  /** This count is the stored answers. */
+  readonly cacheEntries: number;
+  /** This number is the last `x-ratelimit-remaining` of GitHub, or `null` before it. */
+  readonly remaining: number | null;
+  /** This time is the wait until the client sends again after a refusal for the rate, in milliseconds. */
+  readonly blockedForMs: number;
+}
+
+/** A client of the REST API of GitHub. */
+export interface RestClient {
+  /** This method sends one request. It throws when it gets no answer or when the wait for a limit is too long. */
+  request(request: RestRequest, signal: AbortSignal): Promise<RestAnswer>;
+  /** This method gives the counts of the client. */
+  state(): RestClientState;
+}
+
+/** This error tells that a request did not start because the wait for a limit is longer than `maxWaitMs`. */
+export class RestRateError extends Error {
+  override readonly name = "RestRateError";
+  /** This time is the wait until the request can start, in milliseconds. */
+  readonly retryAfterMs: number;
+  constructor(message: string, retryAfterMs: number) {
+    super(message);
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** The base URL of the REST API of GitHub. */
+export const GITHUB_API_URL: string = "https://api.github.com";
+/** The version of the REST API that the client asks for. */
+export const GITHUB_API_VERSION: string = "2022-11-28";
+/** The points of the secondary limit of GitHub in each minute. */
+export const GITHUB_POINTS_PER_MINUTE: number = 900;
+/** The points of a GET, and of a request that changes data. */
+export const GITHUB_POINTS: { readonly read: number; readonly write: number } = { read: 1, write: 5 };
+/** The wait after a refusal for the rate with no time in its headers: one minute, then two times longer, to 16 minutes. */
+export const RATE_WAIT_MS: { readonly first: number; readonly last: number } = { first: 60_000, last: 960_000 };
+/** The longest wait that the headers of an answer can set: one hour and one minute. */
+export const LONGEST_RATE_WAIT_MS: number = 3_660_000;
+
+const METHODS: readonly string[] = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const isCount = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+
+/** This function gives one header of a reply with its name in lowercase, or `undefined`. */
+function header(reply: RestReply, name: string): string | undefined {
+  for (const [key, value] of Object.entries(reply.headers)) {
+    if (key.toLowerCase() !== name) continue;
+    return typeof value === "string" ? value : value.join(", ");
+  }
+  return undefined;
+}
+
+/** This function reads a whole number of 0 or more from a header, or gives `null`. */
+function wholeNumber(text: string | undefined): number | null {
+  if (text === undefined || !/^\s*\d{1,15}\s*$/.test(text)) return null;
+  return Number(text.trim());
+}
+
+/** This function examines the path of a request. A path that can leave its endpoint is refused. */
+function checkedPath(path: unknown): string {
+  if (typeof path !== "string" || !path.startsWith("/") || path.includes("//") || /[?#\\\s\u0000-\u001f\u007f]/.test(path)) {
+    throw new TypeError("The path of a REST request is not a path that starts with / and has no query.");
+  }
+  const segments = path.split("/").slice(1);
+  if (segments.some((segment) => /^(\.|%2e){1,2}$/i.test(segment))) {
+    throw new TypeError("The path of a REST request has a segment . or ..");
+  }
+  return path;
+}
+
+/**
+ * This function decides the wait after a refusal for the rate, in milliseconds, by the rules of
+ * GitHub. A `retry-after` header gives the wait. With `x-ratelimit-remaining` 0, the wait ends at
+ * `x-ratelimit-reset`, on the time of the `date` header. Else the wait is one minute, two times
+ * longer for each refusal in a sequence, to 16 minutes.
+ */
+export function rateWaitMs(reply: RestReply, strikes: number): number {
+  const retryAfter = wholeNumber(header(reply, "retry-after"));
+  if (retryAfter !== null) return Math.min(retryAfter * 1000, LONGEST_RATE_WAIT_MS);
+  const remaining = wholeNumber(header(reply, "x-ratelimit-remaining"));
+  const reset = wholeNumber(header(reply, "x-ratelimit-reset"));
+  const date = Date.parse(header(reply, "date") ?? "");
+  if (remaining === 0 && reset !== null && Number.isFinite(date)) {
+    return Math.min(Math.max(reset * 1000 - date, 0) + 1000, LONGEST_RATE_WAIT_MS);
+  }
+  return Math.min(RATE_WAIT_MS.first * 2 ** Math.max(strikes, 0), RATE_WAIT_MS.last);
+}
+
+/**
+ * This function tells if a reply is a refusal for the rate. GitHub refuses with 429, or with 403
+ * and one of these: `x-ratelimit-remaining` 0, a `retry-after` header, or a message about a rate limit.
+ */
+export function isRateRefusal(reply: RestReply): boolean {
+  if (reply.status === 429) return true;
+  if (reply.status !== 403) return false;
+  if (wholeNumber(header(reply, "x-ratelimit-remaining")) === 0) return true;
+  if (header(reply, "retry-after") !== undefined) return true;
+  const message = typeof reply.body === "object" && reply.body !== null ? (reply.body as { message?: unknown }).message : undefined;
+  return typeof message === "string" && /rate limit/i.test(message);
+}
+
+/**
+ * The default transport: `httpRequest` of `@procedures/http`, with its host policy and its limits of size and time.
+ * A redirect to another origin does not send the token. The transport parses the JSON itself, so an error text has no part of the body.
+ */
+export const httpTransport: RestTransport = async (exchange, signal) => {
+  const reply = await httpRequest(
+    { method: exchange.method, url: exchange.url, headers: { ...exchange.headers }, json: exchange.body, responseType: "text" },
+    { signal },
+  );
+  const text = typeof reply.body === "string" ? reply.body : "";
+  let body: unknown = null;
+  if (text.trim().length > 0) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new Error(`The answer ${reply.status} to ${exchange.method} ${new URL(exchange.url).pathname.slice(0, 200)} is not JSON.`);
+    }
+  }
+  return { status: reply.status, headers: reply.headers, body };
+};
+
+/** This function waits on the clock. The signal ends the wait with an error. */
+function pause(clock: Clock, ms: number, signal: AbortSignal, what: string): Promise<void> {
+  // A wait on a clock with a signal has no function in @mark1russell7/algebra/clock yet. This copy goes when it has one.
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new Error(`The signal stopped the request ${what}.`));
+      return;
+    }
+    const stop = (): void => {
+      cancel();
+      reject(new Error(`The signal stopped the request ${what}.`));
+    };
+    const cancel: Cancel = clock.after(ms, () => {
+      signal.removeEventListener("abort", stop);
+      resolve();
+    });
+    signal.addEventListener("abort", stop, { once: true });
+  });
+}
+
+interface Stored {
+  readonly etag: string;
+  readonly body: unknown;
+}
+
+/**
+ * This function makes a client of the REST API of GitHub. It refuses options that are not valid with
+ * a `RangeError` or a `TypeError`. No error text of the client has the token or the body of an answer.
+ */
+export function createRestClient(options: RestClientOptions): RestClient {
+  const base = new URL(options.baseUrl ?? GITHUB_API_URL);
+  if (base.protocol !== "https:" || base.search !== "" || base.hash !== "" || base.username !== "" || base.password !== "") {
+    throw new TypeError("The base URL of a REST client is not an https URL with no query and no credential.");
+  }
+  const basePath = base.pathname.replace(/\/+$/, "");
+  const apiVersion = options.apiVersion ?? GITHUB_API_VERSION;
+  const userAgent = options.userAgent ?? "procedures-gh";
+  for (const [name, value] of [["version", apiVersion], ["user agent", userAgent]] as const) {
+    if (typeof value !== "string" || value.length === 0 || /[\r\n]/.test(value)) {
+      throw new TypeError(`The ${name} of a REST client is not a text with a character and no line break.`);
+    }
+  }
+  const pointsPerMinute = options.pointsPerMinute ?? GITHUB_POINTS_PER_MINUTE;
+  if (!Number.isSafeInteger(pointsPerMinute) || pointsPerMinute < GITHUB_POINTS.write) {
+    throw new RangeError(`The points of a REST client in each minute are not a whole number of ${GITHUB_POINTS.write} or more.`);
+  }
+  const cacheEntries = options.cacheEntries ?? 1000;
+  if (!isCount(cacheEntries)) throw new RangeError("The stored answers of a REST client are not a whole number of 0 or more.");
+  const maxWaitMs = options.maxWaitMs ?? 60_000;
+  if (!isCount(maxWaitMs)) throw new RangeError("The longest wait of a REST client is not a whole number of milliseconds of 0 or more.");
+  if (typeof options.token !== "string" && typeof options.token !== "function") {
+    throw new TypeError("The token of a REST client is not a text or a function.");
+  }
+  const transport = options.transport ?? httpTransport;
+  const clock = options.clock ?? realClock;
+  const store = memoryStore(clock);
+  const points: LocalLimiter = keyedLimiter(
+    "github-points",
+    { key: "token", policy: { type: "sliding-window", limit: { value: pointsPerMinute, unit: "count" }, window: { value: 60, unit: "s" } }, store: { kind: "local" }, evict: { maxKeys: { value: 1, unit: "count" } } },
+    store,
+  );
+  const writes: LocalLimiter = keyedLimiter(
+    "github-writes",
+    { key: "token", policy: { type: "sliding-window", limit: { value: 1, unit: "count" }, window: { value: 1, unit: "s" } }, store: { kind: "local" }, evict: { maxKeys: { value: 1, unit: "count" } } },
+    store,
+  );
+  const cache = new Map<string, Stored>();
+  let blockedUntil = Number.NEGATIVE_INFINITY;
+  let strikes = 0;
+  let remaining: number | null = null;
+  let sent = 0;
+  let notModified = 0;
+  let rateRefusals = 0;
+
+  const token = async (): Promise<string> => {
+    const value = typeof options.token === "string" ? options.token : await options.token();
+    if (typeof value !== "string" || value.length === 0 || /[\s]/.test(value)) {
+      throw new TypeError("The token of a REST client is not a text with a character and no space or line break.");
+    }
+    return value;
+  };
+
+  /** This function waits until the limiter permits a take, or throws when the wait passes the deadline. */
+  const admit = async (limiter: LocalLimiter, units: number, deadline: number, signal: AbortSignal, what: string): Promise<void> => {
+    for (;;) {
+      const decision = limiter.tryTakeSync("token", units);
+      if (decision.allowed) return;
+      if (decision.cause === "capacity") throw new RangeError(`The request ${what} costs more points than a minute has.`);
+      const wait = Math.max(1, retryAfterSeconds(decision.retryAfter)) * 1000;
+      if (clock.now() + wait > deadline) throw new RestRateError(`The request ${what} waits ${wait} ms for the limit of the rate, more than its longest wait.`, wait);
+      await pause(clock, wait, signal, what);
+    }
+  };
+
+  /** This function waits until the block of a refusal for the rate ends, or throws when the block passes the deadline. */
+  const unblocked = async (deadline: number, signal: AbortSignal, what: string): Promise<void> => {
+    for (;;) {
+      const blocked = Math.ceil(blockedUntil - clock.now());
+      if (blocked <= 0) return;
+      if (clock.now() + blocked > deadline) {
+        throw new RestRateError(`GitHub refused a request for the rate. The request ${what} waits ${blocked} ms, more than its longest wait.`, blocked);
+      }
+      await pause(clock, blocked, signal, what);
+    }
+  };
+
+  const urlOf = (request: RestRequest): string => {
+    const url = new URL(base.origin);
+    url.pathname = basePath + checkedPath(request.path);
+    const query = request.query ?? {};
+    if (typeof query !== "object" || query === null) throw new TypeError("The query of a REST request is not a record of texts.");
+    for (const key of Object.keys(query).sort()) {
+      const value = query[key];
+      if (typeof value !== "string") throw new TypeError(`The query field ${JSON.stringify(key)} of a REST request is not a text.`);
+      url.searchParams.append(key, value);
+    }
+    return url.href;
+  };
+
+  return {
+    async request(request, signal) {
+      if (typeof request !== "object" || request === null || !METHODS.includes(request.method)) {
+        throw new TypeError("The method of a REST request is not GET, POST, PUT, PATCH or DELETE.");
+      }
+      const what = `${request.method} ${typeof request.path === "string" ? request.path.slice(0, 200) : "?"}`;
+      const url = urlOf(request);
+      const read = request.method === "GET";
+      const body = request.body === null ? undefined : request.body;
+      if (read && body !== undefined) throw new TypeError(`The request ${what} is a GET with a body.`);
+      if (signal.aborted) throw new Error(`The signal stopped the request ${what}.`);
+      const deadline = clock.now() + maxWaitMs;
+      await unblocked(deadline, signal, what);
+      if (!read) await admit(writes, 1, deadline, signal, what);
+      await admit(points, read ? GITHUB_POINTS.read : GITHUB_POINTS.write, deadline, signal, what);
+      // A refusal for the rate can come during the waits for the limiters, so the client examines the block again.
+      await unblocked(deadline, signal, what);
+
+      const headers: Record<string, string> = {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${await token()}`,
+        "user-agent": userAgent,
+        "x-github-api-version": apiVersion,
+      };
+      const stored = read && cacheEntries > 0 ? cache.get(url) : undefined;
+      if (stored !== undefined) headers["if-none-match"] = stored.etag;
+      sent += 1;
+      const reply = await transport({ method: request.method, url, headers, body }, signal);
+      if (!isCount(reply.status)) throw new Error(`The transport gave the request ${what} a status that is not a number.`);
+
+      const left = wholeNumber(header(reply, "x-ratelimit-remaining"));
+      if (left !== null) remaining = left;
+      if (isRateRefusal(reply)) {
+        rateRefusals += 1;
+        blockedUntil = Math.max(blockedUntil, clock.now() + rateWaitMs(reply, strikes));
+        strikes += 1;
+        return { status: reply.status, body: reply.body ?? null, cached: false };
+      }
+      strikes = 0;
+      if (left === 0) blockedUntil = Math.max(blockedUntil, clock.now() + rateWaitMs(reply, 0));
+
+      if (read && reply.status === 304 && stored !== undefined) {
+        notModified += 1;
+        cache.delete(url);
+        cache.set(url, stored);
+        return { status: 200, body: structuredClone(stored.body), cached: true };
+      }
+      if (read && cacheEntries > 0) {
+        const etag = header(reply, "etag");
+        if (reply.status === 200 && etag !== undefined && etag.length > 0) {
+          cache.delete(url);
+          cache.set(url, { etag, body: structuredClone(reply.body ?? null) });
+          while (cache.size > cacheEntries) cache.delete(cache.keys().next().value!);
+        } else {
+          cache.delete(url);
+        }
+      }
+      return { status: reply.status, body: reply.body ?? null, cached: false };
+    },
+    state() {
+      return { sent, notModified, rateRefusals, cacheEntries: cache.size, remaining, blockedForMs: Math.max(0, blockedUntil - clock.now()) };
+    },
+  };
+}