@effected/github-actions 0.1.0

package/Artifact.js

@@ -0,0 +1,423 @@
+import { ActionEnvironment } from "./ActionEnvironment.js";
+import { BlobTransferError } from "./BlobTransfer.js";
+import { resultsBackend } from "./internal/actionsResults.js";
+import { CONFLICT, field, isOk, stringField, twirpCall } from "./internal/twirp.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Result, Schema, Stream } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { createHash } from "node:crypto";
+import { BlobClient, BlockBlobClient } from "@azure/storage-blob";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+//#region src/Artifact.ts
+/**
+* Raised when an artifact cannot be uploaded, listed, downloaded or deleted.
+*
+* @public
+*/
+var ArtifactError = class extends Schema.TaggedErrorClass()("ArtifactError", {
+	/**
+	* `misconfigured` — the results backend is not reachable from here (see
+	* {@link Artifact}). `unreachable` — it could not be contacted, or answered
+	* with something that is not a Twirp body. `refused` — it answered,
+	* unhappily; re-uploading a name that already exists in the run is the
+	* common case. `notFound` — no artifact by that name or id exists in this
+	* run. `archiveFailed` — `zip` would not pack or unpack the files.
+	* `transferFailed` — the archive itself did not move. `invalidOptions` — the
+	* call cannot be made as asked.
+	*/
+	reason: Schema.Literals([
+		"misconfigured",
+		"unreachable",
+		"refused",
+		"notFound",
+		"archiveFailed",
+		"transferFailed",
+		"invalidOptions"
+	]),
+	/** The artifact's name or id. A stable identifier, never a value. */
+	artifact: Schema.optionalKey(Schema.String),
+	/** The HTTP status, when the backend answered. */
+	status: Schema.optionalKey(Schema.Number),
+	/** What went wrong, when the reason alone does not say. */
+	detail: Schema.optionalKey(Schema.String),
+	/** `zip`'s own complaint, which is the only useful part of an archive failure. */
+	stderr: Schema.optionalKey(Schema.String),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		const about = this.artifact === void 0 ? "" : ` "${this.artifact}"`;
+		const detail = this.detail === void 0 ? "" : `: ${this.detail}`;
+		switch (this.reason) {
+			case "misconfigured": return `The artifact service is not reachable from here${detail}`;
+			case "unreachable": return `The artifact service could not be reached${detail}`;
+			case "refused": return `The artifact service refused${about}${this.status === void 0 ? "" : ` with status ${this.status}`}${detail}`;
+			case "notFound": return `No artifact${about} exists in this run`;
+			case "archiveFailed": return `The artifact archive could not be built or extracted${about}${this.stderr === void 0 ? "" : `: ${this.stderr}`}`;
+			case "transferFailed": return `The artifact archive did not transfer${about}`;
+			default: return `The artifact call cannot be made as asked${detail}`;
+		}
+	}
+};
+/** The Twirp service the artifact protocol lives under. */
+const SERVICE = "github.actions.results.api.v1.ArtifactService";
+/**
+* `CreateArtifact`'s `version` field.
+*
+* @remarks
+* `7`, read off `actions/toolkit`'s own upload path. It is a *protocol*
+* version, unrelated to the `v4` in `actions/upload-artifact@v4`, and guessing
+* it from the action's major version — which is the obvious guess — produces a
+* create the backend rejects.
+*/
+const ARTIFACT_VERSION = 7;
+/**
+* The Azure half, duplicated on purpose.
+*
+* @remarks
+* `@azure/storage-blob` may be imported here, by `ActionCache` and by
+* `BlobStore.githubCache`, and nowhere else. Hoisting these two calls into a
+* shared `internal/` helper is exactly how a heavy import leaks into the graph
+* of a module that only sets an output; `__test__/reachability.test.ts`
+* measures that these are the only three.
+*/
+const azure = {
+	uploadFile: (url, file) => Effect.tryPromise({
+		try: () => new BlockBlobClient(url).uploadFile(file, {
+			blockSize: 64 * 1024 * 1024,
+			concurrency: 8,
+			maxSingleShotSize: 128 * 1024 * 1024
+		}),
+		catch: (cause) => new BlobTransferError({
+			reason: "uploadFailed",
+			cause
+		})
+	}).pipe(Effect.asVoid),
+	downloadToFile: (url, file) => Effect.tryPromise({
+		try: () => new BlobClient(url).downloadToFile(file),
+		catch: (cause) => new BlobTransferError({
+			reason: "downloadFailed",
+			cause
+		})
+	}).pipe(Effect.asVoid)
+};
+const fromTwirp = (failure, artifact) => failure.kind === "status" ? new ArtifactError({
+	reason: "refused",
+	artifact,
+	detail: failure.method,
+	...failure.status === void 0 ? {} : { status: failure.status }
+}) : new ArtifactError({
+	reason: "unreachable",
+	artifact,
+	detail: `${failure.method} did not answer with a Twirp body`,
+	...failure.cause === void 0 ? {} : { cause: failure.cause }
+});
+/** One row of a `ListArtifacts` answer, read under either field spelling. */
+const toItem = (row) => {
+	const createdAt = stringField(row, "createdAt");
+	return {
+		id: Number(stringField(row, "databaseId") ?? 0),
+		name: stringField(row, "name") ?? "",
+		size: Number(stringField(row, "size") ?? 0),
+		...createdAt === void 0 ? {} : { createdAt }
+	};
+};
+const make = (transfer) => Effect.gen(function* () {
+	const http = yield* HttpClient.HttpClient;
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	const env = yield* ActionEnvironment;
+	const windows = yield* Effect.map(env.getOptional("RUNNER_OS"), (found) => Option.match(found, {
+		onNone: () => false,
+		onSome: (os) => os.toLowerCase() === "windows"
+	}));
+	const backend = (artifact) => resultsBackend(env).pipe(Effect.mapError((name) => new ArtifactError({
+		reason: "misconfigured",
+		artifact,
+		detail: `${name} is not set — the artifact service is only reachable from a \`uses:\` step, never from \`run:\``
+	})), Effect.flatMap((resolved) => Result.isFailure(resolved.backendIds) ? Effect.fail(new ArtifactError({
+		reason: "misconfigured",
+		artifact,
+		detail: resolved.backendIds.failure
+	})) : Effect.succeed({
+		baseUrl: resolved.baseUrl,
+		token: resolved.token,
+		ids: resolved.backendIds.success
+	})));
+	const call = (method, body, artifact) => Effect.gen(function* () {
+		const { baseUrl, ids, token } = yield* backend(artifact);
+		return yield* twirpCall({
+			http,
+			baseUrl,
+			service: SERVICE,
+			token,
+			method,
+			body: {
+				...ids,
+				...body(ids)
+			}
+		}).pipe(Effect.mapError((failure) => fromTwirp(failure, artifact)));
+	});
+	const listAll = (artifact) => Effect.map(call("ListArtifacts", () => ({}), artifact), (answer) => {
+		if (answer === CONFLICT) return [];
+		const rows = field(answer, "artifacts");
+		return Array.isArray(rows) ? rows.map(toItem) : [];
+	});
+	/** Run an archiving command, keeping its stderr. */
+	const archive = (command, artifact) => Effect.gen(function* () {
+		const output = yield* spawner.string(command, { includeStderr: true }).pipe(Effect.mapError((cause) => new ArtifactError({
+			reason: "archiveFailed",
+			artifact,
+			cause
+		})));
+		if ((yield* spawner.exitCode(command).pipe(Effect.mapError((cause) => new ArtifactError({
+			reason: "archiveFailed",
+			artifact,
+			cause
+		})))) !== 0) return yield* Effect.fail(new ArtifactError({
+			reason: "archiveFailed",
+			artifact,
+			stderr: output.trim()
+		}));
+	});
+	const scratch = (artifact, use) => Effect.acquireUseRelease(fs.makeTempDirectory({ prefix: "effected-artifact-" }).pipe(Effect.mapError((cause) => new ArtifactError({
+		reason: "archiveFailed",
+		artifact,
+		cause
+	}))), use, (directory) => Effect.ignore(fs.remove(directory, {
+		recursive: true,
+		force: true
+	})));
+	/**
+	* The SHA-256 the backend finalizes against.
+	*
+	* @remarks
+	* Over the *stored zip*, streamed rather than read: an artifact is the one
+	* payload in this package with no upper bound on size, and a runner has
+	* roughly seven gigabytes of memory for everything.
+	*/
+	const digestOf = (file, artifact) => Effect.gen(function* () {
+		const accumulator = createHash("sha256");
+		yield* Stream.runForEach(fs.stream(file), (chunk) => Effect.sync(() => {
+			accumulator.update(chunk);
+		})).pipe(Effect.mapError((cause) => new ArtifactError({
+			reason: "archiveFailed",
+			artifact,
+			cause
+		})));
+		return accumulator.digest("hex");
+	});
+	const moved = (artifact) => Effect.mapError((cause) => new ArtifactError({
+		reason: "transferFailed",
+		artifact,
+		cause
+	}));
+	const zip = (files, root, destination, level, artifact) => {
+		const relative = files.map((file) => path.relative(root, file));
+		return windows ? archive(ChildProcess.make("pwsh", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`Compress-Archive -Path ${relative.map((file) => `'${file.replaceAll("'", "''")}'`).join(",")} -DestinationPath '${destination.replaceAll("'", "''")}' -Force`
+		], { cwd: root }), artifact) : archive(ChildProcess.make("zip", [
+			`-${Math.min(9, Math.max(0, Math.trunc(level)))}`,
+			"-qr",
+			destination,
+			...relative
+		], { cwd: root }), artifact);
+	};
+	const unzip = (source, destination, artifact) => windows ? archive(ChildProcess.make("pwsh", [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		`Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${source.replaceAll("'", "''")}', '${destination.replaceAll("'", "''")}')`
+	]), artifact) : archive(ChildProcess.make("unzip", [
+		"-oq",
+		source,
+		"-d",
+		destination
+	]), artifact);
+	return {
+		upload: Effect.fn("Artifact.upload")(function* (name, files, rootDirectory, options) {
+			yield* Effect.annotateCurrentSpan({ name });
+			if (files.length === 0) return yield* Effect.fail(new ArtifactError({
+				reason: "invalidOptions",
+				artifact: name,
+				detail: "no files were given to upload"
+			}));
+			if (options?.retentionDays !== void 0 && options.retentionDays <= 0) return yield* Effect.fail(new ArtifactError({
+				reason: "invalidOptions",
+				artifact: name,
+				detail: "retentionDays must be positive — omit it to use the repository default"
+			}));
+			return yield* scratch(name, (directory) => Effect.gen(function* () {
+				const packed = path.join(directory, "artifact.zip");
+				yield* zip(files, rootDirectory, packed, options?.compressionLevel ?? 6, name);
+				const created = yield* call("CreateArtifact", () => ({
+					name,
+					version: ARTIFACT_VERSION,
+					mimeType: "application/zip"
+				}), name);
+				if (created === CONFLICT || !isOk(created)) return yield* Effect.fail(new ArtifactError({
+					reason: "refused",
+					artifact: name,
+					detail: "an artifact with this name already exists in this run"
+				}));
+				const url = stringField(created, "signedUploadUrl");
+				if (url === void 0) return yield* Effect.fail(new ArtifactError({
+					reason: "refused",
+					artifact: name,
+					detail: "CreateArtifact returned no upload url"
+				}));
+				yield* transfer.uploadFile(url, packed).pipe(moved(name));
+				const size = yield* fs.stat(packed).pipe(Effect.mapError((cause) => new ArtifactError({
+					reason: "archiveFailed",
+					artifact: name,
+					cause
+				})));
+				const digest = yield* digestOf(packed, name);
+				const finalized = yield* call("FinalizeArtifact", () => ({
+					name,
+					size: String(size.size),
+					hash: `sha256:${digest}`,
+					...options?.retentionDays === void 0 ? {} : { expiresAt: new Date(Date.now() + options.retentionDays * 864e5).toISOString() }
+				}), name);
+				if (finalized === CONFLICT || !isOk(finalized)) return yield* Effect.fail(new ArtifactError({
+					reason: "refused",
+					artifact: name,
+					detail: "FinalizeArtifact did not confirm the upload"
+				}));
+				return {
+					id: Number(stringField(finalized, "artifactId") ?? 0),
+					size: Number(size.size)
+				};
+			}));
+		}),
+		list: Effect.fn("Artifact.list")(function* () {
+			return yield* listAll("*");
+		}),
+		get: Effect.fn("Artifact.get")(function* (name) {
+			yield* Effect.annotateCurrentSpan({ name });
+			const all = yield* listAll(name);
+			return Option.fromNullishOr(all.find((item) => item.name === name));
+		}),
+		download: Effect.fn("Artifact.download")(function* (artifactId, options) {
+			const label = String(artifactId);
+			yield* Effect.annotateCurrentSpan({ artifactId });
+			const found = (yield* listAll(label)).find((item) => item.id === artifactId);
+			if (found === void 0) return yield* Effect.fail(new ArtifactError({
+				reason: "notFound",
+				artifact: label
+			}));
+			const signed = yield* call("GetSignedArtifactURL", () => ({ name: found.name }), label);
+			const url = signed === CONFLICT ? void 0 : stringField(signed, "signedUrl");
+			if (url === void 0) return yield* Effect.fail(new ArtifactError({
+				reason: "refused",
+				artifact: label,
+				detail: "GetSignedArtifactURL returned no url"
+			}));
+			const destination = options?.path;
+			const downloadPath = destination === void 0 ? yield* fs.makeTempDirectory({ prefix: "effected-artifact-download-" }).pipe(Effect.mapError((cause) => new ArtifactError({
+				reason: "archiveFailed",
+				artifact: label,
+				cause
+			}))) : yield* fs.makeDirectory(destination, { recursive: true }).pipe(Effect.as(destination), Effect.mapError((cause) => new ArtifactError({
+				reason: "archiveFailed",
+				artifact: label,
+				cause
+			})));
+			yield* scratch(label, (directory) => Effect.gen(function* () {
+				const packed = path.join(directory, "artifact.zip");
+				yield* transfer.downloadToFile(url, packed).pipe(moved(label));
+				yield* unzip(packed, downloadPath, label);
+			}));
+			return { downloadPath };
+		}),
+		delete: Effect.fn("Artifact.delete")(function* (name) {
+			yield* Effect.annotateCurrentSpan({ name });
+			const found = (yield* listAll(name)).find((item) => item.name === name);
+			if (found === void 0) return yield* Effect.fail(new ArtifactError({
+				reason: "notFound",
+				artifact: name
+			}));
+			const deleted = yield* call("DeleteArtifact", () => ({ name }), name);
+			if (deleted === CONFLICT || !isOk(deleted)) return yield* Effect.fail(new ArtifactError({
+				reason: "refused",
+				artifact: name,
+				detail: "DeleteArtifact did not confirm"
+			}));
+			return { id: Number(stringField(deleted, "artifactId") ?? found.id) };
+		})
+	};
+});
+const unimplemented = (member) => {
+	throw new Error(`Artifact.makeTest: ${member}() was called but not stubbed — pass a \`${member}\` override.`);
+};
+/**
+* Upload, list, download and delete GitHub Actions artifacts.
+*
+* @remarks
+* Speaks the artifact **Twirp v2** protocol at `ACTIONS_RESULTS_URL`, which
+* answers with a pre-signed Azure blob url for the zip. No `@actions/artifact`
+* dependency.
+*
+* **Only reachable from a `uses:` step**, like {@link ActionCache} — the two
+* variables it needs are injected into action execution contexts and not into
+* `run:` shell steps. The `Actions.Results` scope inside the runtime token is a
+* third thing that can be absent, and it is reported as `misconfigured` for the
+* same reason.
+*
+* **This surface is provisional.** Unlike every other service here it was
+* ported without a call site to shape it against, so it keeps the source's
+* shape rather than a narrower one invented from nothing. The first consumer to
+* adopt it is the one whose feedback reshapes it — the members lost their
+* `Artifact` prefix (`artifact.uploadArtifact(...)` stutters) and the
+* cross-run `findBy` lookup is **not** ported, because every path through it in
+* the source is a typed "not implemented" failure. Adding it later is additive;
+* shipping a parameter that has never had behavior is not.
+*
+* @example
+* ```ts
+* import { Artifact } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const artifacts = yield* Artifact;
+*   return yield* artifacts.upload("logs", ["/tmp/build/log.txt"], "/tmp/build");
+* });
+* ```
+*
+* @public
+*/
+var Artifact = class Artifact extends Context.Service()("@effected/github-actions/Artifact") {
+	/** The service, over the real Azure client and the real `zip`. */
+	static layer = Layer.effect(this, make(azure));
+	/**
+	* The service, over a supplied transport.
+	*
+	* @remarks
+	* The protocol, the zip, the digest and the conflict handling are what this
+	* package owns; the pre-signed `PUT` is not. Supplying the transport is what
+	* lets a test exercise all of the first group without the second.
+	*
+	* A parameterized layer factory mints a fresh layer per call and layers
+	* memoize by reference — bind it to a `const` rather than calling it at each
+	* composition site.
+	*/
+	static layerWith = (transfer) => Layer.effect(Artifact, make(transfer));
+	/** A test double. Unstubbed members die rather than reporting an empty run. */
+	static makeTest = (overrides = {}) => ({
+		upload: () => Effect.sync(() => unimplemented("upload")),
+		list: () => Effect.sync(() => unimplemented("list")),
+		get: () => Effect.sync(() => unimplemented("get")),
+		download: () => Effect.sync(() => unimplemented("download")),
+		delete: () => Effect.sync(() => unimplemented("delete")),
+		...overrides
+	});
+	/** {@link Artifact.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(Artifact, Artifact.makeTest(overrides));
+};
+
+//#endregion
+export { Artifact, ArtifactError };

package/BlobEnvelope.js

@@ -0,0 +1,135 @@
+import { Result, Schema } from "effect";
+
+//#region src/BlobEnvelope.ts
+/**
+* Raised when bytes cannot be read as an envelope.
+*
+* @public
+*/
+var BlobEnvelopeError = class extends Schema.TaggedErrorClass()("BlobEnvelopeError", {
+	/**
+	* `notAnEnvelope` — the magic prefix is absent, so these are raw bytes
+	* written before this format existed (or by something else entirely).
+	* `unsupportedVersion` — an envelope from a newer revision.
+	* `truncated` — the frame ends mid-header or mid-metadata.
+	* `metadataDecodeFailed` — the metadata is well-framed but does not satisfy
+	* the caller's schema. `metadataEncodeFailed` — the value being stored does
+	* not satisfy it.
+	*/
+	reason: Schema.Literals([
+		"notAnEnvelope",
+		"unsupportedVersion",
+		"truncated",
+		"metadataDecodeFailed",
+		"metadataEncodeFailed"
+	]),
+	/** The envelope version found, when one was readable. */
+	version: Schema.optionalKey(Schema.Number),
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		switch (this.reason) {
+			case "notAnEnvelope": return "Bytes are not an @effected/github-actions blob envelope";
+			case "unsupportedVersion": return `Blob envelope version ${this.version} is not supported`;
+			case "truncated": return "Blob envelope is truncated";
+			case "metadataDecodeFailed": return "Blob envelope metadata did not satisfy the schema";
+			default: return "Blob metadata could not be encoded";
+		}
+	}
+};
+/** Identifies the frame family. Four bytes: `E F B S`. */
+const MAGIC = Uint8Array.from([
+	69,
+	70,
+	66,
+	83
+]);
+/** The only version this build writes. */
+const VERSION = 1;
+/** magic + version + metadata length. */
+const HEADER_BYTES = MAGIC.length + 1 + 4;
+/**
+* The schema-versioned frame that gives a stored blob a **metadata channel**.
+*
+* @remarks
+* Layout:
+*
+* ```text
+* [4B magic "EFBS"][1B version][4B metadata length, big-endian][metadata JSON][body]
+* ```
+*
+* Three properties earn the format, and each replaces something a consumer was
+* hand-rolling:
+*
+* - **The magic prefix makes a legacy blob legible.** Raw, unframed bytes
+*   decode as `notAnEnvelope` rather than as garbage metadata, so a store
+*   holding pre-envelope entries produces a clean miss instead of a corrupt
+*   read.
+* - **The version lives in the blob, not in the key.** A consumer previously
+*   namespaced keys (`v2/...`) to represent a format change, because there was
+*   no in-band version. Here a revision is detected on read and reported
+*   typed, so **keys stay stable** and old entries age out naturally.
+* - **The metadata is the caller's own schema.** This module owns *framing*;
+*   the caller owns *meaning*. Fields like a cache tag or a duration stop
+*   being bytes at fixed offsets in a consumer's private codec.
+*
+* **Pure**: `Result`-returning, no IO, no service — the framing is testable
+* from a byte array, which is the point.
+*
+* @public
+*/
+var BlobEnvelope = class {
+	constructor() {}
+	/** The version this build writes. */
+	static version = VERSION;
+	/** Frame metadata and a body into a single blob. */
+	static encodeResult(metadata, body, schema) {
+		const encoded = Schema.encodeUnknownResult(schema)(metadata);
+		if (Result.isFailure(encoded)) return Result.fail(new BlobEnvelopeError({
+			reason: "metadataEncodeFailed",
+			cause: encoded.failure
+		}));
+		const metaBytes = new TextEncoder().encode(JSON.stringify(encoded.success));
+		const out = new Uint8Array(HEADER_BYTES + metaBytes.length + body.length);
+		out.set(MAGIC, 0);
+		out[MAGIC.length] = VERSION;
+		new DataView(out.buffer).setUint32(MAGIC.length + 1, metaBytes.length, false);
+		out.set(metaBytes, HEADER_BYTES);
+		out.set(body, HEADER_BYTES + metaBytes.length);
+		return Result.succeed(out);
+	}
+	/** Read a framed blob back into its metadata and body. */
+	static decodeResult(bytes, schema) {
+		if (bytes.length < MAGIC.length || !MAGIC.every((byte, index) => bytes[index] === byte)) return Result.fail(new BlobEnvelopeError({ reason: "notAnEnvelope" }));
+		if (bytes.length < HEADER_BYTES) return Result.fail(new BlobEnvelopeError({ reason: "truncated" }));
+		const version = bytes[MAGIC.length] ?? 0;
+		if (version !== VERSION) return Result.fail(new BlobEnvelopeError({
+			reason: "unsupportedVersion",
+			version
+		}));
+		const metaLength = new DataView(bytes.buffer, bytes.byteOffset).getUint32(MAGIC.length + 1, false);
+		if (bytes.length < HEADER_BYTES + metaLength) return Result.fail(new BlobEnvelopeError({ reason: "truncated" }));
+		const metaText = new TextDecoder().decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + metaLength));
+		let parsed;
+		try {
+			parsed = JSON.parse(metaText);
+		} catch (cause) {
+			return Result.fail(new BlobEnvelopeError({
+				reason: "metadataDecodeFailed",
+				cause
+			}));
+		}
+		const decoded = Schema.decodeUnknownResult(schema)(parsed);
+		if (Result.isFailure(decoded)) return Result.fail(new BlobEnvelopeError({
+			reason: "metadataDecodeFailed",
+			cause: decoded.failure
+		}));
+		return Result.succeed({
+			metadata: decoded.success,
+			body: bytes.slice(HEADER_BYTES + metaLength)
+		});
+	}
+};
+
+//#endregion
+export { BlobEnvelope, BlobEnvelopeError };