The best way to control Claude Code, Codex and more from any computer or phone
| 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 | ); |