diff --git a/.github/workflows/build_docker.yml b/.github/workflows/build_docker.yml index ac7a73727..4d86f6459 100644 --- a/.github/workflows/build_docker.yml +++ b/.github/workflows/build_docker.yml @@ -1,5 +1,15 @@ name: Build Docker image and publish to ECR +# A push to main publishes latest-SNAPSHOT. To publish a release, dispatch on +# its tag once the tag exists: +# +# gh workflow run build_docker.yml --ref v -f image_tag=release +# +# The release check fails the run unless the tag matches package.json and the +# version is new, and it moves latest only for the highest version. Start one +# release at a time: two runs started together can both pass the check before +# either pushes. + on: workflow_dispatch: inputs: @@ -27,27 +37,28 @@ concurrency: jobs: build-and-push-image: runs-on: ubuntu-latest - timeout-minutes: 15 + timeout-minutes: 20 + env: + IS_RELEASE: ${{ github.event_name == 'workflow_dispatch' && inputs.image_tag == 'release' }} + # Where every step pushes and reads, including scripts/releaseImage.ts. + IMAGE: public.ecr.aws/neptune/graph-explorer steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Get package version - id: package-version - run: echo "version=$(node -p 'require("./package.json").version')" >> $GITHUB_OUTPUT + - name: Set up Node.js + if: ${{ env.IS_RELEASE == 'true' }} + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version-file: .node-version + package-manager-cache: false - - name: Get image tag - id: get-image-tag - env: - IS_RELEASE: ${{ github.event_name == 'workflow_dispatch' && inputs.image_tag == 'release' }} - VERSION: ${{ steps.package-version.outputs.version }} - run: | - if [ "$IS_RELEASE" = "true" ]; then - echo "image_tag=$VERSION" >> $GITHUB_OUTPUT - else - echo "image_tag=latest-SNAPSHOT" >> $GITHUB_OUTPUT - fi + # Runs before anything is pushed. + - name: Check the release and choose its tags + id: release + if: ${{ env.IS_RELEASE == 'true' }} + run: node scripts/releaseImage.ts plan - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0 @@ -67,25 +78,21 @@ jobs: - name: Build, tag, and push Docker image env: - REGISTRY: ${{ steps.login-ecr-public.outputs.registry }} - REGISTRY_ALIAS: neptune - REPOSITORY: graph-explorer - IMAGE_TAG: ${{ steps.get-image-tag.outputs.image_tag }} + # Snapshot runs skip the plan, so they push the snapshot tags. + TAGS: ${{ steps.release.outputs.tags || 'latest-SNAPSHOT sagemaker-latest-SNAPSHOT' }} + # TAGS is a space-separated list. run: | - docker build -t $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:$IMAGE_TAG . - docker tag $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:$IMAGE_TAG $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:sagemaker-$IMAGE_TAG - docker push $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:$IMAGE_TAG - docker push $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:sagemaker-$IMAGE_TAG + read -ra tags <<< "$TAGS" + docker build -t "$IMAGE:${tags[0]}" . + for tag in "${tags[@]}"; do + docker tag "$IMAGE:${tags[0]}" "$IMAGE:$tag" + docker push "$IMAGE:$tag" + done - - name: Update latest tag for release - if: ${{ github.event_name == 'workflow_dispatch' && inputs.image_tag == 'release' }} + - name: Check every pushed tag points to one image + if: ${{ env.IS_RELEASE == 'true' }} env: - REGISTRY: ${{ steps.login-ecr-public.outputs.registry }} - REGISTRY_ALIAS: neptune - REPOSITORY: graph-explorer - IMAGE_TAG: ${{ steps.get-image-tag.outputs.image_tag }} + TAGS: ${{ steps.release.outputs.tags }} run: | - docker tag $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:$IMAGE_TAG $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:latest - docker tag $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:sagemaker-$IMAGE_TAG $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:sagemaker-latest - docker push $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:latest - docker push $REGISTRY/$REGISTRY_ALIAS/$REPOSITORY:sagemaker-latest + read -ra tags <<< "$TAGS" + node scripts/releaseImage.ts verify "${tags[@]}" diff --git a/scripts/releaseImage.test.ts b/scripts/releaseImage.test.ts new file mode 100644 index 000000000..1190d331f --- /dev/null +++ b/scripts/releaseImage.test.ts @@ -0,0 +1,377 @@ +import { afterEach, describe, expect, it, type Mock, vi } from "vite-plus/test"; + +import { + checkOneDigest, + fetchDigests, + fetchPublishedTags, + parseImage, + planRelease, +} from "./releaseImage.ts"; + +const image = "public.ecr.aws/neptune/graph-explorer"; + +const publishedTags = [ + "latest", + "sagemaker-latest", + "latest-SNAPSHOT", + "sagemaker-latest-SNAPSHOT", + "3.3.0", + "sagemaker-3.3.0", + "3.3.2", + "sagemaker-3.3.2", + "1.10.0", + "2.0.0", +]; + +describe("planRelease", () => { + it("pushes the version tags and moves latest for the newest version", () => { + expect( + planRelease({ + ref: "refs/tags/v3.4.0", + version: "3.4.0", + publishedTags, + }), + ).toStrictEqual(["3.4.0", "sagemaker-3.4.0", "latest", "sagemaker-latest"]); + }); + + it("leaves latest alone for a version older than one already published", () => { + expect( + planRelease({ + ref: "refs/tags/v3.3.3", + version: "3.3.3", + publishedTags: [...publishedTags, "3.4.0", "sagemaker-3.4.0"], + }), + ).toStrictEqual(["3.3.3", "sagemaker-3.3.3"]); + }); + + it("compares versions numerically, not as text", () => { + expect( + planRelease({ + ref: "refs/tags/v3.10.0", + version: "3.10.0", + publishedTags: ["3.9.0", "3.3.2"], + }), + ).toContain("latest"); + expect( + planRelease({ + ref: "refs/tags/v3.9.1", + version: "3.9.1", + publishedTags: ["3.10.0"], + }), + ).not.toContain("latest"); + }); + + it("ranks non-numeric tags lowest, as the notebook script does", () => { + expect( + planRelease({ + ref: "refs/tags/v0.0.1", + version: "0.0.1", + publishedTags: [ + "latest", + "sagemaker-9.9.9", + "9.9.9-rc1", + "v9.9.9", + "latest-SNAPSHOT", + ], + }), + ).toContain("latest"); + }); + + it("ranks a shorter numeric tag below its longer form", () => { + expect( + planRelease({ + ref: "refs/tags/v3.4.0", + version: "3.4.0", + publishedTags: ["3.4"], + }), + ).toContain("latest"); + }); + + it("leaves latest alone when a published tag has more numeric parts", () => { + expect( + planRelease({ + ref: "refs/tags/v3.4.0", + version: "3.4.0", + publishedTags: ["3.4.0.1"], + }), + ).not.toContain("latest"); + }); + + it("fails when the run is not on a tag", () => { + expect(() => + planRelease({ + ref: "refs/heads/main", + version: "3.4.0", + publishedTags, + }), + ).toThrow( + new Error( + "Release runs must start from the tag v3.4.0, but this run is on refs/heads/main.", + ), + ); + }); + + it("fails when the tag does not match the package.json version", () => { + expect(() => + planRelease({ + ref: "refs/tags/v3.4.1", + version: "3.4.0", + publishedTags, + }), + ).toThrow( + new Error( + "Release runs must start from the tag v3.4.0, but this run is on refs/tags/v3.4.1.", + ), + ); + }); + + it("fails when the version is already published", () => { + expect(() => + planRelease({ + ref: "refs/tags/v3.3.2", + version: "3.3.2", + publishedTags: ["latest", "3.3.2"], + }), + ).toThrow(new Error("3.3.2 is already published.")); + }); + + it("fails when only the sagemaker tag of the version is published", () => { + expect(() => + planRelease({ + ref: "refs/tags/v3.5.0", + version: "3.5.0", + publishedTags: ["sagemaker-3.5.0"], + }), + ).toThrow(new Error("sagemaker-3.5.0 is already published.")); + }); + + it.each(["3.4.0-beta.1", "3.4", "v3.4.0", "03.4.0", "3.4.0.1", ""])( + "fails when the version %j is not a plain X.Y.Z", + version => { + expect(() => + planRelease({ ref: `refs/tags/v${version}`, version, publishedTags }), + ).toThrow( + new Error(`The package.json version "${version}" is not X.Y.Z.`), + ); + }, + ); +}); + +describe("checkOneDigest", () => { + it("returns the digest every tag points to", () => { + expect( + checkOneDigest( + new Map([ + ["3.4.0", "sha256:aaa"], + ["sagemaker-3.4.0", "sha256:aaa"], + ]), + ), + ).toBe("sha256:aaa"); + }); + + it("fails when tags point to different digests", () => { + expect(() => + checkOneDigest( + new Map([ + ["3.4.0", "sha256:aaa"], + ["latest", "sha256:bbb"], + ]), + ), + ).toThrow( + new Error( + "The pushed tags point to more than one image: 3.4.0 sha256:aaa, latest sha256:bbb.", + ), + ); + }); + + it("fails when a tag is missing", () => { + expect(() => + checkOneDigest( + new Map([ + ["3.4.0", "sha256:aaa"], + ["sagemaker-3.4.0", null], + ]), + ), + ).toThrow(new Error("sagemaker-3.4.0 is not in the registry.")); + }); +}); + +describe("parseImage", () => { + it("splits an image into the registry URL and repository", () => { + expect(parseImage(image)).toStrictEqual({ + registry: "https://public.ecr.aws", + repository: "neptune/graph-explorer", + }); + }); + + it.each([ + "", + "graph-explorer", + "public.ecr.aws/", + "/neptune/graph-explorer", + "public.ecr.aws/neptune/graph-explorer:latest", + ])("rejects %j", value => { + expect(() => parseImage(value)).toThrow( + new Error( + `IMAGE must be / with no tag, but it is "${value}".`, + ), + ); + }); +}); + +describe("registry reads", () => { + afterEach(() => { + vi.useRealTimers(); + }); + + function stubRegistry(routes: Record Response>): Mock { + const fetchMock = vi.fn((input: string | URL) => { + const url = String(input); + const route = routes[url]; + if (!route) { + throw new Error(`Unexpected request to ${url}`); + } + return Promise.resolve(route()); + }); + vi.stubGlobal("fetch", fetchMock); + return fetchMock; + } + + const tokenRoute = { + "https://public.ecr.aws/token/": () => Response.json({ token: "anon" }), + }; + + it("reads every tag, following the next page", async () => { + stubRegistry({ + ...tokenRoute, + "https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000": () => + Response.json( + { tags: ["3.3.2", "latest"] }, + { + headers: { + Link: '; rel="next"', + }, + }, + ), + "https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000&last=latest": + () => Response.json({ tags: ["sagemaker-3.3.2"] }), + }); + + await expect(fetchPublishedTags(image)).resolves.toStrictEqual([ + "3.3.2", + "latest", + "sagemaker-3.3.2", + ]); + }); + + it("fails on a tag list it can't read", async () => { + stubRegistry({ + ...tokenRoute, + "https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000": () => + Response.json({ tags: [3] }), + }); + + await expect(fetchPublishedTags(image)).rejects.toThrow( + new Error("The registry returned a tag list without a list of tags."), + ); + }); + + it("fails when the registry refuses the tag list", async () => { + stubRegistry({ + ...tokenRoute, + "https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000": () => + new Response("busy", { status: 503 }), + }); + + await expect(fetchPublishedTags(image)).rejects.toThrow( + new Error( + "GET https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000 returned 503.", + ), + ); + }); + + it("reads each tag's digest, or null when the tag is absent", async () => { + const fetchMock = stubRegistry({ + ...tokenRoute, + "https://public.ecr.aws/v2/neptune/graph-explorer/manifests/3.3.2": () => + new Response(null, { + headers: { "Docker-Content-Digest": "sha256:aaa" }, + }), + "https://public.ecr.aws/v2/neptune/graph-explorer/manifests/3.3.3": () => + new Response(null, { status: 404 }), + }); + + await expect( + fetchDigests(image, ["3.3.2", "3.3.3"]), + ).resolves.toStrictEqual( + new Map([ + ["3.3.2", "sha256:aaa"], + ["3.3.3", null], + ]), + ); + expect(fetchMock).toHaveBeenCalledWith( + "https://public.ecr.aws/v2/neptune/graph-explorer/manifests/3.3.2", + expect.objectContaining({ + method: "HEAD", + headers: expect.objectContaining({ Authorization: "Bearer anon" }), + }), + ); + }); + + it("fails when the registry refuses a digest read", async () => { + stubRegistry({ + ...tokenRoute, + "https://public.ecr.aws/v2/neptune/graph-explorer/manifests/latest": () => + new Response(null, { status: 500 }), + }); + + await expect(fetchDigests(image, ["latest"])).rejects.toThrow( + new Error( + "HEAD https://public.ecr.aws/v2/neptune/graph-explorer/manifests/latest returned 500.", + ), + ); + }); + + it("waits out throttling and asks again", async () => { + vi.useFakeTimers(); + const tagListUrl = + "https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000"; + const statuses = [429, 429, 200]; + const fetchMock = stubRegistry({ + ...tokenRoute, + [tagListUrl]: () => + Response.json({ tags: ["3.3.2"] }, { status: statuses.shift() }), + }); + function tagListCalls() { + return fetchMock.mock.calls.filter(([url]) => url === tagListUrl).length; + } + + const tags = fetchPublishedTags(image); + await vi.advanceTimersByTimeAsync(999); + expect(tagListCalls()).toBe(1); + await vi.advanceTimersByTimeAsync(1); + expect(tagListCalls()).toBe(2); + await vi.runAllTimersAsync(); + + await expect(tags).resolves.toStrictEqual(["3.3.2"]); + expect(tagListCalls()).toBe(3); + }); + + it("gives up when throttling lasts", async () => { + vi.useFakeTimers(); + stubRegistry({ + ...tokenRoute, + "https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000": () => + new Response(null, { status: 429 }), + }); + + const failure = fetchPublishedTags(image).catch((error: unknown) => error); + await vi.runAllTimersAsync(); + + expect(await failure).toStrictEqual( + new Error( + "GET https://public.ecr.aws/v2/neptune/graph-explorer/tags/list?n=1000 returned 429.", + ), + ); + }); +}); diff --git a/scripts/releaseImage.ts b/scripts/releaseImage.ts new file mode 100644 index 000000000..69b4107d8 --- /dev/null +++ b/scripts/releaseImage.ts @@ -0,0 +1,275 @@ +/** + * Decides which tags a release run of build_docker.yml pushes, and checks + * them afterwards. It has no dependencies, so the workflow runs it with plain + * Node and no install. + * + * IMAGE=/ node scripts/releaseImage.ts plan + * IMAGE=/ node scripts/releaseImage.ts verify ... + */ +import { appendFileSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +/** + * An image reference without a tag, such as + * `public.ecr.aws/neptune/graph-explorer`, split into the registry's base URL + * and the repository path. + */ +export function parseImage(image: string): { + registry: string; + repository: string; +} { + const slash = image.indexOf("/"); + if (slash <= 0 || slash === image.length - 1 || image.includes(":")) { + throw new Error( + `IMAGE must be / with no tag, but it is "${image}".`, + ); + } + return { + registry: `https://${image.slice(0, slash)}`, + repository: image.slice(slash + 1), + }; +} + +/** + * Checks a release's inputs and returns the tags to push, in push order. + * Throws when the run must not publish. + */ +export function planRelease({ + ref, + version, + publishedTags, +}: { + ref: string; + version: string; + publishedTags: readonly string[]; +}): string[] { + if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)) { + throw new Error(`The package.json version "${version}" is not X.Y.Z.`); + } + if (ref !== `refs/tags/v${version}`) { + throw new Error( + `Release runs must start from the tag v${version}, but this run is on ${ref}.`, + ); + } + + const tags = [version, `sagemaker-${version}`]; + const published = new Set(publishedTags); + for (const tag of tags) { + if (published.has(tag)) { + throw new Error(`${tag} is already published.`); + } + } + + const key = notebookSortKey(version); + const isNewest = publishedTags.every( + tag => compareSortKeys(key, notebookSortKey(tag)) > 0, + ); + return isNewest ? [...tags, "latest", "sagemaker-latest"] : tags; +} + +// SageMaker notebooks pull `sagemaker-`, ranked by the +// jq in Neptune's lifecycle script, so `latest` must follow that same order: +// sort_by(split(".") | try map(tonumber) catch [0,0,0]) +function notebookSortKey(tag: string): number[] { + const parts = tag.split("."); + return parts.every(part => /^\d+$/.test(part)) + ? parts.map(Number) + : [0, 0, 0]; +} + +function compareSortKeys(a: number[], b: number[]): number { + for (let i = 0; i < Math.min(a.length, b.length); i++) { + if (a[i] !== b[i]) { + return a[i] - b[i]; + } + } + return a.length - b.length; +} + +/** + * Returns the one digest every tag points to. Throws when a tag is missing + * (`null`) or the tags point to different images. + */ +export function checkOneDigest( + digests: ReadonlyMap, +): string { + const found = new Set(); + for (const [tag, digest] of digests) { + if (digest === null) { + throw new Error(`${tag} is not in the registry.`); + } + found.add(digest); + } + const [digest, ...others] = found; + if (digest === undefined) { + throw new Error("No tags to check."); + } + if (others.length > 0) { + const list = [...digests].map(([tag, d]) => `${tag} ${d}`).join(", "); + throw new Error(`The pushed tags point to more than one image: ${list}.`); + } + return digest; +} + +/** Every tag in the public repository, read anonymously. */ +export async function fetchPublishedTags(image: string): Promise { + const { registry, repository } = parseImage(image); + const headers = await anonymousAuth(registry); + const tags: string[] = []; + let url: string | null = `${registry}/v2/${repository}/tags/list?n=1000`; + while (url) { + const response = await request(url, { headers }); + const body: unknown = await response.json(); + tags.push(...parseTagList(body)); + url = nextPage(response.headers.get("Link"), registry); + } + return tags; +} + +/** + * The digest each tag points to, or `null` for a tag that doesn't exist. Asks + * one tag at a time, since the registry throttles bursts of anonymous reads. + */ +export async function fetchDigests( + image: string, + tags: readonly string[], +): Promise> { + const { registry, repository } = parseImage(image); + const headers = { + ...(await anonymousAuth(registry)), + Accept: [ + "application/vnd.oci.image.index.v1+json", + "application/vnd.oci.image.manifest.v1+json", + "application/vnd.docker.distribution.manifest.list.v2+json", + "application/vnd.docker.distribution.manifest.v2+json", + ].join(", "), + }; + const digests = new Map(); + for (const tag of tags) { + const url = `${registry}/v2/${repository}/manifests/${tag}`; + const response = await request(url, { method: "HEAD", headers }, [404]); + if (response.status === 404) { + digests.set(tag, null); + continue; + } + const digest = response.headers.get("Docker-Content-Digest"); + if (!digest) { + throw new Error(`HEAD ${url} returned no digest.`); + } + digests.set(tag, digest); + } + return digests; +} + +async function anonymousAuth( + registry: string, +): Promise<{ Authorization: string }> { + const response = await request(`${registry}/token/`, {}); + const token = stringField( + await response.json(), + "token", + "The registry returned no anonymous token.", + ); + return { Authorization: `Bearer ${token}` }; +} + +const throttleRetryDelaysMs = [1000, 2000, 4000, 8000]; + +/** Fetches `url`, waiting out throttling, and throws on an unexpected status. */ +async function request( + url: string, + init: RequestInit, + allowedStatuses: readonly number[] = [], +): Promise { + let response = await fetch(url, init); + for (const delayMs of throttleRetryDelaysMs) { + if (response.status !== 429) { + break; + } + await new Promise(resolve => setTimeout(resolve, delayMs)); + response = await fetch(url, init); + } + if (!response.ok && !allowedStatuses.includes(response.status)) { + throw new Error( + `${init.method ?? "GET"} ${url} returned ${response.status}.`, + ); + } + return response; +} + +function parseTagList(body: unknown): string[] { + if ( + typeof body === "object" && + body !== null && + "tags" in body && + Array.isArray(body.tags) && + body.tags.every(tag => typeof tag === "string") + ) { + return body.tags; + } + throw new Error("The registry returned a tag list without a list of tags."); +} + +function nextPage(link: string | null, registry: string): string | null { + const match = link?.match(/<([^>]+)>;\s*rel="next"/); + return match ? new URL(match[1], registry).href : null; +} + +function readPackageVersion(): string { + const path = join(import.meta.dirname, "..", "package.json"); + return stringField( + JSON.parse(readFileSync(path, "utf8")), + "version", + "package.json has no version.", + ); +} + +/** The string at `body[key]`, or throws `message` when there isn't one. */ +function stringField(body: unknown, key: string, message: string): string { + const value: unknown = + typeof body === "object" && body !== null + ? Reflect.get(body, key) + : undefined; + if (typeof value === "string") { + return value; + } + throw new Error(message); +} + +function writeOutput(name: string, value: string): void { + process.stdout.write(`${name}=${value}\n`); + const file = process.env.GITHUB_OUTPUT; + if (file) { + appendFileSync(file, `${name}=${value}\n`); + } +} + +async function main([command, ...args]: string[]): Promise { + const image = process.env.IMAGE; + if (!image) { + throw new Error("IMAGE is not set."); + } + if (command === "plan") { + const ref = process.env.GITHUB_REF; + if (!ref) { + throw new Error("GITHUB_REF is not set."); + } + const tags = planRelease({ + ref, + version: readPackageVersion(), + publishedTags: await fetchPublishedTags(image), + }); + writeOutput("tags", tags.join(" ")); + return; + } + if (command === "verify" && args.length > 0) { + const digest = checkOneDigest(await fetchDigests(image, args)); + process.stdout.write(`${args.join(", ")} all point to ${digest}\n`); + return; + } + throw new Error("Usage: releaseImage.ts plan | verify ..."); +} + +if (import.meta.main) { + await main(process.argv.slice(2)); +} diff --git a/scripts/vite.config.ts b/scripts/vite.config.ts index 600ed22de..e98e29e58 100644 --- a/scripts/vite.config.ts +++ b/scripts/vite.config.ts @@ -1,3 +1,8 @@ import { defineConfig } from "vite-plus"; -export default defineConfig({ test: { environment: "node" } }); +export default defineConfig({ + test: { + environment: "node", + unstubGlobals: true, + }, +});