The best way to control Claude Code, Codex and more from any computer or phone

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