pinnace 0.0.0 → 0.1.0

package/src/rpc/mock-kubo.ts

@@ -0,0 +1,194 @@
+/**
+ * A mock Kubo HTTP API for tests: it RECORDS every incoming request (method,
+ * path, query, headers, body) and returns canned responses, so a test can
+ * assert the exact call shape a `KuboRpcClient` produced WITHOUT a live daemon.
+ *
+ * This is the primary test boundary for every host-agnostic pinnace operation
+ * (deploy, publish, status, site management). It is exposed from the package's
+ * test surface so sibling tasks (deploy-multi-target, status-report, ...) reuse
+ * it rather than re-inventing a Kubo fake.
+ */
+
+/** One multipart file part the mock extracted from a `FormData` body. */
+export interface RecordedFilePart {
+	/** The multipart field name (Kubo's file-upload endpoints expect `file`). */
+	field: string;
+	/** The optional filename the part was appended with. */
+	filename?: string;
+	/** The part's bytes. */
+	bytes: Uint8Array;
+}
+
+/** One recorded RPC request as the mock observed it. */
+export interface RecordedRequest {
+	/** The HTTP method (Kubo RPC is always POST). */
+	method: string;
+	/** The `/api/v0/...` path, WITHOUT the base URL or query string. */
+	path: string;
+	/** Parsed query parameters (multi-valued: `arg` can repeat). */
+	query: URLSearchParams;
+	/** Lower-cased header name → value, as fetch delivered them. */
+	headers: Record<string, string>;
+	/** The raw request body as text (empty string if none). */
+	bodyText: string;
+	/**
+	 * The effective request `content-type`. For a `FormData` body this is
+	 * `multipart/form-data` (real `fetch` sets it, WITH a boundary, when it
+	 * serialises FormData) even though the caller must NOT hand-set it — the
+	 * mock derives it here so tests can assert the multipart contract Kubo
+	 * requires for its file-upload endpoints.
+	 */
+	contentType?: string;
+	/**
+	 * When the body was a `FormData` (a `multipart/form-data` upload), the file
+	 * parts it carried. Empty/undefined for non-multipart bodies. Kubo's
+	 * `add`, `dag/import` and `key/import` require at least one file part under
+	 * the field name `file`.
+	 */
+	fileParts?: RecordedFilePart[];
+	/** The full URL that was fetched. */
+	url: string;
+}
+
+/** A canned response for a given `/api/v0/<path>` (path without query). */
+export interface MockResponseSpec {
+	/** HTTP status to return (default 200). */
+	status?: number;
+	/** JSON body to return; serialised and sent with content-type application/json. */
+	json?: unknown;
+	/** Raw text body to return (takes precedence over `json` if both set). */
+	text?: string;
+}
+
+/**
+ * A recording mock Kubo API. Install it with {@link fetchImpl} as the `fetch`
+ * a {@link KuboRpcClient} uses; inspect {@link requests} afterwards.
+ */
+export class MockKuboApi {
+	/** Every request the mock received, in order. */
+	readonly requests: RecordedRequest[] = [];
+
+	/** path (no query) → canned response. */
+	private readonly responses = new Map<string, MockResponseSpec>();
+
+	/** The base URL this mock pretends to be (only its path/query are used). */
+	constructor(readonly baseUrl: string = 'https://node.example.test') {}
+
+	/** Register a canned response for a Kubo `/api/v0/<path>` (path without query). */
+	on(path: string, spec: MockResponseSpec): this {
+		this.responses.set(path, spec);
+		return this;
+	}
+
+	/** The most recent recorded request, or undefined if none. */
+	get lastRequest(): RecordedRequest | undefined {
+		return this.requests[this.requests.length - 1];
+	}
+
+	/** All recorded requests whose path equals `path`. */
+	requestsFor(path: string): RecordedRequest[] {
+		return this.requests.filter((r) => r.path === path);
+	}
+
+	/**
+	 * A `fetch`-compatible function that records the request and returns the
+	 * canned (or a default empty-JSON 200) response. Pass this to the client.
+	 */
+	readonly fetchImpl = async (
+		input: string | URL,
+		init?: {method?: string; headers?: Record<string, string>; body?: unknown},
+	): Promise<Response> => {
+		const url = new URL(typeof input === 'string' ? input : input.toString());
+		const path = url.pathname.replace(/^\/api\/v0\//, '');
+		const headers: Record<string, string> = {};
+		for (const [k, v] of Object.entries(init?.headers ?? {})) {
+			headers[k.toLowerCase()] = v;
+		}
+		const {bodyText, contentType, fileParts} = await inspectBody(
+			init?.body,
+			headers,
+		);
+		this.requests.push({
+			method: init?.method ?? 'GET',
+			path,
+			query: new URLSearchParams(url.search),
+			headers,
+			bodyText,
+			contentType,
+			fileParts,
+			url: url.toString(),
+		});
+
+		const spec = this.responses.get(path);
+		const status = spec?.status ?? 200;
+		if (spec?.text !== undefined) {
+			return new Response(spec.text, {status});
+		}
+		const payload = spec?.json ?? {};
+		return new Response(JSON.stringify(payload), {
+			status,
+			headers: {'content-type': 'application/json'},
+		});
+	};
+}
+
+/**
+ * Inspect a fetch body the way a real `fetch` would surface it to Kubo:
+ * derive the effective `content-type` and, for a `multipart/form-data`
+ * (`FormData`) body, extract the file parts. This is what lets the mock
+ * ENFORCE Kubo's real upload contract (multipart + a `file` part) instead of
+ * merely recording raw bytes — the fidelity gap that let raw octet-stream
+ * uploads ship and then fail against a live daemon.
+ */
+async function inspectBody(
+	body: unknown,
+	headers: Record<string, string>,
+): Promise<{
+	bodyText: string;
+	contentType?: string;
+	fileParts?: RecordedFilePart[];
+}> {
+	if (body instanceof FormData) {
+		// Real `fetch` serialises a FormData as `multipart/form-data; boundary=…`
+		// and IGNORES any hand-set content-type. Model that here.
+		const fileParts: RecordedFilePart[] = [];
+		const textLines: string[] = [];
+		// This TS `lib` (dom) types FormData without `entries()`/an iterator, so
+		// collect the parts via `forEach` (which IS typed) then process them.
+		const entries: Array<[string, FormDataEntryValue]> = [];
+		body.forEach((value, field) => {
+			entries.push([field, value]);
+		});
+		for (const [field, value] of entries) {
+			if (value instanceof Blob) {
+				const bytes = new Uint8Array(await value.arrayBuffer());
+				const filename =
+					typeof (value as File).name === 'string'
+						? (value as File).name
+						: undefined;
+				fileParts.push({field, filename, bytes});
+			} else {
+				textLines.push(`${field}=${String(value)}`);
+			}
+		}
+		return {
+			bodyText: textLines.join('&'),
+			contentType: 'multipart/form-data',
+			fileParts,
+		};
+	}
+	return {
+		bodyText: await bodyToText(body),
+		contentType: headers['content-type'],
+	};
+}
+
+/** Best-effort stringify of a non-multipart fetch body for recording. */
+async function bodyToText(body: unknown): Promise<string> {
+	if (body === undefined || body === null) return '';
+	if (typeof body === 'string') return body;
+	if (body instanceof Blob) return await body.text();
+	if (body instanceof URLSearchParams) return body.toString();
+	if (body instanceof Uint8Array) return Buffer.from(body).toString('utf8');
+	return String(body);
+}

package/src/site/site-management.ts

@@ -0,0 +1,241 @@
+/**
+ * First-class **site management** — the `site` namespace (spec user stories 4,
+ * 15; CONTEXT.md `gateway warming`). Sites are auto-discovered from MFS
+ * `/sites/*` (that is how `gateway warming`, IPNS republish, and `status` find
+ * them), so managing the sites a node serves = managing those MFS entries + the
+ * pins that back them. This module gives the operator explicit verbs for that
+ * lifecycle instead of leaving it an implicit side-effect of `deploy`:
+ *
+ *   - **list**   — enumerate `/sites/*` with each site's current CID and, when a
+ *                  same-`id` keystore key exists, its IPNS id.
+ *   - **remove** — `files/rm /sites/<id>` (the entry drops out of
+ *                  warm/republish/status auto-discovery) AND `pin/rm <cid>` so
+ *                  the content stops being served/announced and its storage is
+ *                  reclaimed.
+ *   - **add**    — place an already-imported `/ipfs/<cid>` into MFS
+ *                  `/sites/<id>` (mkdir parents / rm old / cp). See the
+ *                  DESIGN NOTE below on its relationship to `deploy`.
+ *
+ * Every verb speaks ONLY the Kubo RPC seam (MFS + pin endpoints), so the same
+ * core is usable both as a TypeScript API and behind the thin `pinnace site
+ * <verb>` CLI (CONTEXT.md `core vs cli`). Tests drive it through the recording
+ * `MockKuboApi`, never a live daemon (spec Testing Decisions).
+ *
+ * DESIGN NOTE (add vs deploy) — recorded per the task's "decide during build".
+ * `add` is a DISTINCT verb, not an alias over `deploy`. `deploy` (see
+ * `deploy-multi-target`) builds a fresh CAR, imports+pins it on every node, and
+ * THEN performs this MFS-placement step. `add` is exactly that final placement
+ * step in isolation: it takes an EXISTING CID (already imported/pinned, e.g. a
+ * known-good historical CID, or one imported out of band) and makes the node
+ * serve it under a site name, WITHOUT building or importing a CAR. Adding a site
+ * from an existing CID is a meaningful operation deploy does not cover (no fresh
+ * artifact), so it earns its own verb. Deploy is expected to REUSE
+ * {@link placeInMfs} for its placement step when it lands, keeping a single
+ * implementation of the mkdir/rm/cp sequence rather than forking it. This is
+ * NOT a new domain concept: `add` sits at the same layer as the other explicit
+ * client verbs and reuses the existing `/sites/<name>` MFS convention.
+ */
+import type {KuboRpcClient} from '../rpc/kubo-rpc-client.js';
+
+/** The three site-management verbs, under the `site` namespace. */
+export type SiteVerb = 'list' | 'remove' | 'add';
+
+/** The verbs, in a stable order (for help text / iteration). */
+export const SITE_VERBS: readonly SiteVerb[] = ['list', 'remove', 'add'];
+
+/** The MFS directory sites live under. */
+const DEFAULT_SITES_DIR = '/sites';
+
+/** One site as listed: its MFS `id`, current CID, and IPNS id if a key exists. */
+export interface SiteListing {
+	/** The site's single `id` (its MFS entry under `/sites/`). */
+	id: string;
+	/** The current content root CID (`files/stat --hash`). */
+	cid: string;
+	/** The IPNS id, if a same-`id` keystore key exists (ipfs-mode sites lack one). */
+	ipns?: string;
+}
+
+/** Inputs shared by every site-management verb. */
+interface SiteBaseInput {
+	/** The Kubo RPC client for the node whose sites are being managed. */
+	client: KuboRpcClient;
+	/** The MFS directory sites live under (default `/sites`). */
+	sitesDir?: string;
+}
+
+/** Inputs to {@link listSites}. */
+export type ListSitesInput = SiteBaseInput;
+
+/** Inputs to {@link removeSite}. */
+export interface RemoveSiteInput extends SiteBaseInput {
+	/** The site `id` (its MFS entry `/sites/<id>`) to remove. */
+	id: string;
+}
+
+/** The outcome of {@link removeSite}. */
+export interface RemoveSiteResult {
+	/** The site `id` that was removed. */
+	id: string;
+	/** The CID that backed it (undefined if it had no resolvable content). */
+	cid?: string;
+	/** True when the content was unpinned (storage reclaimed); false if unpin failed. */
+	unpinned: boolean;
+}
+
+/** Inputs to {@link addSite}. */
+export interface AddSiteInput extends SiteBaseInput {
+	/** The site `id` to expose it under (its MFS entry `/sites/<id>`). */
+	id: string;
+	/** The already-imported content root CID to place into MFS. */
+	cid: string;
+}
+
+/** The outcome of {@link addSite}. */
+export interface AddSiteResult {
+	/** The site `id` that was placed. */
+	id: string;
+	/** The CID that now backs it in MFS. */
+	cid: string;
+}
+
+/**
+ * **list** — enumerate the sites the node currently serves (MFS `/sites/*`),
+ * annotating each with its current CID (from `files/stat`) and, when a keystore
+ * key of the same name exists, its IPNS id (from `key/list -l`). A fresh box
+ * with no `/sites` dir yields an empty list, not an error.
+ */
+export async function listSites(input: ListSitesInput): Promise<SiteListing[]> {
+	const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+	const entries = await lsSites(input.client, sitesDir);
+	if (entries.length === 0) return [];
+
+	const keys = await listKeys(input.client);
+	const sites: SiteListing[] = [];
+	for (const id of entries) {
+		const cid = await statCid(input.client, `${sitesDir}/${id}`);
+		if (!cid) continue; // an entry with no resolvable CID is skipped, not fatal.
+		sites.push({id, cid, ipns: keys.get(id)});
+	}
+	return sites;
+}
+
+/**
+ * **remove** — delete a site: `files/rm /sites/<name>` FIRST (so it immediately
+ * drops out of MFS auto-discovery and stops being served/announced/warmed),
+ * THEN `pin/rm <cid>` to unpin the content so its storage is reclaimed. The CID
+ * is resolved up-front with `files/stat` so we know what to unpin after the
+ * entry is gone.
+ *
+ * The MFS removal is the load-bearing step and is always attempted. The unpin
+ * is best-effort: if the content was never pinned (or is pinned indirectly),
+ * `pin/rm` errors, which is REPORTED (`unpinned: false`) rather than thrown, so
+ * a partially-pinned site still removes cleanly.
+ */
+export async function removeSite(
+	input: RemoveSiteInput,
+): Promise<RemoveSiteResult> {
+	const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+	const path = `${sitesDir}/${input.id}`;
+
+	// Resolve the CID before we remove the entry (afterwards it is gone).
+	const cid = await statCid(input.client, path);
+
+	// Remove the MFS entry first: it stops being discovered/served/announced.
+	await input.client.filesRm(path, {recursive: true, force: true});
+
+	// Then reclaim storage by unpinning the content. Best-effort: a site that
+	// was never pinned (or pinned indirectly) must not fail the removal.
+	let unpinned = false;
+	if (cid) {
+		try {
+			await input.client.pinRm(cid);
+			unpinned = true;
+		} catch {
+			unpinned = false;
+		}
+	}
+
+	return {id: input.id, cid, unpinned};
+}
+
+/**
+ * **add** — expose an existing CID as a served site by placing it into MFS at
+ * `/sites/<name>` (the discoverable location warm/republish/status read). This
+ * is deploy's MFS-placement step in isolation (see the module DESIGN NOTE): it
+ * does NOT build or import a CAR and does NOT pin (the CID is assumed already
+ * imported/pinned on the node).
+ */
+export async function addSite(input: AddSiteInput): Promise<AddSiteResult> {
+	const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+	await placeInMfs(input.client, sitesDir, input.id, input.cid);
+	return {id: input.id, cid: input.cid};
+}
+
+/**
+ * The MFS-placement step: `files/mkdir /sites --parents`, `files/rm
+ * /sites/<id> --recursive --force` (clear any prior content), then `files/cp
+ * /ipfs/<cid> /sites/<id>`. Ported from the reference prototype's deploy MFS
+ * placement (`~/searches/ipfs-hetzner/deploy-car.mjs`). Exported so `deploy`
+ * can REUSE this exact sequence rather than forking it.
+ */
+export async function placeInMfs(
+	client: KuboRpcClient,
+	sitesDir: string,
+	id: string,
+	cid: string,
+): Promise<void> {
+	await client.filesMkdir(sitesDir, {parents: true});
+	await client.filesRm(`${sitesDir}/${id}`, {recursive: true, force: true});
+	await client.filesCp(`/ipfs/${cid}`, `${sitesDir}/${id}`);
+}
+
+// ---------------------------------------------------------------------------
+// Small shared Kubo reads (fail-soft where a missing dir is not an error).
+// ---------------------------------------------------------------------------
+
+/** List the entry NAMES under the sites dir; empty on a fresh box (no dir). */
+async function lsSites(
+	client: KuboRpcClient,
+	sitesDir: string,
+): Promise<string[]> {
+	let listing: {Entries?: Array<{Name?: string}> | null};
+	try {
+		listing = await client.filesLs<{Entries?: Array<{Name?: string}> | null}>(
+			sitesDir,
+		);
+	} catch {
+		// No /sites dir yet (fresh box) — nothing to list, not an error.
+		return [];
+	}
+	const names: string[] = [];
+	for (const entry of listing.Entries ?? []) {
+		if (entry?.Name) names.push(entry.Name);
+	}
+	return names;
+}
+
+/** Stat an MFS path for its current CID, or undefined if it cannot be resolved. */
+async function statCid(
+	client: KuboRpcClient,
+	path: string,
+): Promise<string | undefined> {
+	try {
+		const stat = await client.filesStat<{Hash?: string}>(path);
+		return stat?.Hash;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Map site/key name -> IPNS id from `key/list -l` (same shape as node-commands). */
+async function listKeys(client: KuboRpcClient): Promise<Map<string, string>> {
+	const res = await client.keyList<{
+		Keys?: Array<{Name?: string; Id?: string}> | null;
+	}>();
+	const map = new Map<string, string>();
+	for (const k of res.Keys ?? []) {
+		if (k?.Name && k?.Id) map.set(k.Name, k.Id);
+	}
+	return map;
+}