Open History to see the last commit
1import { normalizeHost } from "@t3tools/source-control-core/server/pullRequestUtils";
2import * as Context from "effect/Context";
3import * as Duration from "effect/Duration";
4import * as Effect from "effect/Effect";
5import * as Layer from "effect/Layer";
6import * as Option from "effect/Option";
7import * as Schema from "effect/Schema";
8import { HttpClient, HttpClientRequest, type HttpClientResponse } from "effect/http";
9
10import { collectUint8StreamText } from "@t3tools/provider-core/server/collectStreamText";
11import * as GitHubAppSignIn from "./GitHubAppSignIn.ts";
12import * as GitHubCredentials from "./GitHubCredentials.ts";
13import * as GitHubQuota from "./GitHubQuota.ts";
14import * as GitHubRequestPolicy from "./GitHubRequestPolicy.ts";
15import * as SourceControlRateLimit from "@t3tools/source-control-core/server/SourceControlRateLimit";
16
17const DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
18const { gitHubApiUrls } = GitHubRequestPolicy;
19type GitHubApiError = GitHubRequestPolicy.GitHubApiError;
20
21export interface GitHubRestResponse {
22 readonly status: number;
23 readonly headers: Readonly<Record<string, string | undefined>>;
24 readonly body: string;
25 readonly truncated: boolean;
26 /** Invalid UTF-8 indicates a binary raw file. */
27 readonly invalidUtf8: boolean;
28}
29
30export interface GitHubRestInput {
31 readonly host: string;
32 readonly operation: string;
33 readonly method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
34 /** Relative to the API root, including query string. */
35 readonly path: string;
36 readonly body?: unknown;
37 /** Defaults to `application/vnd.github+json`. */
38 readonly accept?: string;
39 /** Revalidate cached answers; 304 returns successfully without spending quota. */
40 readonly ifNoneMatch?: string;
41 readonly maxResponseBytes?: number;
42 /** Defaults to 30 seconds; a whole pull request's patch may need longer. */
43 readonly timeout?: Duration.Input;
44 /** Overrides `SourceControlRateLimit.Interactive` for this one request. */
45 readonly allowReserve?: boolean;
46}
47
48export class GitHubRest extends Context.Service<
49 GitHubRest,
50 {
51 readonly rest: (input: GitHubRestInput) => Effect.Effect<GitHubRestResponse, GitHubApiError>;
52 readonly credential: GitHubRequestPolicy.GitHubRequestPolicy["Service"]["credential"];
53 readonly appCredential: GitHubRequestPolicy.GitHubRequestPolicy["Service"]["appCredential"];
54 }
55>()("@t3tools/source-control-github/server/GitHubRest") {}
56
57const decodeRestErrors = Schema.decodeUnknownOption(
58 Schema.fromJsonString(
59 Schema.Struct({
60 message: Schema.optional(Schema.String),
61 errors: Schema.optional(
62 Schema.Array(
63 Schema.Union([
64 Schema.String,
65 Schema.Struct({
66 message: Schema.optional(Schema.String),
67 field: Schema.optional(Schema.String),
68 code: Schema.optional(Schema.String),
69 }),
70 ]),
71 ),
72 ),
73 }),
74 ),
75);
76
77function restErrorMessages(body: string): ReadonlyArray<string> | undefined {
78 return Option.match(decodeRestErrors(body), {
79 onNone: () => undefined,
80 onSome: (decoded) => {
81 const details = (decoded.errors ?? []).flatMap((error) =>
82 typeof error === "string"
83 ? [error]
84 : error.message !== undefined
85 ? [error.message]
86 : error.field !== undefined && error.code !== undefined
87 ? [`${error.field} ${error.code}`]
88 : [],
89 );
90 const messages = [...(decoded.message === undefined ? [] : [decoded.message]), ...details];
91 return messages.length > 0 ? messages : undefined;
92 },
93 });
94}
95
96/** Accept 304 only for cache revalidation. */
97function classify(input: {
98 readonly answer: GitHubRestResponse;
99 readonly acceptNotModified: boolean;
100}): GitHubRequestPolicy.GitHubAnswer<GitHubRestResponse> {
101 const { status, headers, body } = input.answer;
102 const meta = { status, headers };
103 if (GitHubRequestPolicy.isRateLimited({ status, headers, body })) {
104 return { _tag: "RateLimited", ...meta };
105 }
106 if (status === 401) return { _tag: "Unauthorized", ...meta };
107 if (status === 404) return { _tag: "NotFound", ...meta };
108 if ((status >= 200 && status < 300) || (status === 304 && input.acceptNotModified)) {
109 return { _tag: "Ok", value: input.answer, ...meta };
110 }
111 return { _tag: "Failed", messages: restErrorMessages(body), ...meta };
112}
113
114/** @public */
115export const make = Effect.gen(function* () {
116 const httpClient = yield* HttpClient.HttpClient;
117 const policy = yield* GitHubRequestPolicy.GitHubRequestPolicy;
118
119 const send = Effect.fn("GitHubRest.send")(function* (input: {
120 readonly host: string;
121 readonly operation: string;
122 readonly request: HttpClientRequest.HttpClientRequest;
123 readonly maxResponseBytes: number;
124 readonly timeout?: Duration.Input | undefined;
125 readonly allowReserve: boolean;
126 readonly acceptNotModified: boolean;
127 }) {
128 const host = normalizeHost(input.host);
129 // Query strings can expose SHAs or branches in traces.
130 yield* Effect.annotateCurrentSpan({
131 "github.kind": "rest",
132 "http.request.method": input.request.method,
133 "url.path": new URL(input.request.url).pathname,
134 });
135 return yield* policy.request(
136 {
137 host,
138 operation: input.operation,
139 // All current paths spend `core`; search would need a different resource.
140 resource: "core",
141 allowReserve: input.allowReserve,
142 timeout: input.timeout,
143 },
144 (headers) =>
145 Effect.gen(function* () {
146 const response: HttpClientResponse.HttpClientResponse = yield* httpClient
147 .execute(input.request.pipe(HttpClientRequest.setHeaders(headers)))
148 .pipe(
149 // Client spans expose SHAs and branches through url.full/url.query.
150 Effect.provideService(HttpClient.TracerDisabledWhen, () => true),
151 );
152 const collected = yield* collectUint8StreamText({
153 stream: response.stream,
154 maxBytes: input.maxResponseBytes,
155 }).pipe(
156 Effect.catchIf(
157 (error) => error.reason._tag === "EmptyBodyError",
158 () => Effect.succeed({ text: "", truncated: false, invalidUtf8: false }),
159 ),
160 );
161 const { status, headers: responseHeaders } = response;
162 const answer = {
163 status,
164 headers: responseHeaders,
165 body: collected.text,
166 truncated: collected.truncated,
167 invalidUtf8: collected.invalidUtf8,
168 };
169 return classify({ answer, acceptNotModified: input.acceptNotModified });
170 }).pipe(
171 Effect.mapError(
172 (cause) =>
173 new GitHubRequestPolicy.GitHubApiRequestError({
174 host,
175 operation: input.operation,
176 cause,
177 }),
178 ),
179 ),
180 );
181 });
182
183 const rest: GitHubRest["Service"]["rest"] = (input) => {
184 const url = `${gitHubApiUrls(input.host).rest}/${input.path.replace(/^\/+/, "")}`;
185 const base = HttpClientRequest.make(input.method ?? "GET")(url).pipe(
186 HttpClientRequest.setHeader("accept", input.accept ?? "application/vnd.github+json"),
187 );
188 const withEtag =
189 input.ifNoneMatch === undefined
190 ? base
191 : base.pipe(HttpClientRequest.setHeader("if-none-match", input.ifNoneMatch));
192 const request =
193 input.body === undefined
194 ? withEtag
195 : withEtag.pipe(HttpClientRequest.bodyJsonUnsafe(input.body));
196 return SourceControlRateLimit.Interactive.pipe(
197 Effect.flatMap((interactive) =>
198 send({
199 host: input.host,
200 operation: input.operation,
201 request,
202 maxResponseBytes: input.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
203 timeout: input.timeout,
204 allowReserve: input.allowReserve ?? interactive,
205 acceptNotModified: input.ifNoneMatch !== undefined,
206 }),
207 ),
208 );
209 };
210
211 return GitHubRest.of({
212 rest,
213 credential: policy.credential,
214 appCredential: policy.appCredential,
215 });
216});
217
218export const layer = Layer.effect(GitHubRest, make).pipe(
219 Layer.provideMerge(GitHubRequestPolicy.layer),
220);
221
222/**
223 * REST and the request policy, with the credential and quota reserve the policy reads through.
224 * Built once, so every GitHub reader shares one view of each quota per host. The rate-limit pause
225 * comes from the server, which every host's change request reads share.
226 */
227export const layerWithDependencies = layer.pipe(
228 Layer.provideMerge(GitHubCredentials.layer),
229 Layer.provideMerge(GitHubAppSignIn.layer),
230 Layer.provideMerge(GitHubQuota.layer),
231);