Commit d720210996a514368ba99f4860063110033d93fa | the-knife

apps/server/scripts/measure-pr-preview.ts+12-4

...	@@ -1,7 +1,7 @@	...	@@ -1,7 +1,7 @@
1	// Run with: node apps/server/scripts/measure-pr-preview.ts owner/repo 123 456	1	// Run with: node apps/server/scripts/measure-pr-preview.ts owner/repo 123 456
2	// Numbers form a session with shared repository-permission caches. Browser and	2	// Numbers form a session with shared repository-permission caches. Browser and
3	// service caches are excluded. Uses real GitHub reads, without a server or database.	3	// service caches are excluded. Uses real GitHub reads, without a server or database.
4	// Every GraphQL read carries `rateLimit`, so its cost is read off its own answer.	4	// Each GraphQL read asks for `rateLimit` here, so its cost is read off its own answer.
5	import * as NodeServices from "@effect/platform-node/NodeServices";	5	import * as NodeServices from "@effect/platform-node/NodeServices";
6	import * as Effect from "effect/Effect";	6	import * as Effect from "effect/Effect";
7	import * as Console from "effect/Console";	7	import * as Console from "effect/Console";
...	@@ -15,7 +15,7 @@ import * as GitHubPullRequestProvider from "../src/pullRequest/GitHubPullRequest	...	@@ -15,7 +15,7 @@ import * as GitHubPullRequestProvider from "../src/pullRequest/GitHubPullRequest
15	import * as GitHubApi from "../src/sourceControl/GitHubApi.ts";	15	import * as GitHubApi from "../src/sourceControl/GitHubApi.ts";
16	import * as GitHubCredentials from "../src/sourceControl/GitHubCredentials.ts";	16	import * as GitHubCredentials from "../src/sourceControl/GitHubCredentials.ts";
17	import * as ServerSettings from "../src/serverSettings.ts";	17	import * as ServerSettings from "../src/serverSettings.ts";
18	import * as GitHubGraphQlBudget from "../src/sourceControl/githubGraphQlBudget.ts";	18	import * as GitHubQuota from "../src/sourceControl/githubQuota.ts";
19	import * as SourceControlRateLimit from "../src/sourceControl/SourceControlRateLimit.ts";	19	import * as SourceControlRateLimit from "../src/sourceControl/SourceControlRateLimit.ts";
20	import * as VcsProcess from "../src/vcs/VcsProcess.ts";	20	import * as VcsProcess from "../src/vcs/VcsProcess.ts";
21		21
...	@@ -33,6 +33,14 @@ const decodeCost = Schema.decodeUnknownOption(	...	@@ -33,6 +33,14 @@ const decodeCost = Schema.decodeUnknownOption(
33	}),	33	}),
34	),	34	),
35	);	35	);
		36	/** The query with GitHub's own count of what it cost, for a read rather than a mutation. */
		37	function withRateLimit(query: string): string {
		38	const end = query.lastIndexOf("}");
		39	return query.trimStart().startsWith("mutation") \|\| end === -1
		40	? query
		41	: `${query.slice(0, end)}\n rateLimit { cost }\n${query.slice(end)}`;
		42	}
		43
36	const measuredApi = Layer.effect(	44	const measuredApi = Layer.effect(
37	GitHubApi.GitHubApi,	45	GitHubApi.GitHubApi,
38	Effect.gen(function* () {	46	Effect.gen(function* () {
...	@@ -40,7 +48,7 @@ const measuredApi = Layer.effect(	...	@@ -40,7 +48,7 @@ const measuredApi = Layer.effect(
40	return GitHubApi.GitHubApi.of({	48	return GitHubApi.GitHubApi.of({
41	...api,	49	...api,
42	graphql: (input) =>	50	graphql: (input) =>
43	api.graphql(input).pipe(	51	api.graphql({ ...input, query: withRateLimit(input.query) }).pipe(
44	Effect.tap((body) =>	52	Effect.tap((body) =>
45	Effect.sync(() =>	53	Effect.sync(() =>
46	reads.push({	54	reads.push({
...	@@ -66,7 +74,7 @@ const measuredApi = Layer.effect(	...	@@ -66,7 +74,7 @@ const measuredApi = Layer.effect(
66	}),	74	}),
67	).pipe(	75	).pipe(
68	Layer.provide(GitHubCredentials.layer.pipe(Layer.provide(ServerSettings.layerTest()))),	76	Layer.provide(GitHubCredentials.layer.pipe(Layer.provide(ServerSettings.layerTest()))),
69	Layer.provide(GitHubGraphQlBudget.layer),	77	Layer.provide(GitHubQuota.layer),
70	Layer.provide(SourceControlRateLimit.layer),	78	Layer.provide(SourceControlRateLimit.layer),
71	Layer.provide(FetchHttpClient.layer),	79	Layer.provide(FetchHttpClient.layer),
72	Layer.provide(VcsProcess.layer),	80	Layer.provide(VcsProcess.layer),

apps/server/src/pullRequest/GitHubPullRequestApi.test.ts+49-73

 @@ -15,7 +15,7 @@ import { HttpClient, HttpClientResponse } from "effect/http";
 import { AllowGitHubReserve } from "../sourceControl/GitHubApi.ts";
 import * as GitHubApi from "../sourceControl/GitHubApi.ts";
 import * as GitHubCredentials from "../sourceControl/GitHubCredentials.ts";
-import * as GitHubGraphQlBudget from "../sourceControl/githubGraphQlBudget.ts";
+import * as GitHubQuota from "../sourceControl/githubQuota.ts";
 import * as SourceControlRateLimit from "../sourceControl/SourceControlRateLimit.ts";
 import * as VcsProcess from "../vcs/VcsProcess.ts";
 import * as GitHubPullRequestApi from "./GitHubPullRequestApi.ts";
 @@ -69,26 +69,29 @@ const mockedStackMemberships = vi.fn<(call: ApiCall) => ApiAnswer>(() =>
 );
 /**
- * A transport that answers from the mocks above but spends the real GraphQL budget, the way
+ * A transport that answers from the mocks above but spends the real GraphQL quota from each
- * GitHubApi does, so the reserve and pause behaviour is still the module's to prove.
+ * answer's headers, the way GitHubApi does, so the reserve behaviour is still the module's to prove.
  */
 const mockApi = Layer.effect(
   GitHubApi.GitHubApi,
   Effect.gen(function* () {
-    const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
+    const quota = yield* GitHubQuota.GitHubQuota;
     return GitHubApi.GitHubApi.of({
       graphql: (input) =>
-        budget
+        GitHubApi.AllowGitHubReserve.pipe(
-          .query(input.host, input.query, input.allowReserve ? { allowReserve: true } : undefined)
+          Effect.flatMap((interactive) =>
-          .pipe(
+            quota.admit(input.host, "graphql", {
-            Effect.flatMap((query) =>
+              allowReserve: input.allowReserve ?? interactive,
-              (input.query.includes("query PullRequestStackMemberships")
+            }),
-                ? mockedStackMemberships
-                : mockedExecute)({ kind: "graphql", ...input, query }),
-            ),
-            Effect.map((answer) => answer.body),
-            Effect.tap((body) => budget.observe(input.host, body)),
           ),
+          Effect.andThen(() =>
+            (input.query.includes("query PullRequestStackMemberships")
+              ? mockedStackMemberships
+              : mockedExecute)({ kind: "graphql", ...input }),
+          ),
+          Effect.tap((answer) => quota.observe(input.host, answer.headers)),
+          Effect.map((answer) => answer.body),
+        ),
       rest: (input) => mockedExecute({ kind: "rest", ...input }),
       credential: (host) => mockedCredential(host),
     });
 @@ -98,7 +101,7 @@ const mockApi = Layer.effect(
 const layer = it.layer(
   GitHubPullRequestApi.layer.pipe(
     Layer.provideMerge(mockApi),
-    Layer.provideMerge(GitHubGraphQlBudget.layer),
+    Layer.provideMerge(GitHubQuota.layer),
     Layer.provide(NodeCrypto.layer),
     Layer.provide(VcsProcess.layer.pipe(Layer.provideMerge(NodeServices.layer))),
   ),
 @@ -109,8 +112,19 @@ function output(
   body: string,
   truncated = false,
   invalidUtf8 = false,
+  headers: Readonly<Record<string, string>> = {},
 ): GitHubApi.GitHubRestResponse {
-  return { status: 200, headers: {}, body, truncated, invalidUtf8 };
+  return { status: 200, headers, body, truncated, invalidUtf8 };
+}
+/** GitHub's GraphQL quota headers, leaving `remaining` of 5,000 until `resetAt`. */
+function graphqlQuota(remaining: number, resetAt = "2099-08-13T14:00:00Z") {
+  return {
+    "x-ratelimit-resource": "graphql",
+    "x-ratelimit-limit": "5000",
+    "x-ratelimit-remaining": String(remaining),
+    "x-ratelimit-reset": String(Date.parse(resetAt) / 1000),
+  };
 }
 /**
 @@ -493,7 +507,7 @@ it.effect(
         Effect.provide(
           GitHubApi.layer.pipe(
             Layer.provide(Layer.mergeAll(credentials, http)),
-            Layer.provide(GitHubGraphQlBudget.layer),
+            Layer.provide(GitHubQuota.layer),
             Layer.provide(SourceControlRateLimit.layer),
             Layer.merge(VcsProcess.layer),
             Layer.provideMerge(NodeServices.layer),
 @@ -538,15 +552,13 @@ it.effect(
 );
 layer("GitHubPullRequestApi.layer", (it) => {
-  it.effect("admits only one concurrent preview above the reserve and resumes after reset", () =>
+  it.effect("holds background previews once an answer reports the reserve, until it resets", () =>
     Effect.gen(function* () {
       const now = yield* Clock.currentTimeMillis;
-      const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
+      const quota = yield* GitHubQuota.GitHubQuota;
       const resetAt = "2099-08-13T14:00:00Z";
-      yield* budget.observe(
+      yield* quota.observe("preview-budget.example", graphqlQuota(501, resetAt));
-        "preview-budget.example",
+      // GitHub's count, not ours: the answer below reports the reserve has been reached.
-        encodeJson({ data: { rateLimit: { cost: 1, limit: 5_000, remaining: 501, resetAt } } }),
-      );
       mockedExecute.mockReturnValue(
         Effect.succeed(
           output(
 @@ -563,9 +575,11 @@ layer("GitHubPullRequestApi.layer", (it) => {
                     author: null,
                   },
                 },
-                rateLimit: { cost: 1, limit: 5_000, remaining: 500, resetAt },
               },
             }),
+            false,
+            false,
+            graphqlQuota(499, resetAt),
           ),
         ),
       );
 @@ -576,18 +590,9 @@ layer("GitHubPullRequestApi.layer", (it) => {
         host: "preview-budget.example",
         number: 7,
       };
-      const results = yield* Effect.all(
+      yield* cli.getPullRequestPreview(input);
-        Array.from({ length: 20 }, (_, index) =>
+      const held = yield* Effect.flip(cli.getPullRequestPreview({ ...input, number: 8 }));
-          cli.getPullRequestPreview({ ...input, number: index + 1 }).pipe(Effect.result),
+      expect(held._tag).toBe("SourceControlRateLimitPausedError");
-        ),
-        { concurrency: "unbounded" },
-      );
-      expect(results.filter((result) => result._tag === "Success")).toHaveLength(1);
-      for (const result of results) {
-        if (result._tag === "Failure") {
-          expect(result.failure._tag).toBe("SourceControlRateLimitPausedError");
-        }
-      }
       expect(mockedExecute).toHaveBeenCalledTimes(1);
       yield* TestClock.setTime(Date.parse(resetAt));
       yield* cli.getPullRequestPreview(input);
 @@ -3220,7 +3225,7 @@ layer("GitHubPullRequestApi.layer", (it) => {
     }),
   );
-  it.effect("accounts for the avatar lookup in the GraphQL budget", () =>
+  it.effect("looks up avatars by node id in one GraphQL read", () =>
     Effect.gen(function* () {
       mockedExecute.mockReturnValueOnce(
         Effect.succeed(
 @@ -3228,12 +3233,6 @@ layer("GitHubPullRequestApi.layer", (it) => {
             encodeJson({
               data: {
                 nodes: [{ login: "octocat", avatarUrl: "https://avatars/octocat" }],
-                rateLimit: {
-                  cost: 1,
-                  limit: 5_000,
-                  remaining: 4_999,
-                  resetAt: "2099-08-13T14:00:00Z",
-                },
               },
             }),
           ),
 @@ -3249,7 +3248,6 @@ layer("GitHubPullRequestApi.layer", (it) => {
       });
       expect(varsAt(0)).toEqual({ ids: ["MDQ6VXNlcjE="] });
-      expect(queryAt(0)).toContain("rateLimit { cost limit remaining resetAt }");
       expect(avatars.get("octocat")).toBe("https://avatars/octocat");
     }),
   );
 @@ -3852,22 +3850,7 @@ layer("GitHubPullRequestApi.layer", (it) => {
     Effect.gen(function* () {
       const response = coreResponse();
       mockedExecute.mockReturnValue(
-        Effect.succeed(
+        Effect.succeed(output(encodeJson(response), false, false, graphqlQuota(499))),
-          output(
-            encodeJson({
-              ...response,
-              data: {
-                ...response.data,
-                rateLimit: {
-                  cost: 1,
-                  limit: 5000,
-                  remaining: 500,
-                  resetAt: "2099-08-13T14:00:00Z",
-                },
-              },
-            }),
-          ),
-        ),
       );
       const cli = yield* GitHubPullRequestApi.GitHubPullRequestApi;
       const input = {
 @@ -4125,14 +4108,11 @@ layer("GitHubPullRequestApi.layer", (it) => {
                   viewerPermission: "READ",
                   pullRequest: { viewerCanUpdate: true, viewerDidAuthor: true },
                 },
-                rateLimit: {
-                  cost: 1,
-                  limit: 5_000,
-                  remaining: 500,
-                  resetAt: "2099-08-13T14:00:00Z",
-                },
               },
             }),
+            false,
+            false,
+            graphqlQuota(499),
           ),
         ),
       );
 @@ -4145,7 +4125,6 @@ layer("GitHubPullRequestApi.layer", (it) => {
       } as const;
       yield* cli.getViewerAccess(input);
-      expect(queryAt(0)).toContain("rateLimit { cost limit remaining resetAt }");
       const error = yield* Effect.flip(cli.getViewerAccess(input));
 @@ -4173,14 +4152,11 @@ layer("GitHubPullRequestApi.layer", (it) => {
                     viewerPermission: "READ",
                     pullRequest: { viewerCanUpdate: true, viewerDidAuthor: true },
                   },
-                  rateLimit: {
-                    cost: 1,
-                    limit: 5_000,
-                    remaining: 500,
-                    resetAt: "2099-08-13T14:00:00Z",
-                  },
                 },
               }),
+              false,
+              false,
+              graphqlQuota(499),
             ),
           ),
         )

apps/server/src/sourceControl/GitHubApi.test.ts+51-25

 @@ -12,7 +12,7 @@ import { HttpClient, HttpClientResponse, type HttpClientRequest } from "effect/h
 import * as GitHubApi from "./GitHubApi.ts";
 import * as GitHubCredentials from "./GitHubCredentials.ts";
-import * as GitHubGraphQlBudget from "./githubGraphQlBudget.ts";
+import * as GitHubQuota from "./githubQuota.ts";
 import * as SourceControlRateLimit from "./SourceControlRateLimit.ts";
 import * as VcsProcess from "../vcs/VcsProcess.ts";
 import * as ServerSettings from "../serverSettings.ts";
 @@ -49,7 +49,7 @@ function harness(respond: (request: HttpClientRequest.HttpClientRequest) => Resp
   );
   const layer = GitHubApi.layer.pipe(
     Layer.provide(Layer.mergeAll(credentials, http)),
-    Layer.provideMerge(GitHubGraphQlBudget.layer),
+    Layer.provideMerge(GitHubQuota.layer),
     Layer.provideMerge(SourceControlRateLimit.layer),
   );
   return { layer, requests, invalidations: () => invalidations };
 @@ -97,15 +97,8 @@ describe("environmentToken", () => {
 });
 describe("GitHubApi", () => {
-  it.effect("sends GraphQL with the token and records the reported budget", () => {
+  it.effect("sends GraphQL with the token, and the document as written", () => {
-    const { layer, requests } = harness(() =>
+    const { layer, requests } = harness(() => json({ data: { viewer: { login: "julius" } } }));
-      json({
-        data: {
-          viewer: { login: "julius" },
-          rateLimit: { cost: 1, limit: 5000, remaining: 4999, resetAt: "2026-10-05T13:00:00Z" },
-        },
-      }),
-    );
     return Effect.gen(function* () {
       yield* TestClock.setTime(NOW);
       const api = yield* GitHubApi.GitHubApi;
 @@ -117,11 +110,16 @@ describe("GitHubApi", () => {
       expect(body).toContain('"login":"julius"');
       expect(requests[0]!.url).toBe("https://api.github.com/graphql");
       expect(requests[0]!.headers.authorization).toBe("Bearer first");
+      // No `rateLimit` selection is added: the quota is read off the response headers.
+      const sent = requests[0]!.body;
+      expect(sent._tag === "Uint8Array" ? new TextDecoder().decode(sent.body) : "").toContain(
+        '"query":"query { viewer { login } }"',
+      );
     }).pipe(Effect.provide(layer));
   });
   it.effect(
-    "traces the operation, path, query and cost, never the query string or variables",
+    "traces the operation, path, query and quota, never the query string or variables",
     () => {
       const spans: Array<Tracer.NativeSpan> = [];
       const tracer = Tracer.make({
 @@ -134,17 +132,7 @@ describe("GitHubApi", () => {
       const { layer } = harness((request) =>
         request.url.endsWith("/graphql")
           ? json(
-              {
+              { data: { viewer: { login: "julius" } } },
-                data: {
-                  viewer: { login: "julius" },
-                  rateLimit: {
-                    cost: 3,
-                    limit: 5000,
-                    remaining: 4990,
-                    resetAt: "2026-10-05T13:00:00Z",
-                  },
-                },
-              },
               { headers: { "x-ratelimit-remaining": "4990", "x-ratelimit-resource": "graphql" } },
             )
           : json({ ok: true }, { headers: { "x-ratelimit-remaining": "4800" } }),
 @@ -168,8 +156,10 @@ describe("GitHubApi", () => {
         expect(graphql).toMatchObject({
           "github.operation": "getPullRequestDetail",
           "github.graphql.query": "query($body: String!) { viewer { login } }",
-          "github.graphql.cost": 3,
+        });
-          "github.graphql.remaining": 4990,
+        expect(Object.fromEntries(byName("GitHubApi.send")[0]!.attributes)).toMatchObject({
+          "github.ratelimit.remaining": 4990,
+          "github.ratelimit.resource": "graphql",
         });
         expect(String(graphql["github.graphql.query_hash"])).toMatch(/^[0-9a-f]{8}$/);
         const rest = Object.fromEntries(byName("GitHubApi.send")[1]!.attributes);
 @@ -258,6 +248,42 @@ describe("GitHubApi", () => {
     }).pipe(Effect.provide(layer));
   });
+  it.effect("keeps the last tenth of a quota for interactive requests until it resets", () => {
+    const reset = Math.floor(NOW / 1000) + 600;
+    const quota = (remaining: number) => ({
+      "x-ratelimit-resource": "core",
+      "x-ratelimit-limit": "5000",
+      "x-ratelimit-remaining": String(remaining),
+      "x-ratelimit-reset": String(reset),
+    });
+    let remaining = 499;
+    const { layer, requests } = harness((request) =>
+      request.url.endsWith("/graphql")
+        ? json({ data: { viewer: { id: "1" } } })
+        : json({ ok: true }, { headers: quota(remaining--) }),
+    );
+    return Effect.gen(function* () {
+      yield* TestClock.setTime(NOW);
+      const api = yield* GitHubApi.GitHubApi;
+      const read = { host: "github.com", operation: "sweep", path: "repos/acme/web/pulls" };
+      // The first answer leaves 499 of 5000, under the last tenth; the next background read waits.
+      yield* api.rest(read);
+      const refused = yield* Effect.flip(api.rest(read));
+      expect(refused).toMatchObject({
+        _tag: "SourceControlRateLimitPausedError",
+        retryAt: reset * 1000,
+      });
+      // A user's own request may spend the reserve, and GraphQL has a quota of its own.
+      yield* api.rest(read).pipe(Effect.provideService(GitHubApi.AllowGitHubReserve, true));
+      yield* api.graphql({ host: "github.com", operation: "x", query: "query { viewer { id } }" });
+      expect(requests).toHaveLength(3);
+      // The reset gives the background its quota back.
+      yield* TestClock.setTime(reset * 1000);
+      yield* api.rest(read);
+      expect(requests).toHaveLength(4);
+    }).pipe(Effect.provide(layer));
+  });
   it.effect("carries GitHub's own reason for a refused REST request", () => {
     const { layer } = harness(() =>
       json(

apps/server/src/sourceControl/GitHubApi.ts+19-31

 @@ -12,7 +12,7 @@ import { HttpClient, HttpClientRequest, type HttpClientResponse } from "effect/h
 import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
 import * as GitHubCredentials from "./GitHubCredentials.ts";
-import * as GitHubGraphQlBudget from "./githubGraphQlBudget.ts";
+import * as GitHubQuota from "./githubQuota.ts";
 import * as SourceControlRateLimit from "./SourceControlRateLimit.ts";
 const DEFAULT_TIMEOUT = Duration.seconds(30);
 @@ -218,16 +218,6 @@ function rateLimitAttributes(
   return attributes;
 }
-const decodeGraphQlCost = Schema.decodeUnknownOption(
-  Schema.fromJsonString(
-    Schema.Struct({
-      data: Schema.Struct({
-        rateLimit: Schema.Struct({ cost: Schema.Number, remaining: Schema.Number }),
-      }),
-    }),
-  ),
-);
 /** The pause GitHub asked for, from `retry-after` or the primary limit's reset. */
 function retryAtFrom(
   headers: Readonly<Record<string, string | undefined>>,
 @@ -354,7 +344,7 @@ function classify(input: {
 export const make = Effect.gen(function* () {
   const httpClient = yield* HttpClient.HttpClient;
   const credentials = yield* GitHubCredentials.GitHubCredentials;
-  const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
+  const quota = yield* GitHubQuota.GitHubQuota;
   const limits = yield* SourceControlRateLimit.SourceControlRateLimit;
   const gate = yield* Semaphore.make(CONCURRENCY);
 @@ -403,10 +393,17 @@ export const make = Effect.gen(function* () {
     });
     const { token, fingerprint } = yield* credential(host);
     const scope = yield* SourceControlRateLimit.CredentialScope;
+    // REST spends `core` and GraphQL its own quota, each with its own reserve. Every REST path
+    // this reads today is `core`; a `search/` read would need its own resource here. A refusal
+    // still pauses the whole host, the key PullRequestService records its own backoff under.
+    const resource = input.graphql === true ? "graphql" : "core";
     const key = { provider: "github" as const, host };
     const run = Effect.gen(function* () {
-      const lease = yield* limits
+      const lease = yield* quota
-        .check(key, input.allowReserve ? { allowPaused: true } : undefined)
+        .admit(host, resource, { allowReserve: input.allowReserve })
+        .pipe(
+          Effect.andThen(limits.check(key, input.allowReserve ? { allowPaused: true } : undefined)),
+        )
         .pipe(
           Effect.tapError((paused) =>
             Effect.annotateCurrentSpan({
 @@ -452,6 +449,7 @@ export const make = Effect.gen(function* () {
       );
       const headers = response.headers;
       const status = response.status;
+      yield* quota.observe(host, headers);
       yield* Effect.annotateCurrentSpan({
         "http.response.status_code": status,
         ...rateLimitAttributes(headers),
 @@ -556,17 +554,15 @@ export const make = Effect.gen(function* () {
             : input.query,
       });
       return yield* Effect.gen(function* () {
-        const query = yield* budget.query(
-          host,
-          input.query,
-          allowReserve ? { allowReserve: true } : undefined,
-        );
         const response = yield* send({
           host,
           operation: input.operation,
           request: HttpClientRequest.post(gitHubApiUrls(host).graphql).pipe(
             HttpClientRequest.acceptJson,
-            HttpClientRequest.bodyJsonUnsafe({ query, variables: input.variables ?? {} }),
+            HttpClientRequest.bodyJsonUnsafe({
+              query: input.query,
+              variables: input.variables ?? {},
+            }),
           ),
           maxResponseBytes: input.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
           allowReserve,
 @@ -581,14 +577,6 @@ export const make = Effect.gen(function* () {
             status: response.status,
           });
         }
-        yield* budget.observe(host, response.body);
-        const cost = Option.getOrUndefined(decodeGraphQlCost(response.body));
-        if (cost !== undefined) {
-          yield* Effect.annotateCurrentSpan({
-            "github.graphql.cost": cost.data.rateLimit.cost,
-            "github.graphql.remaining": cost.data.rateLimit.remaining,
-          });
-        }
         return response.body;
       }).pipe(Effect.provideService(SourceControlRateLimit.CredentialScope, scope));
     },
 @@ -600,11 +588,11 @@ export const make = Effect.gen(function* () {
 export const layer = Layer.effect(GitHubApi, make);
 /**
- * The transport with the credential, GraphQL budget and rate-limit pause it reads through. An
+ * The transport with the credential, quota reserve and rate-limit pause it reads through. An
- * application builds this once so every GitHub reader shares one budget and one pause per host.
+ * application builds this once so every GitHub reader shares one view of each quota per host.
  */
 export const layerWithDependencies = layer.pipe(
   Layer.provideMerge(GitHubCredentials.layer),
-  Layer.provideMerge(GitHubGraphQlBudget.layer),
+  Layer.provideMerge(GitHubQuota.layer),
   Layer.provideMerge(SourceControlRateLimit.layer),
 );

apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts+2

...	@@ -459,6 +459,8 @@ describe("GitHubSourceControlProvider writes", () => {	...	@@ -459,6 +459,8 @@ describe("GitHubSourceControlProvider writes", () => {
459	});	459	});
460	assert.strictEqual(requests[0]!.method, "POST");	460	assert.strictEqual(requests[0]!.method, "POST");
461	assert.strictEqual(requests[0]!.path, "repos/acme/web/pulls");	461	assert.strictEqual(requests[0]!.path, "repos/acme/web/pulls");
		462	// A user's own write, so the background's reserve is not held against it.
		463	assert.strictEqual(requests[0]!.allowReserve, true);
462	assert.deepStrictEqual(requests[0]!.body, {	464	assert.deepStrictEqual(requests[0]!.body, {
463	base: "main",	465	base: "main",
464	head: "me:feature",	466	head: "me:feature",

apps/server/src/sourceControl/GitHubSourceControlProvider.ts+9-1

 @@ -679,7 +679,12 @@ export const make = Effect.gen(function* () {
   const readViewerLogin = Effect.fn("GitHubSourceControlProvider.readViewerLogin")(function* (
     host: string,
   ) {
-    const response = yield* rest({ host, operation: "getViewer", path: "user" });
+    const response = yield* rest({
+      host,
+      operation: "getViewer",
+      path: "user",
+      allowReserve: true,
+    });
     const decoded = decodeViewerLogin(response.body);
     if (Result.isFailure(decoded)) {
       return yield* failure("GitHub request failed.", decoded.failure);
 @@ -944,6 +949,8 @@ export const make = Effect.gen(function* () {
           host: locator.host,
           operation: "createPullRequest",
           method: "POST",
+          // A user's own write may spend the reserve the background leaves for it.
+          allowReserve: true,
           path: `repos/${encodeURIComponent(locator.owner)}/${encodeURIComponent(locator.name)}/pulls`,
           // `owner:branch` is how the REST API takes a fork's head, the same as `gh --head`.
           // gh allows maintainer edits unless told otherwise; the API's default is not documented.
 @@ -990,6 +997,7 @@ export const make = Effect.gen(function* () {
             host,
             operation: "createRepository",
             method: "POST",
+            allowReserve: true,
             path:
               isViewer || owner === null ? "user/repos" : `orgs/${encodeURIComponent(owner)}/repos`,
             body: { name, private: input.visibility === "private" },

apps/server/src/sourceControl/githubGraphQlBudget.test.ts deleted-241

...	@@ -1,241 +0,0 @@
1	import { describe, expect, it } from "@effect/vitest";
2	import * as Effect from "effect/Effect";
3	import * as TestClock from "effect/testing/TestClock";
4
5	import * as GitHubGraphQlBudget from "./githubGraphQlBudget.ts";
6	import { CredentialScope } from "./SourceControlRateLimit.ts";
7
8	const RESET_AT = "2026-08-13T14:00:00.000Z";
9	const NEXT_RESET_AT = "2026-08-13T15:00:00.000Z";
10	const BEFORE_RESET = Date.parse("2026-08-13T13:30:00.000Z");
11	const AFTER_RESET = Date.parse("2026-08-13T14:00:01.000Z");
12
13	function rateLimit(remaining: number, limit = 5_000, resetAt = RESET_AT, cost = 14): string {
14	return JSON.stringify({
15	data: {
16	viewer: { login: "bilal" },
17	rateLimit: { cost, limit, remaining, resetAt },
18	},
19	});
20	}
21
22	describe("GitHub GraphQL budget", () => {
23	it.effect("adds rate metadata to a read query", () =>
24	Effect.gen(function* () {
25	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
26
27	const query = yield* budget.query(
28	"github.com",
29	'query { repository(owner: "acme", name: "web") { name } }',
30	);
31
32	expect(query).toContain("rateLimit { cost limit remaining resetAt }");
33	expect(query).toContain('repository(owner: "acme", name: "web") { name }');
34	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
35	);
36
37	it.effect("protects the last ten percent with the shared provider cooldown error", () =>
38	Effect.gen(function* () {
39	yield* TestClock.setTime(BEFORE_RESET);
40	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
41	yield* budget.observe("github.com", rateLimit(500));
42
43	const error = yield* Effect.flip(budget.query("github.com", "query { viewer { login } }"));
44	expect(error).toMatchObject({
45	_tag: "SourceControlRateLimitPausedError",
46	provider: "github",
47	host: "github.com",
48	retryAt: Date.parse(RESET_AT),
49	});
50	expect(error.message).toBe(
51	"github requests to github.com are paused until the rate limit resets.",
52	);
53
54	yield* TestClock.setTime(AFTER_RESET);
55	expect(yield* budget.query("github.com", "query { viewer { login } }")).toContain(
56	"rateLimit",
57	);
58	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
59	);
60
61	it.effect("keeps hosts isolated", () =>
62	Effect.gen(function* () {
63	yield* TestClock.setTime(BEFORE_RESET);
64	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
65	yield* budget.observe("github.com", rateLimit(0));
66
67	const error = yield* Effect.flip(budget.query("github.com", "query { viewer { login } }"));
68	expect(error._tag).toBe("SourceControlRateLimitPausedError");
69	expect(yield* budget.query("github.example.com", "query { viewer { login } }")).toContain(
70	"rateLimit",
71	);
72	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
73	);
74
75	it.effect("isolates query reservations and observations by credential", () =>
76	Effect.gen(function* () {
77	yield* TestClock.setTime(BEFORE_RESET);
78	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
79	const query = budget.query("github.com", "query { viewer { login } }");
80	yield* budget
81	.observe("github.com", rateLimit(0))
82	.pipe(Effect.provideService(CredentialScope, "first"));
83	yield* budget
84	.observe("github.com", rateLimit(5000))
85	.pipe(Effect.provideService(CredentialScope, "second"));
86	yield* query.pipe(Effect.provideService(CredentialScope, "second"));
87	const error = yield* query.pipe(Effect.provideService(CredentialScope, "first"), Effect.flip);
88	expect(error.retryAt).toBe(Date.parse(RESET_AT));
89	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
90	);
91
92	it.effect("keeps the lower remaining value from out-of-order responses", () =>
93	Effect.gen(function* () {
94	yield* TestClock.setTime(BEFORE_RESET);
95	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
96	yield* budget.observe("github.com", rateLimit(400));
97	yield* budget.observe("github.com", rateLimit(600));
98
99	const error = yield* Effect.flip(budget.query("github.com", "query { viewer { login } }"));
100	expect(error).toMatchObject({
101	_tag: "SourceControlRateLimitPausedError",
102	retryAt: Date.parse(RESET_AT),
103	});
104	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
105	);
106
107	it.effect("learns a cheaper observed cost without restoring reserved quota", () =>
108	Effect.gen(function* () {
109	yield* TestClock.setTime(BEFORE_RESET);
110	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
111	const query = "query { viewer { login } }";
112	yield* budget.observe("github.com", rateLimit(512, 5_000, RESET_AT, 8));
113	yield* budget.query("github.com", query);
114	// The admission reserved eight points, but the completed read only cost one.
115	yield* budget.observe("github.com", rateLimit(511, 5_000, RESET_AT, 1));
116
117	for (let count = 0; count < 4; count += 1) {
118	expect(yield* budget.query("github.com", query)).toContain("rateLimit");
119	}
120	const error = yield* Effect.flip(budget.query("github.com", query));
121	expect(error).toMatchObject({
122	_tag: "SourceControlRateLimitPausedError",
123	retryAt: Date.parse(RESET_AT),
124	});
125	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
126	);
127
128	it.effect("ignores a response from an older reset window", () =>
129	Effect.gen(function* () {
130	yield* TestClock.setTime(BEFORE_RESET);
131	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
132	yield* budget.observe("github.com", rateLimit(400, 5_000, NEXT_RESET_AT));
133	yield* budget.observe("github.com", rateLimit(1_000, 5_000, RESET_AT));
134
135	const error = yield* Effect.flip(budget.query("github.com", "query { viewer { login } }"));
136	expect(error).toMatchObject({
137	_tag: "SourceControlRateLimitPausedError",
138	retryAt: Date.parse(NEXT_RESET_AT),
139	});
140	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
141	);
142
143	it.effect("accepts a response from a later reset window", () =>
144	Effect.gen(function* () {
145	yield* TestClock.setTime(BEFORE_RESET);
146	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
147	yield* budget.observe("github.com", rateLimit(1_000));
148	yield* budget.observe("github.com", rateLimit(400, 5_000, NEXT_RESET_AT));
149
150	const error = yield* Effect.flip(budget.query("github.com", "query { viewer { login } }"));
151	expect(error).toMatchObject({
152	_tag: "SourceControlRateLimitPausedError",
153	retryAt: Date.parse(NEXT_RESET_AT),
154	});
155	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
156	);
157
158	it.effect("allows reads above the reserve", () =>
159	Effect.gen(function* () {
160	yield* TestClock.setTime(BEFORE_RESET);
161	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
162	yield* budget.observe("github.com", rateLimit(515));
163
164	expect(yield* budget.query("github.com", "query { viewer { login } }")).toContain(
165	"rateLimit",
166	);
167	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
168	);
169
170	it.effect("allows an interactive read to use the reserve", () =>
171	Effect.gen(function* () {
172	yield* TestClock.setTime(BEFORE_RESET);
173	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
174	yield* budget.observe("github.com", rateLimit(500));
175
176	expect(
177	yield* budget.query("github.com", "query { viewer { login } }", {
178	allowReserve: true,
179	}),
180	).toContain("rateLimit");
181	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
182	);
183
184	it.effect("reserves an admitted query cost before its response", () =>
185	Effect.gen(function* () {
186	yield* TestClock.setTime(BEFORE_RESET);
187	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
188	yield* budget.observe("github.com", rateLimit(514));
189
190	expect(yield* budget.query("github.com", "query { viewer { login } }")).toContain(
191	"rateLimit",
192	);
193	const error = yield* Effect.flip(budget.query("github.com", "query { viewer { login } }"));
194
195	expect(error).toMatchObject({
196	_tag: "SourceControlRateLimitPausedError",
197	retryAt: Date.parse(RESET_AT),
198	});
199	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
200	);
201
202	it.effect("stops interactive reads when the reserve is exhausted", () =>
203	Effect.gen(function* () {
204	yield* TestClock.setTime(BEFORE_RESET);
205	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
206	yield* budget.observe("github.com", rateLimit(1, 5000, RESET_AT, 1));
207	yield* budget.query("github.com", "query { viewer { login } }", { allowReserve: true });
208	const error = yield* budget
209	.query("github.com", "query { viewer { login } }", { allowReserve: true })
210	.pipe(Effect.flip);
211	expect(error.retryAt).toBe(Date.parse(RESET_AT));
212	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
213	);
214
215	it.effect("ignores malformed or partial rate metadata", () =>
216	Effect.gen(function* () {
217	yield* TestClock.setTime(BEFORE_RESET);
218	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
219	yield* budget.observe("github.com", "{");
220	yield* budget.observe(
221	"github.com",
222	'{"data":{"rateLimit":{"limit":0,"remaining":-1,"resetAt":"never"}}}',
223	);
224
225	expect(yield* budget.query("github.com", "query { viewer { login } }")).toContain(
226	"rateLimit",
227	);
228	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
229	);
230
231	it.effect("does not add a read field to a mutation", () =>
232	Effect.gen(function* () {
233	yield* TestClock.setTime(BEFORE_RESET);
234	const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
235	const mutation = "mutation { addComment(input: {}) { clientMutationId } }";
236	yield* budget.observe("github.com", rateLimit(0));
237
238	expect(yield* budget.query("github.com", mutation)).toBe(mutation);
239	}).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
240	);
241	});

apps/server/src/sourceControl/githubGraphQlBudget.ts deleted-150

...	@@ -1,150 +0,0 @@
1	import * as Clock from "effect/Clock";
2	import * as Context from "effect/Context";
3	import * as Effect from "effect/Effect";
4	import * as Layer from "effect/Layer";
5	import * as Ref from "effect/Ref";
6	import * as Predicate from "effect/Predicate";
7
8	import * as SourceControlRateLimit from "./SourceControlRateLimit.ts";
9
10	const GRAPHQL_RESERVE_RATIO = 0.1;
11	const RATE_LIMIT_SELECTION = "rateLimit { cost limit remaining resetAt }";
12
13	interface GraphQlBudgetSnapshot {
14	readonly cost: number;
15	readonly limit: number;
16	readonly remaining: number;
17	readonly resetAtMs: number;
18	}
19
20	export class GitHubGraphQlBudget extends Context.Service<
21	GitHubGraphQlBudget,
22	{
23	readonly query: (
24	host: string,
25	document: string,
26	options?: { readonly allowReserve: boolean },
27	) => Effect.Effect<string, SourceControlRateLimit.SourceControlRateLimitPausedError>;
28	readonly observe: (host: string, raw: string) => Effect.Effect<void>;
29	}
30	>()("t3/sourceControl/githubGraphQlBudget") {}
31
32	function hostKey(host: string): string {
33	return host.trim().toLowerCase();
34	}
35
36	function snapshotFrom(raw: string): GraphQlBudgetSnapshot \| null {
37	try {
38	const parsed: unknown = JSON.parse(raw);
39	if (
40	!Predicate.isObject(parsed) \|\|
41	!Predicate.isObject(parsed.data) \|\|
42	!Predicate.isObject(parsed.data.rateLimit)
43	) {
44	return null;
45	}
46	const { cost, limit, remaining, resetAt } = parsed.data.rateLimit;
47	if (
48	typeof cost !== "number" \|\|
49	!Number.isFinite(cost) \|\|
50	cost < 0 \|\|
51	typeof limit !== "number" \|\|
52	!Number.isFinite(limit) \|\|
53	limit <= 0 \|\|
54	typeof remaining !== "number" \|\|
55	!Number.isFinite(remaining) \|\|
56	remaining < 0 \|\|
57	typeof resetAt !== "string"
58	) {
59	return null;
60	}
61	const resetAtMs = Date.parse(resetAt);
62	return Number.isFinite(resetAtMs) ? { cost, limit, remaining, resetAtMs } : null;
63	} catch {
64	return null;
65	}
66	}
67
68	function isReadOperation(document: string): boolean {
69	const operation = document.trimStart();
70	return operation.startsWith("query") \|\| operation.startsWith("{");
71	}
72
73	function withRateLimit(document: string): string {
74	if (!isReadOperation(document)) return document;
75	const end = document.lastIndexOf("}");
76	if (end === -1 \|\| document.includes(RATE_LIMIT_SELECTION)) return document;
77	return `${document.slice(0, end)}\n ${RATE_LIMIT_SELECTION}\n${document.slice(end)}`;
78	}
79
80	/** @public Service construction is part of the canonical Effect module API. */
81	export const make = Effect.gen(function* () {
82	const snapshots = yield* Ref.make<ReadonlyMap<string, GraphQlBudgetSnapshot>>(new Map());
83
84	const query: GitHubGraphQlBudget["Service"]["query"] = Effect.fn("GitHubGraphQlBudget.query")(
85	function* (host, document, options) {
86	if (!isReadOperation(document)) return document;
87	const now = yield* Clock.currentTimeMillis;
88	const key = `${hostKey(host)}\0${yield* SourceControlRateLimit.CredentialScope}`;
89	const retryAt = yield* Ref.modify(snapshots, (current) => {
90	const snapshot = current.get(key);
91	if (snapshot === undefined) return [null, current] as const;
92	if (snapshot.resetAtMs <= now) {
93	const next = new Map(current);
94	next.delete(key);
95	return [null, next] as const;
96	}
97	const remaining = snapshot.remaining - Math.max(1, snapshot.cost);
98	if (
99	remaining < 0 \|\|
100	(options?.allowReserve !== true && remaining < snapshot.limit * GRAPHQL_RESERVE_RATIO)
101	) {
102	return [snapshot.resetAtMs, current] as const;
103	}
104	const next = new Map(current);
105	next.set(key, { ...snapshot, remaining });
106	return [null, next] as const;
107	});
108	if (retryAt !== null) {
109	return yield* new SourceControlRateLimit.SourceControlRateLimitPausedError({
110	provider: "github",
111	host: hostKey(host),
112	retryAt,
113	});
114	}
115	return withRateLimit(document);
116	},
117	);
118
119	const observe: GitHubGraphQlBudget["Service"]["observe"] = Effect.fn(
120	"GitHubGraphQlBudget.observe",
121	)(function* (host, raw) {
122	const snapshot = snapshotFrom(raw);
123	if (snapshot === null) return;
124	const key = `${hostKey(host)}\0${yield* SourceControlRateLimit.CredentialScope}`;
125	yield* Ref.update(snapshots, (current) => {
126	const previous = current.get(key);
127	// Concurrent reads can finish out of order. Quota only falls within one reset window, and
128	// an answer from an older window must not replace the current one.
129	if (previous !== undefined && snapshot.resetAtMs < previous.resetAtMs) {
130	return current;
131	}
132	const next = new Map(current);
133	// Keep the conservative balance, but learn the observed cost even when our reservation
134	// was larger. Otherwise one expensive read makes every later cheap read spend its cost.
135	next.set(
136	key,
137	previous !== undefined &&
138	snapshot.resetAtMs === previous.resetAtMs &&
139	snapshot.remaining >= previous.remaining
140	? { ...previous, cost: snapshot.cost }
141	: snapshot,
142	);
143	return next;
144	});
145	});
146
147	return GitHubGraphQlBudget.of({ query, observe });
148	});
149
150	export const layer = Layer.effect(GitHubGraphQlBudget, make);

apps/server/src/sourceControl/githubQuota.test.ts created+86

...	@@ -0,0 +1,86 @@
1	import { assert, describe, it } from "@effect/vitest";
2	import * as Effect from "effect/Effect";
3	import * as TestClock from "effect/testing/TestClock";
4
5	import * as GitHubQuota from "./githubQuota.ts";
6	import { CredentialScope } from "./SourceControlRateLimit.ts";
7
8	const RESET = Date.parse("2099-08-13T14:00:00Z");
9	const headers = (remaining: number, resource = "graphql", reset = RESET) => ({
10	"x-ratelimit-resource": resource,
11	"x-ratelimit-limit": "5000",
12	"x-ratelimit-remaining": String(remaining),
13	"x-ratelimit-reset": String(reset / 1000),
14	});
15
16	describe("GitHubQuota", () => {
17	it.effect("refuses a background request below the reserve, per quota and account", () =>
18	Effect.gen(function* () {
19	const quota = yield* GitHubQuota.GitHubQuota;
20	yield* quota.observe("github.com", headers(499));
21	const refused = yield* Effect.flip(quota.admit("github.com", "graphql"));
22	assert.strictEqual(refused.retryAt, RESET);
23	// Another quota, another host and another account each have their own balance.
24	yield* quota.admit("github.com", "core");
25	yield* quota.admit("ghe.example", "graphql");
26	yield* quota.admit("github.com", "graphql").pipe(Effect.provideService(CredentialScope, "b"));
27	yield* quota.admit("github.com", "graphql", { allowReserve: true });
28	}).pipe(Effect.provide(GitHubQuota.layer)),
29	);
30
31	it.effect("takes the latest balance in a window, and ignores an older window", () =>
32	Effect.gen(function* () {
33	const quota = yield* GitHubQuota.GitHubQuota;
34	yield* quota.observe("github.com", headers(400));
35	yield* Effect.flip(quota.admit("github.com", "graphql"));
36	// GitHub can report more left later in the same window, from another region.
37	yield* quota.observe("github.com", headers(900));
38	yield* quota.admit("github.com", "graphql");
39	yield* quota.observe("github.com", headers(400));
40	yield* Effect.flip(quota.admit("github.com", "graphql"));
41	// An answer from an older window says nothing about this one.
42	yield* quota.observe("github.com", headers(4000, "graphql", RESET - 3_600_000));
43	yield* Effect.flip(quota.admit("github.com", "graphql"));
44	// A later window replaces it.
45	yield* quota.observe("github.com", headers(4000, "graphql", RESET + 3_600_000));
46	yield* quota.admit("github.com", "graphql");
47	}).pipe(Effect.provide(GitHubQuota.layer)),
48	);
49
50	it.effect("lets interactive requests spend the reserve but not an empty quota", () =>
51	Effect.gen(function* () {
52	const quota = yield* GitHubQuota.GitHubQuota;
53	yield* quota.observe("github.com", headers(1));
54	yield* quota.admit("github.com", "graphql", { allowReserve: true });
55	yield* quota.observe("github.com", headers(0));
56	const refused = yield* Effect.flip(
57	quota.admit("github.com", "graphql", { allowReserve: true }),
58	);
59	assert.strictEqual(refused.retryAt, RESET);
60	}).pipe(Effect.provide(GitHubQuota.layer)),
61	);
62
63	it.effect("spends nothing locally, so a free 304 cannot run the balance down", () =>
64	Effect.gen(function* () {
65	const quota = yield* GitHubQuota.GitHubQuota;
66	yield* quota.observe("github.com", headers(501, "core"));
67	// Conditional reads answer 304 with the balance unchanged, however many are sent.
68	for (let index = 0; index < 5; index++) {
69	yield* quota.admit("github.com", "core");
70	yield* quota.observe("github.com", headers(501, "core"));
71	}
72	yield* quota.admit("github.com", "core");
73	}).pipe(Effect.provide(GitHubQuota.layer)),
74	);
75
76	it.effect("forgets a balance once its window resets, and ignores answers naming no quota", () =>
77	Effect.gen(function* () {
78	const quota = yield* GitHubQuota.GitHubQuota;
79	yield* quota.observe("github.com", headers(0));
80	yield* TestClock.setTime(RESET);
81	yield* quota.admit("github.com", "graphql");
82	yield* quota.observe("other.example", { "x-ratelimit-remaining": "0" });
83	yield* quota.admit("other.example", "graphql");
84	}).pipe(Effect.provide(GitHubQuota.layer)),
85	);
86	});

apps/server/src/sourceControl/githubQuota.ts created+122

...	@@ -0,0 +1,122 @@
1	import * as Clock from "effect/Clock";
2	import * as Context from "effect/Context";
3	import * as Effect from "effect/Effect";
4	import * as Layer from "effect/Layer";
5	import * as Ref from "effect/Ref";
6
7	import * as SourceControlRateLimit from "./SourceControlRateLimit.ts";
8
9	/** The share of each quota a background read leaves for a user's next click. */
10	const RESERVE_RATIO = 0.1;
11
12	/**
13	* GitHub's quotas: `core` for REST, `graphql` for GraphQL, and a few smaller ones (`search`, …).
14	* Each is spent and reset on its own, so each is tracked on its own.
15	*/
16	type GitHubQuotaResource = string;
17
18	interface QuotaSnapshot {
19	readonly limit: number;
20	readonly remaining: number;
21	readonly resetAtMs: number;
22	}
23
24	/**
25	* What GitHub says is left of one quota, from the `x-ratelimit-*` headers every API answer
26	* carries. Null when the answer named no quota, which an Enterprise host with limits off does.
27	*/
28	function quotaFromHeaders(
29	headers: Readonly<Record<string, string \| undefined>>,
30	): (QuotaSnapshot & { readonly resource: GitHubQuotaResource }) \| null {
31	const resource = headers["x-ratelimit-resource"]?.trim();
32	const limit = Number(headers["x-ratelimit-limit"]);
33	const remaining = Number(headers["x-ratelimit-remaining"]);
34	const reset = Number(headers["x-ratelimit-reset"]);
35	if (
36	!resource \|\|
37	!Number.isFinite(limit) \|\|
38	limit <= 0 \|\|
39	!Number.isFinite(remaining) \|\|
40	remaining < 0 \|\|
41	!Number.isFinite(reset)
42	) {
43	return null;
44	}
45	return { resource, limit, remaining, resetAtMs: reset * 1_000 };
46	}
47
48	/**
49	* Keeps the last tenth of each GitHub quota for interactive requests. A background sweep that
50	* would dip below it is refused until the quota resets, so a user's next click still has budget.
51	*
52	* The balance is GitHub's own count from the latest answer's headers, so it already includes
53	* what anything else spent with the same token, such as an agent's `gh` commands. Requests in
54	* flight together all see that one balance; the reserve absorbs what they spend before their
55	* answers land. Nothing is debited locally, because a 304 or a request that never reached GitHub
56	* spends nothing, and a local count would drift below GitHub's for the rest of the window.
57	*
58	* Interactive requests may spend the reserve, but not a quota GitHub already reported empty.
59	*/
60	export class GitHubQuota extends Context.Service<
61	GitHubQuota,
62	{
63	readonly admit: (
64	host: string,
65	resource: GitHubQuotaResource,
66	options?: { readonly allowReserve: boolean },
67	) => Effect.Effect<void, SourceControlRateLimit.SourceControlRateLimitPausedError>;
68	readonly observe: (
69	host: string,
70	headers: Readonly<Record<string, string \| undefined>>,
71	) => Effect.Effect<void>;
72	}
73	>()("t3/sourceControl/githubQuota") {}
74
75	const make = Effect.gen(function* () {
76	const snapshots = yield* Ref.make<ReadonlyMap<string, QuotaSnapshot>>(new Map());
77	const keyOf = (host: string, resource: string, scope: string) =>
78	`${host.trim().toLowerCase()}\0${resource}\0${scope}`;
79
80	const admit: GitHubQuota["Service"]["admit"] = Effect.fn("GitHubQuota.admit")(
81	function* (host, resource, options) {
82	const now = yield* Clock.currentTimeMillis;
83	const key = keyOf(host, resource, yield* SourceControlRateLimit.CredentialScope);
84	const snapshot = (yield* Ref.get(snapshots)).get(key);
85	if (snapshot === undefined \|\| snapshot.resetAtMs <= now) return;
86	const floor = options?.allowReserve === true ? 1 : snapshot.limit * RESERVE_RATIO;
87	if (snapshot.remaining >= floor) return;
88	return yield* new SourceControlRateLimit.SourceControlRateLimitPausedError({
89	provider: "github",
90	host: host.trim().toLowerCase(),
91	retryAt: snapshot.resetAtMs,
92	});
93	},
94	);
95
96	const observe: GitHubQuota["Service"]["observe"] = Effect.fn("GitHubQuota.observe")(
97	function* (host, headers) {
98	const quota = quotaFromHeaders(headers);
99	if (quota === null) return;
100	const key = keyOf(host, quota.resource, yield* SourceControlRateLimit.CredentialScope);
101	yield* Ref.update(snapshots, (current) => {
102	const previous = current.get(key);
103	// The latest answer wins. GitHub serves requests from several regions, so a later answer
104	// can report more left in the same window, and keeping the lower one would hold
105	// background work at the reserve until the reset. An answer from an older window says
106	// nothing of this one.
107	if (previous !== undefined && quota.resetAtMs < previous.resetAtMs) return current;
108	const next = new Map(current);
109	next.set(key, {
110	limit: quota.limit,
111	remaining: quota.remaining,
112	resetAtMs: quota.resetAtMs,
113	});
114	return next;
115	});
116	},
117	);
118
119	return GitHubQuota.of({ admit, observe });
120	});
121
122	export const layer = Layer.effect(GitHubQuota, make);

author	Julius Marminge <julius0216@outlook.com> 2026-10-07 17:26:26-07:00
committer	GitHub <noreply@github.com> 2026-10-07 17:26:26-07:00
log	d720210996a514368ba99f4860063110033d93fa
tree	fc99acf46fd9eb1a53983ca9952d7cbee7a73951
parent	42d92ec59775c187af69071c81b2b91180810bdd
signature	Signed by PGP key B5690EEEBB952194

refactor(server): GitHub rate limits read the response headers (#16986)