pinnace 0.0.0 → 0.2.0

package/src/rpc/kubo-rpc-client.ts

@@ -0,0 +1,281 @@
+/**
+ * A typed, per-node Kubo RPC client. It wraps `POST {baseUrl}/api/v0/<path>`
+ * with an `Authorization: Bearer <token>` header on EVERY call. No Kubo binary
+ * runs on the client — all interaction is HTTP.
+ *
+ * This is the seam every host-agnostic pinnace operation (deploy, publish,
+ * status, site management) speaks. It is deliberately PER-NODE (one base URL +
+ * one token); multi-target fan-out lives in the deploy task, not here.
+ *
+ * Behaviour ported (not copied) from the reference prototype
+ * `~/searches/ipfs-hetzner/deploy-car.mjs`: the exact query params
+ * (`files/mkdir?arg=/sites&parents=true`, `dag/import?pin-roots=true`, ...) and
+ * the throw-on-`!ok` error handling.
+ */
+
+/** A minimal `fetch`-shaped function, so tests can inject a recording mock. */
+export type FetchLike = (
+	input: string | URL,
+	init?: {method?: string; headers?: Record<string, string>; body?: unknown},
+) => Promise<Response>;
+
+/** Options for constructing a per-node {@link KuboRpcClient}. */
+export interface KuboRpcClientOptions {
+	/** The node's Kubo RPC base URL, e.g. `https://ipfs-api.example.com`. */
+	baseUrl: string;
+	/** The node's bearer token (sent on every call). */
+	token: string;
+	/** Injectable fetch (defaults to the global `fetch`); tests pass the mock. */
+	fetchImpl?: FetchLike;
+}
+
+/**
+ * A loud error carrying the endpoint + HTTP status of a non-2xx Kubo response,
+ * so a caller (and a log) can see exactly which call failed and how.
+ */
+export class KuboRpcError extends Error {
+	constructor(
+		/** The `/api/v0/<endpoint>` path that failed. */
+		readonly endpoint: string,
+		/** The HTTP status returned. */
+		readonly status: number,
+		/** The response body text (for diagnostics). */
+		readonly bodyText: string,
+	) {
+		super(`Kubo RPC ${endpoint} failed: ${status} ${bodyText}`);
+		this.name = 'KuboRpcError';
+	}
+}
+
+/** Flags accepted by `files/mkdir`. */
+export interface FilesMkdirOptions {
+	/** Create parent directories as needed (`parents=true`). */
+	parents?: boolean;
+}
+
+/** Flags accepted by `files/rm`. */
+export interface FilesRmOptions {
+	/** Remove directories recursively (`recursive=true`). */
+	recursive?: boolean;
+	/** Ignore nonexistent files (`force=true`). */
+	force?: boolean;
+}
+
+/** Parameters for `name/publish`. */
+export interface NamePublishOptions {
+	/** The `/ipfs/<cid>` path to publish. */
+	cidPath: string;
+	/** The keystore key name to sign with. */
+	key: string;
+	/** Record lifetime (e.g. `72h`). */
+	lifetime?: string;
+	/** Record TTL (e.g. `1h`). */
+	ttl?: string;
+	/** Publish even with no online peers (`allow-offline=true`). */
+	allowOffline?: boolean;
+}
+
+export class KuboRpcClient {
+	private readonly baseUrl: string;
+	private readonly token: string;
+	private readonly fetchImpl: FetchLike;
+
+	constructor(options: KuboRpcClientOptions) {
+		// Normalise: strip trailing slashes so path joining is unambiguous.
+		this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+		this.token = options.token;
+		this.fetchImpl = options.fetchImpl ?? (globalThis.fetch as FetchLike);
+	}
+
+	/**
+	 * The core request primitive: POST `/api/v0/<endpoint>?<query>` with the
+	 * bearer token. Throws {@link KuboRpcError} on any non-2xx. Returns the raw
+	 * {@link Response} so callers can decode JSON or bytes as they need.
+	 */
+	async request(
+		endpoint: string,
+		query?: URLSearchParams,
+		body?: unknown,
+		extraHeaders?: Record<string, string>,
+	): Promise<Response> {
+		const qs =
+			query && [...query.keys()].length > 0 ? `?${query.toString()}` : '';
+		const url = `${this.baseUrl}/api/v0/${endpoint}${qs}`;
+		const res = await this.fetchImpl(url, {
+			method: 'POST',
+			headers: {authorization: `Bearer ${this.token}`, ...(extraHeaders ?? {})},
+			body,
+		});
+		if (!res.ok) {
+			const text = await safeText(res);
+			throw new KuboRpcError(endpoint, res.status, text);
+		}
+		return res;
+	}
+
+	/** POST an endpoint and parse the JSON response body. */
+	private async requestJson<T = unknown>(
+		endpoint: string,
+		query?: URLSearchParams,
+		body?: unknown,
+		extraHeaders?: Record<string, string>,
+	): Promise<T> {
+		const res = await this.request(endpoint, query, body, extraHeaders);
+		return (await res.json()) as T;
+	}
+
+	/** `id` — the node's identity (PeerID etc.). */
+	id<T = unknown>(): Promise<T> {
+		return this.requestJson<T>('id');
+	}
+
+	/**
+	 * `add` — add raw bytes (returned shape is Kubo-defined). Kubo requires the
+	 * payload as a `multipart/form-data` `file` part, NOT a raw body, so we send
+	 * a {@link FormData} and let `fetch` set the multipart boundary itself (see
+	 * {@link fileUpload}).
+	 */
+	add<T = unknown>(data: Uint8Array): Promise<T> {
+		return this.fileUpload<T>('add', undefined, data);
+	}
+
+	/** `dag/import?pin-roots=true` — import a CAR and pin its roots. */
+	dagImport<T = unknown>(car: Uint8Array): Promise<T> {
+		const q = new URLSearchParams({'pin-roots': 'true'});
+		return this.fileUpload<T>('dag/import', q, car);
+	}
+
+	/**
+	 * `pin/rm?arg=<cid>` — UNPIN content so Kubo can garbage-collect it and
+	 * reclaim storage. The counterpart to `dag/import?pin-roots=true`: removing a
+	 * site unpins its CID here so it stops being served/announced. `arg` takes a
+	 * bare CID (or an `/ipfs/<cid>` path); callers pass the CID from `files/stat`.
+	 */
+	pinRm<T = unknown>(cid: string): Promise<T> {
+		return this.requestJson<T>('pin/rm', new URLSearchParams({arg: cid}));
+	}
+
+	/** `files/mkdir?arg=<path>[&parents=true]`. */
+	async filesMkdir(
+		path: string,
+		options: FilesMkdirOptions = {},
+	): Promise<void> {
+		const q = new URLSearchParams({arg: path});
+		if (options.parents) q.set('parents', 'true');
+		await this.request('files/mkdir', q);
+	}
+
+	/** `files/rm?arg=<path>[&recursive=true][&force=true]`. */
+	async filesRm(path: string, options: FilesRmOptions = {}): Promise<void> {
+		const q = new URLSearchParams({arg: path});
+		if (options.recursive) q.set('recursive', 'true');
+		if (options.force) q.set('force', 'true');
+		await this.request('files/rm', q);
+	}
+
+	/** `files/cp?arg=<from>&arg=<to>`. */
+	async filesCp(from: string, to: string): Promise<void> {
+		const q = new URLSearchParams();
+		q.append('arg', from);
+		q.append('arg', to);
+		await this.request('files/cp', q);
+	}
+
+	/** `files/stat?arg=<path>` — returns the MFS entry stat (Hash, Type, ...). */
+	filesStat<T = unknown>(path: string): Promise<T> {
+		return this.requestJson<T>('files/stat', new URLSearchParams({arg: path}));
+	}
+
+	/** `files/ls?arg=<path>[&l=true]` — list an MFS directory. */
+	filesLs<T = unknown>(path: string, long = true): Promise<T> {
+		const q = new URLSearchParams({arg: path});
+		if (long) q.set('long', 'true');
+		return this.requestJson<T>('files/ls', q);
+	}
+
+	/** `key/list?l=true` — list keystore keys with their IPNS ids. */
+	keyList<T = unknown>(): Promise<T> {
+		return this.requestJson<T>('key/list', new URLSearchParams({l: 'true'}));
+	}
+
+	/** `key/gen?arg=<name>&type=ed25519` — generate a new keystore key. */
+	keyGen<T = unknown>(name: string): Promise<T> {
+		const q = new URLSearchParams({arg: name, type: 'ed25519'});
+		return this.requestJson<T>('key/gen', q);
+	}
+
+	/**
+	 * `key/import?arg=<name>` — import key MATERIAL (libp2p/protobuf bytes) into
+	 * the keystore. The node, not the client, signs records with it.
+	 */
+	keyImport<T = unknown>(name: string, keyBytes: Uint8Array): Promise<T> {
+		const q = new URLSearchParams({arg: name});
+		return this.fileUpload<T>('key/import', q, keyBytes);
+	}
+
+	/**
+	 * Kubo's file-upload endpoints require the payload as a `multipart/form-data`
+	 * body with the bytes as a named file part (confirmed by the Kubo RPC docs'
+	 * `-F <field>=@…` cURL examples and a live daemon). A raw
+	 * `application/octet-stream` body is rejected with
+	 * `400 file argument '<field>' is required`.
+	 *
+	 * The field name is endpoint-specific: `add`, `dag/import` and `key/import`
+	 * expect `file` (the default), while `routing/put` expects `value-file`.
+	 *
+	 * We build a {@link FormData} and pass it as the body WITHOUT a hand-set
+	 * `content-type`: `fetch` serialises the FormData and sets
+	 * `content-type: multipart/form-data; boundary=…` itself. Setting it manually
+	 * would omit/override the boundary and break the request.
+	 */
+	private fileUpload<T = unknown>(
+		endpoint: string,
+		query: URLSearchParams | undefined,
+		bytes: Uint8Array,
+		field = 'file',
+	): Promise<T> {
+		const form = new FormData();
+		form.append(field, new Blob([bytes as BlobPart]), field);
+		return this.requestJson<T>(endpoint, query, form);
+	}
+
+	/** `name/publish?arg=<cidPath>&key=<key>&lifetime=..&ttl=..` — sign+publish IPNS. */
+	namePublish<T = unknown>(options: NamePublishOptions): Promise<T> {
+		const q = new URLSearchParams({arg: options.cidPath, key: options.key});
+		if (options.lifetime) q.set('lifetime', options.lifetime);
+		if (options.ttl) q.set('ttl', options.ttl);
+		if (options.allowOffline) q.set('allow-offline', 'true');
+		return this.requestJson<T>('name/publish', q);
+	}
+
+	/** `routing/get?arg=<ipnsPath>` — fetch the raw signed record for a name. */
+	async routingGet(ipnsPath: string): Promise<Uint8Array> {
+		const res = await this.request(
+			'routing/get',
+			new URLSearchParams({arg: ipnsPath}),
+		);
+		return new Uint8Array(await res.arrayBuffer());
+	}
+
+	/**
+	 * `routing/put?arg=<ipnsPath>` — (re-)announce a signed record body. Kubo's
+	 * `routing/put` takes the record as a `multipart/form-data` file part named
+	 * **`value-file`** (NOT the generic `file` the other upload endpoints use); a
+	 * raw `application/octet-stream` body is rejected with
+	 * `400 file argument 'value-file' is required`. Goes through {@link fileUpload}
+	 * so `fetch` owns the multipart boundary (no hand-set content-type).
+	 */
+	async routingPut(ipnsPath: string, record: Uint8Array): Promise<void> {
+		const q = new URLSearchParams({arg: ipnsPath});
+		await this.fileUpload('routing/put', q, record, 'value-file');
+	}
+}
+
+/** Read a response body as text without throwing (best-effort for errors). */
+async function safeText(res: Response): Promise<string> {
+	try {
+		return await res.text();
+	} catch {
+		return '';
+	}
+}

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);
+}