import { Context, Effect, Layer, Option, Schema } from "effect"; import { GitHubClient } from "./GitHubClient.js"; import { GitHubError } from "./GitHubError.js"; import { unstubbed } from "./internal/unstubbed.js"; import { originOf, uploadChannelOf, uploadsBaseUrlFor } from "./internal/uploads.js"; import { Repo } from "./Repo.js"; import type { PageOptions } from "./Rest.js"; /** * A release, projected to the fields callers read. * * @public */ export class ReleaseInfo extends Schema.Class("ReleaseInfo")({ id: Schema.Int, tag: Schema.String, name: Schema.String, body: Schema.String, draft: Schema.Boolean, prerelease: Schema.Boolean, /** The web URL. */ url: Schema.String, /** * The templated upload endpoint GitHub hands back for assets. * * @remarks * {@link GitHubReleaseShape.uploadAsset} never routes by this value: it is * response data. It only cross-checks that its origin is the upload host * derived from the client's configured base URL, and refuses the upload * when it is not. */ uploadUrl: Schema.String, }) {} /** * A file attached to a release. * * @public */ export class ReleaseAsset extends Schema.Class("ReleaseAsset")({ id: Schema.Int, name: Schema.String, /** The browser download URL. */ url: Schema.String, /** Size in bytes. */ size: Schema.Int, }) {} /** * Create, read, list and update releases, and upload and list their assets. * * @public */ export interface GitHubReleaseShape { /** Create a release for `tag`. Unset fields are left to GitHub's defaults. */ readonly create: (input: { readonly tag: string; readonly name?: string | undefined; readonly body?: string | undefined; readonly draft?: boolean | undefined; readonly prerelease?: boolean | undefined; readonly generateReleaseNotes?: boolean | undefined; }) => Effect.Effect; /** Read the release for `tag`. Fails `notFound` when there is none. */ readonly getByTag: (tag: string) => Effect.Effect; /** As {@link GitHubReleaseShape.getByTag}, with absence as `Option.none`. */ readonly getByTagOption: (tag: string) => Effect.Effect, GitHubError, Repo>; /** List releases, paginated. */ readonly list: (options?: { readonly page?: PageOptions | undefined; }) => Effect.Effect, GitHubError, Repo>; /** Patch a release by id; only the fields given are sent. */ readonly update: ( id: number, patch: { readonly name?: string | undefined; readonly body?: string | undefined; readonly draft?: boolean | undefined; readonly prerelease?: boolean | undefined; }, ) => Effect.Effect; /** * Attach a file to a release. * * @remarks * The one route in this package that is **not** in GitHub's generated * endpoint map: asset upload goes to a separate upload host with a raw * binary body, and the map omits it. So it is decoded against an owned * schema — the escape hatch is from the route table, never from typing. * * Being outside the map cuts the other way too: octokit has no schema * saying `name` is a **query** parameter, so the route template must carry * it (`assets{?name}`) or octokit silently drops it and GitHub answers 400 * `Invalid name for request` — a hand-written route owns its query * parameters in the template, always. `label` is the endpoint's optional * display label, shown in place of the file name on the release page. * * The upload host is derived from the base URL the client was **configured** * with, so the token only goes where the caller pointed it: github.com * (`https://api.github.com`, or no `baseUrl`) uploads to * `https://uploads.github.com`, GitHub Enterprise Server * (`https:///api/v3`) to `https:///api/uploads`, and any other * base to itself. The release's own `uploadUrl` is response data, so it is * never the route; its origin must equal the derived host's, or the call * fails `kind: "rejected"` with no status and nothing is sent. * * The client's public `requestDecoded` cannot reach the upload host: it * refuses every host but the configured API host. A client this package * built uploads through a private channel it carries off its public type, * which takes no host from anyone. A shape spread from a built client * (`{ ...client, requestDecoded }`) keeps that channel, so its upload does * **not** go through an overridden `requestDecoded`. * * A client shape this package did not build (`GitHubClient.makeTest`, * `layerFixture`, a hand-written double) has no channel: it is read as * github.com for the `uploadUrl` check, and the upload is handed to its own * `requestDecoded`, so a double records and answers it as usual. Before * these checks, a GitHub Enterprise Server client's upload sent its token to * `uploads.github.com`. */ readonly uploadAsset: ( release: ReleaseInfo, asset: { readonly name: string; readonly data: Uint8Array | string; readonly contentType: string; readonly label?: string | undefined; }, ) => Effect.Effect; /** List a release's assets, paginated. */ readonly listAssets: ( id: number, options?: { readonly page?: PageOptions | undefined }, ) => Effect.Effect, GitHubError, Repo>; } /** * Create, read, list and update GitHub releases, and upload and list their * assets. * * @remarks * Provide it with {@link GitHubRelease.layer}, which needs a `GitHubClient`; * each method also needs a `Repo` in `R`. * * @example * ```ts * import { GitHubRelease } from "@effected/github"; * import { Effect } from "effect"; * * const publish = Effect.gen(function* () { * const releases = yield* GitHubRelease; * const release = yield* releases.create({ tag: "v1.2.3", generateReleaseNotes: true }); * return release.url; * }); * ``` * * @public */ export class GitHubRelease extends Context.Service()( "@effected/github/GitHubRelease", ) { /** 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 = {}): GitHubReleaseShape => ({ create: overrides.create ?? (() => dies("create")), getByTag: overrides.getByTag ?? (() => dies("getByTag")), getByTagOption: overrides.getByTagOption ?? (() => dies("getByTagOption")), list: overrides.list ?? (() => dies("list")), update: overrides.update ?? (() => dies("update")), uploadAsset: overrides.uploadAsset ?? (() => dies("uploadAsset")), listAssets: overrides.listAssets ?? (() => dies("listAssets")), }); /** {@link GitHubRelease.makeTest} behind a `Layer`. */ static readonly layerTest = (overrides: Partial = {}): Layer.Layer => Layer.succeed(GitHubRelease, GitHubRelease.makeTest(overrides)); } const dies = unstubbed("GitHubRelease.makeTest"); interface RawRelease { readonly id: number; readonly tag_name: string; readonly name?: string | null | undefined; readonly body?: string | null | undefined; readonly draft: boolean; readonly prerelease: boolean; readonly html_url: string; readonly upload_url: string; } const project = (raw: RawRelease): ReleaseInfo => ReleaseInfo.make({ id: raw.id, tag: raw.tag_name, // GitHub sends null for an unset name or body; the empty string is what // every caller does with it anyway. name: raw.name ?? "", body: raw.body ?? "", draft: raw.draft, prerelease: raw.prerelease, url: raw.html_url, uploadUrl: raw.upload_url, }); const AssetResponse = Schema.Struct({ id: Schema.Int, name: Schema.String, browser_download_url: Schema.String, size: Schema.Int, }); const assetOf = (raw: { id: number; name: string; browser_download_url: string; size: number }): ReleaseAsset => ReleaseAsset.make({ id: raw.id, name: raw.name, url: raw.browser_download_url, size: raw.size }); const make = (client: GitHubClient["Service"]): GitHubReleaseShape => { const getByTag = Effect.fn("GitHubRelease.getByTag")(function* (tag: string) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo, tag }); const raw = yield* client.request("GET /repos/{owner}/{repo}/releases/tags/{tag}", { owner, repo, tag }); return project(raw); }); return { getByTag, create: Effect.fn("GitHubRelease.create")(function* (input: { readonly tag: string; readonly name?: string | undefined; readonly body?: string | undefined; readonly draft?: boolean | undefined; readonly prerelease?: boolean | undefined; readonly generateReleaseNotes?: boolean | undefined; }) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo, tag: input.tag }); const created = yield* client.request("POST /repos/{owner}/{repo}/releases", { owner, repo, tag_name: input.tag, ...(input.name !== undefined ? { name: input.name } : {}), ...(input.body !== undefined ? { body: input.body } : {}), ...(input.draft !== undefined ? { draft: input.draft } : {}), ...(input.prerelease !== undefined ? { prerelease: input.prerelease } : {}), ...(input.generateReleaseNotes !== undefined ? { generate_release_notes: input.generateReleaseNotes } : {}), }); return project(created); }), getByTagOption: Effect.fn("GitHubRelease.getByTagOption")(function* (tag: string) { return yield* getByTag(tag).pipe( Effect.map(Option.some), Effect.catchIf(GitHubError.hasKind("notFound"), () => Effect.succeed(Option.none())), ); }), list: Effect.fn("GitHubRelease.list")(function* (options?: { readonly page?: PageOptions | undefined }) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo }); const raw = yield* client.paginate("GET /repos/{owner}/{repo}/releases", { owner, repo }, options?.page); return raw.map(project); }), update: Effect.fn("GitHubRelease.update")(function* ( id: number, patch: { readonly name?: string | undefined; readonly body?: string | undefined; readonly draft?: boolean | undefined; readonly prerelease?: boolean | undefined; }, ) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo, id }); const updated = yield* client.request("PATCH /repos/{owner}/{repo}/releases/{release_id}", { owner, repo, release_id: id, ...(patch.name !== undefined ? { name: patch.name } : {}), ...(patch.body !== undefined ? { body: patch.body } : {}), ...(patch.draft !== undefined ? { draft: patch.draft } : {}), ...(patch.prerelease !== undefined ? { prerelease: patch.prerelease } : {}), }); return project(updated); }), uploadAsset: Effect.fn("GitHubRelease.uploadAsset")(function* ( release: ReleaseInfo, asset: { readonly name: string; readonly data: Uint8Array | string; readonly contentType: string; readonly label?: string | undefined; }, ) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo, release: release.id, asset: asset.name }); // The host comes from the client's CONFIGURED base, never from the // release: `uploadUrl` is response data, and the token rides with the // request. It only has to agree with the derived host. const channel = uploadChannelOf(client); const uploadsBaseUrl = uploadsBaseUrlFor(channel?.baseUrl); const expected = originOf(uploadsBaseUrl); const offered = originOf(release.uploadUrl); if (expected === undefined || offered !== expected) { return yield* Effect.fail( new GitHubError({ kind: "rejected", operation: "GitHubRelease.uploadAsset", reason: offered === undefined ? `release ${release.id} has no absolute upload URL; refusing to upload` : `release ${release.id}'s upload URL is on ${offered}, not this client's upload host ${expected ?? uploadsBaseUrl}; refusing to send the token there`, }), ); } // `name` MUST be in the template: this route is outside the generated // endpoint map, so no schema routes it to the query string — passed // only as a parameter it is silently dropped and GitHub answers 400 // "Invalid name for request". The two // template spellings exist because `{?name,label}` with an absent // label expands to a dangling `&` (probed at @octokit/endpoint 11.0.3). const route = asset.label === undefined ? "POST /repos/{owner}/{repo}/releases/{release_id}/assets{?name}" : "POST /repos/{owner}/{repo}/releases/{release_id}/assets{?name,label}"; const params = { owner, repo, release_id: release.id, name: asset.name, ...(asset.label === undefined ? {} : { label: asset.label }), data: asset.data, headers: { "content-type": asset.contentType }, }; // A client this package built uploads through its private channel to // the derived host; a double answers through its own requestDecoded. const raw = channel === undefined ? yield* client.requestDecoded(route, params, AssetResponse) : yield* channel.upload(route, params, AssetResponse); return assetOf(raw); }), listAssets: Effect.fn("GitHubRelease.listAssets")(function* ( id: number, options?: { readonly page?: PageOptions | undefined }, ) { const { owner, repo } = yield* Repo; yield* Effect.annotateCurrentSpan({ owner, repo, id }); // Paginated, and the caller's budget is forwarded. const raw = yield* client.paginate( "GET /repos/{owner}/{repo}/releases/{release_id}/assets", { owner, repo, release_id: id }, options?.page, ); return raw.map(assetOf); }), }; };