import { Context, Effect, Layer, Option, Result } from "effect"; import * as Base64 from "effect/encoding/Base64"; import { GitHubClient } from "./GitHubClient.js"; import { GitHubError } from "./GitHubError.js"; import { unstubbed } from "./internal/unstubbed.js"; import { Repo } from "./Repo.js"; /** * Non-fatal, matching `Buffer`'s lenient decode of a non-UTF-8 file; `ignoreBOM` * keeps a leading BOM, since it is the file's content rather than framing. */ const utf8 = new TextDecoder("utf-8", { ignoreBOM: true }); /** * Read a text file out of a repository at a ref. * * @public */ export interface GitHubContentShape { /** * A text file's contents at `ref`, or the default branch when `ref` is * omitted. * * @remarks * Fails `notFound` when the path does not exist, and `rejected` when it is a * directory, is not a regular file, or is too large for the contents API * (which answers an empty body above roughly a megabyte). * * Fails `decode` when the payload is not valid base64. Only **standard, * padded** base64 is accepted, which is what the contents API sends; the * line breaks it wraps the payload with are ignored. Unpadded or URL-safe * (`-`/`_`) input is rejected rather than guessed at. The bytes decode as * UTF-8, keeping a leading BOM as content. */ readonly getFile: ( path: string, options?: { readonly ref?: string | undefined }, ) => Effect.Effect; /** As {@link GitHubContentShape.getFile}, with absence as `Option.none`. */ readonly getFileOption: ( path: string, options?: { readonly ref?: string | undefined }, ) => Effect.Effect, GitHubError, Repo>; } /** * Read a text file out of a repository at a ref, with absence as an `Option` * when you want it. * * @remarks * Provide it with {@link GitHubContent.layer}, which needs a `GitHubClient`; * each method also needs a `Repo` in `R`. * * @example * ```ts * import { GitHubContent } from "@effected/github"; * import { Effect, Option } from "effect"; * * const readme = Effect.gen(function* () { * const content = yield* GitHubContent; * const file = yield* content.getFileOption("README.md", { ref: "main" }); * return Option.getOrElse(file, () => ""); * }); * ``` * * @public */ export class GitHubContent extends Context.Service()( "@effected/github/GitHubContent", ) { /** The live service, built over a `GitHubClient`. */ static readonly layer: Layer.Layer = Layer.effect( this, Effect.map(GitHubClient, (client) => make(client)), ); /** An in-memory double; an unstubbed member dies when run, naming itself. */ static readonly makeTest = (overrides: Partial = {}): GitHubContentShape => ({ getFile: overrides.getFile ?? (() => dies("getFile")), getFileOption: overrides.getFileOption ?? (() => dies("getFileOption")), }); /** {@link GitHubContent.makeTest} behind a `Layer`. */ static readonly layerTest = (overrides: Partial = {}): Layer.Layer => Layer.succeed(GitHubContent, GitHubContent.makeTest(overrides)); } const dies = unstubbed("GitHubContent.makeTest"); const make = (client: GitHubClient["Service"]): GitHubContentShape => { const getFile = Effect.fn("GitHubContent.getFile")(function* ( path: string, options?: { readonly ref?: string | undefined }, ) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo, path, ref: options?.ref ?? "" }); const content = yield* client.request("GET /repos/{owner}/{repo}/contents/{path}", { owner, repo, path, ...(options?.ref !== undefined ? { ref: options.ref } : {}), }); // A directory comes back as an array. Reading one as a file would be a // silent type confusion. if (Array.isArray(content)) { return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} is a directory`)); } if (content.type !== "file") { return yield* Effect.fail( GitHubError.rejected("GitHubContent.getFile", 422, `${path} is a ${content.type}, not a file`), ); } // Over about a megabyte GitHub answers with `encoding: "none"` and an empty // body. Decoding that as base64 yields an empty string that looks exactly // like a legitimately empty file, so it is refused instead. if (content.encoding !== "base64") { return yield* Effect.fail( GitHubError.rejected( "GitHubContent.getFile", 422, `${path} came back with encoding ${JSON.stringify(content.encoding)} — it is probably too large for the contents API`, ), ); } // GitHub wraps the payload at 60 columns. Decoded through core Base64 and // TextDecoder rather than Buffer, a Node global a Worker may not have. const bytes = Base64.decode(content.content.replace(/\s/g, "")); if (Result.isFailure(bytes)) { return yield* Effect.fail( GitHubError.decode("GitHubContent.getFile", `${path} did not come back as valid base64`, bytes.failure), ); } return utf8.decode(bytes.success); }); return { getFile, getFileOption: Effect.fn("GitHubContent.getFileOption")(function* ( path: string, options?: { readonly ref?: string | undefined }, ) { return yield* getFile(path, options).pipe( Effect.map(Option.some), Effect.catchIf(GitHubError.hasKind("notFound"), () => Effect.succeed(Option.none())), ); }), }; };