Open History to see the last commit
1import { normalizeHost } from "@t3tools/source-control-core/server/pullRequestUtils";
2import * as Context from "effect/Context";
3import * as Effect from "effect/Effect";
4import { dual } from "effect/Function";
5import * as Layer from "effect/Layer";
6import * as Option from "effect/Option";
7import * as Schema from "effect/Schema";
8import * as Stream from "effect/Stream";
9import { HttpClient, HttpClientError, HttpClientResponse } from "effect/http";
10import * as Headers from "effect/http/Headers";
11import { GraphQLClientError, GraphQLMiddleware, GraphQLProtocol } from "effect/graphql";
12import * as SourceControlRateLimit from "@t3tools/source-control-core/server/SourceControlRateLimit";
13import { collectUint8StreamText } from "@t3tools/provider-core/server/collectStreamText";
14
15import * as GitHubCredentials from "./GitHubCredentials.ts";
16import * as GitHubRequestPolicy from "./GitHubRequestPolicy.ts";
17
18const DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
19/** Added to the answer, never sent: names the credential an errored answer was given to. */
20const CREDENTIAL_SOURCE_HEADER = "x-t3code-credential-source";
21const isCredentialSource = Schema.is(GitHubCredentials.GitHubCredentialSource);
22
23/** One client serves all hosts; each call must supply its target. */
24export class GitHubGraphQlTarget extends Context.Service<
25 GitHubGraphQlTarget,
26 {
27 readonly host: string;
28 readonly operation: string;
29 /** Overrides `SourceControlRateLimit.Interactive` for this one call. */
30 readonly allowReserve?: boolean | undefined;
31 /** A longer answer fails as a `GitHubApiResponseError`. Defaults to 8 MB. */
32 readonly maxResponseBytes?: number | undefined;
33 }
34>()("@t3tools/source-control-github/server/gitHubGraphQlClient/GitHubGraphQlTarget") {}
35
36// Group traces by query without exposing query text.
37function queryHash(query: string): string {
38 let hash = 0x811c9dc5;
39 for (let index = 0; index < query.length; index++) {
40 hash ^= query.charCodeAt(index);
41 hash = Math.imul(hash, 0x01000193);
42 }
43 return (hash >>> 0).toString(16).padStart(8, "0");
44}
45
46/**
47 * Whether every error is a NOT_FOUND on a lookup: a root field (with its list items),
48 * `repository.pullRequest` or `repository.issueOrPullRequest`. A NOT_FOUND deeper down is one
49 * field GitHub could not resolve.
50 */
51export const isNotFoundOnly = (error: unknown): boolean =>
52 GraphQLClientError.isGraphQLClientError(error) &&
53 error.reason._tag === "ResponseError" &&
54 error.reason.errors.every(
55 ({ type, path }) =>
56 type === "NOT_FOUND" &&
57 (path === undefined ||
58 path.slice(1).every((segment) => typeof segment === "number") ||
59 (path.length === 2 &&
60 path[0] === "repository" &&
61 (path[1] === "pullRequest" || path[1] === "issueOrPullRequest"))),
62 );
63
64/** GitHub's message for each error in an answer, with the field it names. */
65export const describeErrors = (error: GraphQLClientError.GraphQLClientError) =>
66 error.reason._tag === "ResponseError"
67 ? error.reason.errors.map(({ message, path }) =>
68 path === undefined || path.length === 0 ? message : `${message} (at ${path.join(".")})`,
69 )
70 : [];
71
72/** Share REST's credentials/slots/quota/pause; leave non-rate-limit errors to each lookup. */
73export class GitHubGraphQlAuth extends GraphQLMiddleware.Service<
74 GitHubGraphQlAuth,
75 { requires: GitHubGraphQlTarget; error: GitHubRequestPolicy.GitHubApiError }
76>()("@t3tools/source-control-github/server/gitHubGraphQlClient/GitHubGraphQlAuth") {
77 static readonly layer = Layer.effect(
78 GitHubGraphQlAuth,
79 Effect.gen(function* () {
80 const policy = yield* GitHubRequestPolicy.GitHubRequestPolicy;
81 return GitHubGraphQlAuth.of({
82 execute: Effect.fn("GitHubGraphQlAuth.execute")(function* ({ request, next }) {
83 const target = yield* GitHubGraphQlTarget;
84 const host = normalizeHost(target.host);
85 yield* Effect.annotateCurrentSpan({
86 "github.kind": "graphql",
87 "github.graphql.query_hash": queryHash(request.query),
88 });
89 return yield* policy.request(
90 {
91 host,
92 operation: target.operation,
93 resource: "graphql",
94 allowReserve: target.allowReserve ?? (yield* SourceControlRateLimit.Interactive),
95 },
96 (headers, source) =>
97 next({ ...request, headers: Headers.setAll(request.headers, headers) }).pipe(
98 Effect.map((answer) => {
99 const status = answer.status;
100 const responseHeaders = answer.headers ?? Headers.empty;
101 const rateLimited = GitHubRequestPolicy.isRateLimited({
102 status: status ?? 200,
103 headers: responseHeaders,
104 ...(answer.errors === undefined ? {} : { graphqlErrors: answer.errors }),
105 });
106 const withheld = (answer.errors ?? []).some(
107 (error) => error["type"] === "NOT_FOUND" || error["type"] === "FORBIDDEN",
108 );
109 return rateLimited
110 ? { _tag: "RateLimited" as const, status, headers: responseHeaders }
111 : {
112 _tag: "Ok" as const,
113 // The source is local; never trust one GitHub's answer carries.
114 value: {
115 ...answer,
116 headers:
117 source === undefined
118 ? Headers.remove(responseHeaders, CREDENTIAL_SOURCE_HEADER)
119 : Headers.set(responseHeaders, CREDENTIAL_SOURCE_HEADER, source),
120 },
121 withheld,
122 status,
123 headers: responseHeaders,
124 };
125 }),
126 Effect.catchIf(GraphQLClientError.isGraphQLClientError, (error) =>
127 refused(error, { host, operation: target.operation }),
128 ),
129 ),
130 );
131 }),
132 subscribe: () => Stream.die(new Error("GitHub GraphQL has no subscriptions.")),
133 });
134 }),
135 );
136}
137
138/**
139 * What a refusal GitHub sent as an HTTP status means, read the way REST reads one. A
140 * failure that never reached GitHub is a request error; one that is not about the transport
141 * (an answer that does not decode) is the client's own.
142 */
143const refused = Effect.fn("gitHubGraphQlClient.refused")(function* (
144 error: GraphQLClientError.GraphQLClientError,
145 context: { readonly host: string; readonly operation: string },
146) {
147 const reason = error.reason;
148 if (reason._tag !== "TransportError" && reason._tag !== "ResponseError") {
149 return yield* error;
150 }
151 const status = reason.status;
152 if (reason._tag === "TransportError" && status === undefined) {
153 return yield* new GitHubRequestPolicy.GitHubApiRequestError({ ...context, cause: error });
154 }
155 const headers = reason.headers ?? Headers.empty;
156 // A secondary limit is a 403 that only its body names, which the transport read.
157 const body =
158 reason._tag === "TransportError" &&
159 HttpClientError.isHttpClientError(reason.cause) &&
160 reason.cause.response !== undefined
161 ? yield* reason.cause.response.text.pipe(Effect.orElseSucceed(() => ""))
162 : "";
163 const tag = GitHubRequestPolicy.isRateLimited({
164 status: status ?? 200,
165 headers,
166 body,
167 ...(reason._tag === "ResponseError" ? { graphqlErrors: reason.errors } : {}),
168 })
169 ? "RateLimited"
170 : status === 401
171 ? "Unauthorized"
172 : status === 404
173 ? "NotFound"
174 : "Failed";
175 return { _tag: tag, status: status ?? 200, headers } as const;
176});
177
178/**
179 * Reads each answer whole, up to the call's byte cap, before the protocol parses it. A body cut
180 * at the cap hides any `errors` past the cut and cannot be decoded, so it fails, which the
181 * middleware reports as a `GitHubApiResponseError` with the answer's status.
182 */
183const capResponse = Effect.fn("gitHubGraphQlClient.capResponse")(function* (
184 effect: Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>,
185) {
186 const response = yield* effect;
187 const target = yield* Effect.serviceOption(GitHubGraphQlTarget);
188 const maxBytes = Option.match(target, {
189 onNone: () => DEFAULT_MAX_RESPONSE_BYTES,
190 onSome: (target) => target.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
191 });
192 const collected = yield* collectUint8StreamText({ stream: response.stream, maxBytes }).pipe(
193 Effect.catchIf(
194 (error) => error.reason._tag === "EmptyBodyError",
195 () => Effect.succeed({ text: "", truncated: false }),
196 ),
197 );
198 if (collected.truncated) {
199 return yield* new HttpClientError.HttpClientError({
200 reason: new HttpClientError.DecodeError({
201 request: response.request,
202 response,
203 description: `The answer is longer than ${maxBytes} bytes.`,
204 }),
205 });
206 }
207 return HttpClientResponse.fromWeb(
208 response.request,
209 new Response(collected.text === "" ? null : collected.text, {
210 status: response.status,
211 headers: response.headers,
212 }),
213 );
214});
215
216// Endpoint URLs isolate hosts. Disable client tracing to protect SHAs and branches in url.full.
217const layerProtocol = GraphQLProtocol.layerHttp({
218 url: ({ context }) =>
219 GitHubRequestPolicy.gitHubApiUrls(Context.getUnsafe(context, GitHubGraphQlTarget).host).graphql,
220}).pipe(
221 Layer.provide(
222 Layer.effect(
223 HttpClient.HttpClient,
224 Effect.gen(function* () {
225 const client = yield* HttpClient.HttpClient;
226 return HttpClient.transformResponse(client, (effect) =>
227 capResponse(effect).pipe(
228 Effect.provideService(HttpClient.TracerDisabledWhen, () => true),
229 ),
230 );
231 }),
232 ),
233 ),
234);
235
236export const layer = Layer.merge(GitHubGraphQlAuth.layer, layerProtocol);
237
238/** Isolate credentials/rate-limit scopes; transport URLs already separate hosts. */
239export const batchKey = (context: Context.Context<GitHubGraphQlTarget>) =>
240 JSON.stringify([
241 Context.getOrElse(context, GitHubRequestPolicy.PinnedGitHubCredential, () => null)
242 ?.credentialFingerprint ?? null,
243 Context.getOrElse(context, SourceControlRateLimit.CredentialScope, () => ""),
244 ]);
245
246const fromClientError = (
247 target: { readonly host: string; readonly operation: string },
248 error: GraphQLClientError.GraphQLClientError,
249):
250 | GitHubRequestPolicy.GitHubApiNotFoundError
251 | GitHubRequestPolicy.GitHubApiResponseError
252 | GraphQLClientError.GraphQLClientError => {
253 const reason = error.reason;
254 if (reason._tag !== "ResponseError") return error;
255 const context = {
256 host: normalizeHost(target.host),
257 operation: target.operation,
258 githubErrors: describeErrors(error),
259 };
260 const credential = Option.filter(
261 Headers.get(reason.headers ?? Headers.empty, CREDENTIAL_SOURCE_HEADER),
262 isCredentialSource,
263 );
264 return isNotFoundOnly(error)
265 ? new GitHubRequestPolicy.GitHubApiNotFoundError({
266 ...context,
267 ...(Option.isSome(credential) ? { credential: credential.value } : {}),
268 })
269 : new GitHubRequestPolicy.GitHubApiResponseError({
270 ...context,
271 status: reason.status ?? 200,
272 githubErrorTypes: reason.errors.map((graphQlError) =>
273 typeof graphQlError["type"] === "string" ? graphQlError["type"] : null,
274 ),
275 });
276};
277
278/** Map response errors to policy errors; callers map decode errors to read errors. */
279export const call: {
280 (
281 target: GitHubGraphQlTarget["Service"],
282 ): <A, E, R>(
283 effect: Effect.Effect<A, E, R>,
284 ) => Effect.Effect<
285 A,
286 E | GitHubRequestPolicy.GitHubApiNotFoundError | GitHubRequestPolicy.GitHubApiResponseError,
287 Exclude<R, GitHubGraphQlTarget>
288 >;
289 <A, E, R>(
290 effect: Effect.Effect<A, E, R>,
291 target: GitHubGraphQlTarget["Service"],
292 ): Effect.Effect<
293 A,
294 E | GitHubRequestPolicy.GitHubApiNotFoundError | GitHubRequestPolicy.GitHubApiResponseError,
295 Exclude<R, GitHubGraphQlTarget>
296 >;
297} = dual(2, <A, E, R>(effect: Effect.Effect<A, E, R>, target: GitHubGraphQlTarget["Service"]) =>
298 effect.pipe(
299 Effect.mapError((error) =>
300 GraphQLClientError.isGraphQLClientError(error)
301 ? (fromClientError(target, error) as
302 | E
303 | GitHubRequestPolicy.GitHubApiNotFoundError
304 | GitHubRequestPolicy.GitHubApiResponseError)
305 : error,
306 ),
307 Effect.provideService(GitHubGraphQlTarget, target),
308 ),
309);