Open History to see the last commit
1import { normalizeHost } from "@t3tools/source-control-core/server/pullRequestUtils";
2import { SourceControlProviderKind } from "@t3tools/contracts";
3import * as Cause from "effect/Cause";
4import * as Clock from "effect/Clock";
5import * as Context from "effect/Context";
6import * as Duration from "effect/Duration";
7import * as Effect from "effect/Effect";
8import * as Layer from "effect/Layer";
9import * as Redacted from "effect/Redacted";
10import * as Schema from "effect/Schema";
11import * as Semaphore from "effect/Semaphore";
12import * as SourceControlRateLimit from "@t3tools/source-control-core/server/SourceControlRateLimit";
13
14import * as Option from "effect/Option";
15import * as Result from "effect/Result";
16
17import * as GitHubAppSignIn from "./GitHubAppSignIn.ts";
18import * as GitHubCredentials from "./GitHubCredentials.ts";
19import * as GitHubQuota from "./GitHubQuota.ts";
20
21const DEFAULT_TIMEOUT = Duration.seconds(30);
22/** GitHub's secondary limits penalize concurrent bursts. */
23const CONCURRENCY = 8;
24const REQUEST_HEADERS = { "x-github-api-version": "2022-11-28", "user-agent": "t3code" };
25
26/** Pin requests to this host's credential across account switches. Keep it out of RPCs/cache keys. */
27export const PinnedGitHubCredential = Context.Reference<{
28 readonly host: string;
29 readonly token: Redacted.Redacted<string>;
30 readonly credentialFingerprint: string;
31 readonly source?: GitHubCredentials.GitHubCredentialSource;
32} | null>("@t3tools/source-control-github/server/GitHubRequestPolicy/PinnedGitHubCredential", {
33 defaultValue: () => null,
34});
35
36export class GitHubApiRequestError extends Schema.TaggedError<GitHubApiRequestError>()(
37 "GitHubApiRequestError",
38 { host: Schema.String, operation: Schema.String, cause: Schema.Defect() },
39) {
40 override get message(): string {
41 return `Could not reach GitHub at ${this.host}.`;
42 }
43}
44
45export class GitHubApiAuthenticationError extends Schema.TaggedError<GitHubApiAuthenticationError>()(
46 "GitHubApiAuthenticationError",
47 { host: Schema.String, operation: Schema.String },
48) {
49 override get message(): string {
50 return `GitHub refused the credential for ${this.host}. Run \`gh auth login --hostname ${this.host}\` and retry.`;
51 }
52}
53
54export class GitHubApiRateLimitError extends Schema.TaggedError<GitHubApiRateLimitError>()(
55 "GitHubApiRateLimitError",
56 {
57 host: Schema.String,
58 operation: Schema.String,
59 retryAt: Schema.optionalKey(Schema.Finite),
60 },
61) {
62 override get message(): string {
63 return "GitHub API rate limit exceeded.";
64 }
65}
66
67export class GitHubApiNotFoundError extends Schema.TaggedError<GitHubApiNotFoundError>()(
68 "GitHubApiNotFoundError",
69 {
70 host: Schema.String,
71 operation: Schema.String,
72 githubErrors: Schema.optionalKey(Schema.Array(Schema.String)),
73 /** The source of the credential the refused request carried, when known. */
74 credential: Schema.optionalKey(GitHubCredentials.GitHubCredentialSource),
75 },
76) {
77 override get message(): string {
78 const missing =
79 "GitHub could not find the requested resource, or the credential cannot see it.";
80 return this.githubErrors !== undefined && this.githubErrors.length > 0
81 ? `${missing} GitHub said: ${this.githubErrors.join("; ")}`
82 : missing;
83 }
84}
85
86export class GitHubApiResponseError extends Schema.TaggedError<GitHubApiResponseError>()(
87 "GitHubApiResponseError",
88 {
89 host: Schema.String,
90 operation: Schema.String,
91 status: Schema.Int,
92 githubErrors: Schema.optionalKey(Schema.Array(Schema.String)),
93 githubErrorTypes: Schema.optionalKey(Schema.Array(Schema.NullOr(Schema.String))),
94 },
95) {
96 override get message(): string {
97 return this.githubErrors !== undefined && this.githubErrors.length > 0
98 ? `GitHub returned an error: ${this.githubErrors.join("; ")}`
99 : `GitHub returned HTTP ${this.status}.`;
100 }
101}
102
103export type GitHubApiError =
104 | GitHubCredentials.GitHubCredentialUnavailableError
105 | GitHubAppSignIn.GitHubAppSessionError
106 | GitHubApiRequestError
107 | GitHubApiAuthenticationError
108 | GitHubApiRateLimitError
109 | GitHubApiNotFoundError
110 | GitHubApiResponseError
111 | SourceControlRateLimit.SourceControlRateLimitPausedError;
112
113export function gitHubApiUrls(host: string): { readonly rest: string; readonly graphql: string } {
114 const normalized = normalizeHost(host);
115 if (normalized === "github.com") {
116 return { rest: "https://api.github.com", graphql: "https://api.github.com/graphql" };
117 }
118 if (normalized.endsWith(".ghe.com")) {
119 return {
120 rest: `https://api.${normalized}`,
121 graphql: `https://api.${normalized}/graphql`,
122 };
123 }
124 return { rest: `https://${normalized}/api/v3`, graphql: `https://${normalized}/api/graphql` };
125}
126
127function rateLimitAttributes(
128 headers: Readonly<Record<string, string | undefined>>,
129): Record<string, number | string> {
130 const attributes: Record<string, number | string> = {};
131 for (const [header, name] of [
132 ["x-ratelimit-limit", "github.ratelimit.limit"],
133 ["x-ratelimit-remaining", "github.ratelimit.remaining"],
134 ["x-ratelimit-used", "github.ratelimit.used"],
135 ["x-ratelimit-reset", "github.ratelimit.reset"],
136 ] as const) {
137 const value = Number(headers[header]);
138 if (headers[header] !== undefined && Number.isFinite(value)) attributes[name] = value;
139 }
140 const resource = headers["x-ratelimit-resource"];
141 if (resource !== undefined) attributes["github.ratelimit.resource"] = resource;
142 return attributes;
143}
144
145function retryAtFrom(
146 headers: Readonly<Record<string, string | undefined>>,
147 now: number,
148): number | undefined {
149 const fromRetryAfter = SourceControlRateLimit.retryAtFromHeader(headers["retry-after"], now);
150 if (fromRetryAfter !== undefined) return fromRetryAfter;
151 const reset = Number(headers["x-ratelimit-reset"]) * 1_000;
152 return Number.isFinite(reset) && reset > now ? reset : undefined;
153}
154
155/**
156 * HTTP 200 GraphQL rate limits use RATE_LIMITED or untyped errors with quota headers. A 403 is a
157 * limit only when its quota, body or GraphQL errors name one (older hosts say "abuse detection
158 * mechanism"): a proxy in front of GitHub Enterprise can refuse with `Retry-After` alone.
159 */
160export function isRateLimited(input: {
161 readonly status: number;
162 readonly headers: Readonly<Record<string, string | undefined>>;
163 readonly graphqlErrors?: ReadonlyArray<{ readonly type?: unknown; readonly message?: unknown }>;
164 readonly body?: string;
165}): boolean {
166 const { status, headers, graphqlErrors: errors } = input;
167 return (
168 status === 429 ||
169 (errors !== undefined &&
170 (headers["x-ratelimit-remaining"] === "0" ||
171 errors.some(
172 (error) =>
173 error.type === "RATE_LIMITED" ||
174 (typeof error.message === "string" &&
175 /rate limit (already )?exceeded/i.test(error.message)),
176 ))) ||
177 (status === 403 &&
178 (headers["x-ratelimit-remaining"] === "0" ||
179 namesLimit(input.body) ||
180 (errors ?? []).some((error) => namesLimit(error.message))))
181 );
182}
183
184function namesLimit(text: unknown): boolean {
185 return typeof text === "string" && /rate limit|abuse detection mechanism/i.test(text);
186}
187
188export type GitHubAnswer<A> = {
189 readonly status: number | undefined;
190 readonly headers: Readonly<Record<string, string | undefined>>;
191} & (
192 | {
193 readonly _tag: "Ok";
194 readonly value: A;
195 /** GitHub left part of the answer out as not found or forbidden for this credential. */
196 readonly withheld?: boolean;
197 }
198 | { readonly _tag: "RateLimited" | "Unauthorized" | "NotFound" }
199 | { readonly _tag: "Failed"; readonly messages?: ReadonlyArray<string> | undefined }
200);
201
202export interface GitHubRequest {
203 readonly host: string;
204 readonly operation: string;
205 /** The quota the request spends: `core` for REST, `graphql` for GraphQL. */
206 readonly resource: string;
207 readonly allowReserve: boolean;
208 /** Covers sending and reading the answer. Defaults to 30 seconds. */
209 readonly timeout?: Duration.Input | undefined;
210}
211
212/** REST/GraphQL share credentials, slots, quota reserves and host-wide pauses. */
213export class GitHubRequestPolicy extends Context.Service<
214 GitHubRequestPolicy,
215 {
216 /**
217 * send receives auth/version headers and the source of the credential they carry; its
218 * failures pass through unchanged.
219 */
220 readonly request: <A, E, R>(
221 input: GitHubRequest,
222 send: (
223 headers: Readonly<Record<string, string>>,
224 source: GitHubCredentials.GitHubCredentialSource | undefined,
225 ) => Effect.Effect<GitHubAnswer<A>, E, R>,
226 ) => Effect.Effect<A, E | GitHubApiError, R>;
227 /**
228 * The credential requests to `host` use: a token saved in Settings, else the app sign-in,
229 * else `GH_TOKEN` or `gh`. `personal` skips the app, for repositories it cannot reach.
230 */
231 readonly credential: (
232 host: string,
233 options?: { readonly personal?: boolean },
234 ) => Effect.Effect<GitHubHeldCredential, GitHubApiError>;
235 /** The app sign-in's own credential, whatever else outranks it; none when not signed in. */
236 readonly appCredential: (
237 host: string,
238 ) => Effect.Effect<Option.Option<GitHubHeldCredential>, GitHubAppSignIn.GitHubAppSessionError>;
239 }
240>()("@t3tools/source-control-github/server/GitHubRequestPolicy") {}
241
242export interface GitHubHeldCredential {
243 readonly source?: GitHubCredentials.GitHubCredentialSource;
244 readonly token: Redacted.Redacted<string>;
245 readonly fingerprint: string;
246}
247
248interface ChosenCredential extends GitHubHeldCredential {
249 readonly fromApp: boolean;
250}
251
252/**
253 * The app reaches only repositories where it is installed. A not-found or "not accessible by
254 * integration" answer to its token is worth one more try with the user's own credential.
255 */
256function refusedToApp<A>(answer: GitHubAnswer<A>): boolean {
257 switch (answer._tag) {
258 case "NotFound":
259 return true;
260 case "Ok":
261 return answer.withheld === true;
262 case "Failed":
263 return (
264 answer.status === 403 &&
265 (answer.messages ?? []).some((message) => /not accessible by integration/i.test(message))
266 );
267 default:
268 return false;
269 }
270}
271
272/** @public */
273export const make = Effect.gen(function* () {
274 const credentials = yield* GitHubCredentials.GitHubCredentials;
275 const appSignIn = yield* GitHubAppSignIn.GitHubAppSignIn;
276 const quota = yield* GitHubQuota.GitHubQuota;
277 const limits = yield* SourceControlRateLimit.SourceControlRateLimit;
278 const slots = yield* Semaphore.make(CONCURRENCY);
279
280 const personalCredential = (host: string) =>
281 credentials.get(host).pipe(
282 Effect.map((held): ChosenCredential => ({
283 token: held.token,
284 fingerprint: held.fingerprint,
285 source: held.source,
286 fromApp: false,
287 })),
288 );
289
290 const appCredential: GitHubRequestPolicy["Service"]["appCredential"] = Effect.fn(
291 "GitHubRest.appCredential",
292 )(function* (host) {
293 const token = yield* appSignIn.token(normalizeHost(host));
294 if (Option.isNone(token)) return Option.none();
295 return Option.some({
296 source: "app" as const,
297 token: Redacted.make(token.value),
298 fingerprint: yield* credentials.fingerprint(normalizeHost(host), token.value),
299 });
300 });
301
302 const choose = Effect.fn("GitHubRest.credential")(function* (host: string, personal: boolean) {
303 const pinned = yield* PinnedGitHubCredential;
304 if (pinned !== null) {
305 if (pinned.host !== host) {
306 return yield* new GitHubApiAuthenticationError({ host, operation: "credential" });
307 }
308 return {
309 token: pinned.token,
310 fingerprint: pinned.credentialFingerprint,
311 ...(pinned.source === undefined ? {} : { source: pinned.source }),
312 fromApp: false,
313 } satisfies ChosenCredential;
314 }
315 const saved = yield* credentials.saved(host);
316 if (Option.isSome(saved)) {
317 return {
318 token: saved.value.token,
319 fingerprint: saved.value.fingerprint,
320 source: saved.value.source,
321 fromApp: false,
322 };
323 }
324 if (personal) return yield* personalCredential(host);
325 const app = yield* Effect.result(appCredential(host));
326 // An app session that cannot refresh right now steps aside for the user's own credential.
327 if (Result.isFailure(app)) {
328 return yield* personalCredential(host).pipe(Effect.mapError(() => app.failure));
329 }
330 if (Option.isNone(app.success)) return yield* personalCredential(host);
331 return { ...app.success.value, fromApp: true } satisfies ChosenCredential;
332 });
333
334 const credential: GitHubRequestPolicy["Service"]["credential"] = (host, options) =>
335 choose(normalizeHost(host), options?.personal === true).pipe(
336 Effect.map(({ token, fingerprint, source }) => ({
337 token,
338 fingerprint,
339 ...(source === undefined ? {} : { source }),
340 })),
341 );
342
343 // The REST/GraphQL transport span owns request and quota metadata.
344 const request: GitHubRequestPolicy["Service"]["request"] = Effect.fnUntraced(function* <A, E, R>(
345 input: GitHubRequest,
346 send: (
347 headers: Readonly<Record<string, string>>,
348 source: GitHubCredentials.GitHubCredentialSource | undefined,
349 ) => Effect.Effect<GitHubAnswer<A>, E, R>,
350 ) {
351 const host = normalizeHost(input.host);
352 const context = { host, operation: input.operation };
353 yield* Effect.annotateCurrentSpan({
354 "github.host": host,
355 "github.operation": input.operation,
356 });
357 const scope = yield* SourceControlRateLimit.CredentialScope;
358 // A refusal pauses the whole host, whichever quota it spent: the key PullRequestService
359 // records its own backoff under.
360 const key = { provider: SourceControlProviderKind.make("github"), host };
361
362 // Settlement annotates the request span with status and rate-limit attributes.
363 const settle = Effect.fnUntraced(function* (
364 lease: number,
365 answer: GitHubAnswer<A>,
366 held: ChosenCredential,
367 ) {
368 yield* quota.observe(host, answer.headers);
369 yield* Effect.annotateCurrentSpan({
370 ...(answer.status === undefined ? {} : { "http.response.status_code": answer.status }),
371 ...rateLimitAttributes(answer.headers),
372 });
373 switch (answer._tag) {
374 case "Ok":
375 yield* limits.recordSuccess({ ...key, lease });
376 return answer.value;
377 case "RateLimited": {
378 const retryAt = retryAtFrom(answer.headers, yield* Clock.currentTimeMillis);
379 yield* limits.recordRateLimit({ ...key, lease, retryAt });
380 yield* Effect.annotateCurrentSpan({
381 "github.rate_limited": true,
382 ...(retryAt === undefined ? {} : { "github.retry_at": retryAt }),
383 });
384 return yield* new GitHubApiRateLimitError({
385 ...context,
386 ...(retryAt === undefined ? {} : { retryAt }),
387 });
388 }
389 case "Unauthorized":
390 // The source may hold a newer token than the one that was refused.
391 yield* appSignIn.invalidate(host, Redacted.value(held.token));
392 yield* credentials.invalidate(host);
393 return yield* new GitHubApiAuthenticationError(context);
394 case "NotFound":
395 return yield* new GitHubApiNotFoundError({
396 ...context,
397 ...(held.source === undefined ? {} : { credential: held.source }),
398 });
399 case "Failed":
400 return yield* new GitHubApiResponseError({
401 ...context,
402 status: answer.status ?? 200,
403 ...(answer.messages === undefined ? {} : { githubErrors: answer.messages }),
404 });
405 }
406 });
407
408 /** One send under `held`; `Retry` hands an app-refused request to the user's credential. */
409 const attempt = (held: ChosenCredential) =>
410 slots
411 .withPermit(
412 Effect.gen(function* () {
413 const lease = yield* quota
414 .admit(host, input.resource, { allowReserve: input.allowReserve })
415 .pipe(
416 Effect.andThen(
417 limits.check(key, input.allowReserve ? { allowPaused: true } : undefined),
418 ),
419 Effect.tapError((paused) =>
420 Effect.annotateCurrentSpan({
421 "github.paused": true,
422 "github.retry_at": paused.retryAt,
423 }),
424 ),
425 );
426 // One deadline covers the headers and the body: a host that answers headers and then
427 // stalls must not hold a shared slot for undici's own five-minute body timeout.
428 const answer = yield* send(
429 { ...REQUEST_HEADERS, authorization: `Bearer ${Redacted.value(held.token)}` },
430 held.source,
431 ).pipe(
432 Effect.timeoutOrElse({
433 duration: input.timeout ?? DEFAULT_TIMEOUT,
434 orElse: () =>
435 Effect.fail(
436 new GitHubApiRequestError({ ...context, cause: new Cause.TimeoutError() }),
437 ),
438 }),
439 );
440 if (held.fromApp && refusedToApp(answer)) {
441 const personal = yield* Effect.option(personalCredential(host));
442 if (Option.isSome(personal)) {
443 yield* quota.observe(host, answer.headers);
444 yield* limits.recordSuccess({ ...key, lease });
445 yield* Effect.annotateCurrentSpan({ "github.app_refused": true });
446 return { _tag: "Retry", with: personal.value } as const;
447 }
448 }
449 return { _tag: "Done", value: yield* settle(lease, answer, held) } as const;
450 }),
451 )
452 // The rate-limit scope follows the credential, so a pause on one account never blocks another.
453 .pipe(
454 Effect.provideService(SourceControlRateLimit.CredentialScope, scope || held.fingerprint),
455 );
456
457 // Only an app credential is handed on, so this runs at most twice.
458 let held = yield* choose(host, false);
459 while (true) {
460 const outcome = yield* attempt(held);
461 if (outcome._tag === "Done") return outcome.value;
462 held = outcome.with;
463 }
464 });
465
466 return GitHubRequestPolicy.of({ request, credential, appCredential });
467});
468
469export const layer = Layer.effect(GitHubRequestPolicy, make);