feat: create type-safe API object for Headscale

app/components/Error.tsx

@@ -1,6 +1,6 @@
 import { AlertCircle } from 'lucide-react';
 import { isRouteErrorResponse, useRouteError } from 'react-router';
-import ResponseError from '~/server/headscale/api-error';
+import ResponseError from '~/server/headscale/api/error';
 import cn from '~/utils/cn';
 import Card from './Card';
 import Code from './Code';

app/entry.server.tsx

@@ -3,7 +3,8 @@ import { createReadableStreamFromReadable } from '@react-router/node';
 import { isbot } from 'isbot';
 import type { RenderToPipeableStreamOptions } from 'react-dom/server';
 import { renderToPipeableStream } from 'react-dom/server';
-import { AppLoadContext, EntryContext, ServerRouter } from 'react-router';
+import type { AppLoadContext, EntryContext } from 'react-router';
+import { ServerRouter } from 'react-router';
 
 export const streamTimeout = 5_000;
 export default function handleRequest(

app/layouts/dashboard.tsx

@@ -2,7 +2,7 @@ import { type LoaderFunctionArgs, Outlet, redirect } from 'react-router';
 import { ErrorPopup } from '~/components/Error';
 import type { LoadContext } from '~/server';
 import { pruneEphemeralNodes } from '~/server/db/pruner';
-import ResponseError from '~/server/headscale/api-error';
+import ResponseError from '~/server/headscale/api/error';
 import log from '~/utils/log';
 
 export async function loader({

app/openapi-operation-hashes.json

@@ -0,0 +1,81 @@
+{
+	"0.26.0": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "ac9ffcd6243a9784",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	},
+	"0.26.1": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "ac9ffcd6243a9784",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	},
+	"0.27.0": {
+		"GET /api/v1/apikey": "efe31b6dc980e158",
+		"POST /api/v1/apikey": "39953a96c1da5312",
+		"POST /api/v1/apikey/expire": "ca56add866802f17",
+		"DELETE /api/v1/apikey/{prefix}": "3f0125f7abe7abb1",
+		"POST /api/v1/debug/node": "204f9ae3f9f738c6",
+		"GET /api/v1/health": "5e447272e72b2e5f",
+		"GET /api/v1/node": "8bb18b8c7cfb4f20",
+		"POST /api/v1/node/backfillips": "6da4d1d3922a8001",
+		"POST /api/v1/node/register": "539f7cb3a84d43d4",
+		"GET /api/v1/node/{nodeId}": "8a7da3d24dc82c37",
+		"DELETE /api/v1/node/{nodeId}": "f832f33d84fd3724",
+		"POST /api/v1/node/{nodeId}/approve_routes": "e6c22e46ad44903d",
+		"POST /api/v1/node/{nodeId}/expire": "ac9ffcd6243a9784",
+		"POST /api/v1/node/{nodeId}/rename/{newName}": "d355388ac934dc90",
+		"POST /api/v1/node/{nodeId}/tags": "b6a8296dcc2939b5",
+		"POST /api/v1/node/{nodeId}/user": "ae3a30b43ffd1922",
+		"GET /api/v1/policy": "d6c639be304cd3c0",
+		"PUT /api/v1/policy": "6cbe80bde771a388",
+		"GET /api/v1/preauthkey": "14db6a04f90d7a7e",
+		"POST /api/v1/preauthkey": "0b4308e049d4eb58",
+		"POST /api/v1/preauthkey/expire": "31f377a66d3a5c4f",
+		"GET /api/v1/user": "228831b58ccc5a17",
+		"POST /api/v1/user": "a4e1d889d7962da5",
+		"DELETE /api/v1/user/{id}": "3d553e4b74296884",
+		"POST /api/v1/user/{oldId}/rename/{newName}": "996c03ebf81576d7"
+	}
+}

app/routes/acls/acl-action.ts

@@ -1,6 +1,6 @@
 import { ActionFunctionArgs, data } from 'react-router';
 import { LoadContext } from '~/server';
-import ResponseError from '~/server/headscale/api-error';
+import ResponseError from '~/server/headscale/api/error';
 import { Capabilities } from '~/server/web/roles';
 import { data400, data403 } from '~/utils/res';
 

app/routes/acls/acl-loader.ts

@@ -1,6 +1,6 @@
 import { LoaderFunctionArgs } from 'react-router';
 import { LoadContext } from '~/server';
-import ResponseError from '~/server/headscale/api-error';
+import ResponseError from '~/server/headscale/api/error';
 import { Capabilities } from '~/server/web/roles';
 import { data403 } from '~/utils/res';
 

app/routes/auth/login/action.ts

@@ -1,6 +1,6 @@
 import { ActionFunctionArgs, data, redirect } from 'react-router';
 import { LoadContext } from '~/server';
-import ResponseError from '~/server/headscale/api-error';
+import ResponseError from '~/server/headscale/api/error';
 import { Key } from '~/types';
 import log from '~/utils/log';
 

app/routes/machines/overview.tsx

@@ -6,7 +6,6 @@ import Link from '~/components/Link';
 import Tooltip from '~/components/Tooltip';
 import type { LoadContext } from '~/server';
 import { Capabilities } from '~/server/web/roles';
-import type { Machine, User } from '~/types';
 import cn from '~/utils/cn';
 import { mapNodes } from '~/utils/node-info';
 import MachineRow from './components/machine-row';
@@ -40,10 +39,8 @@ export async function loader({
 		Capabilities.write_machines,
 	);
 
-	const [{ nodes }, { users }] = await Promise.all([
-		context.client.get<{ nodes: Machine[] }>('v1/node', session.api_key),
-		context.client.get<{ users: User[] }>('v1/user', session.api_key),
-	]);
+	const api = context.hsApi.getRuntimeClient(session.api_key);
+	const [nodes, users] = await Promise.all([api.getNodes(), api.getUsers()]);
 
 	let magic: string | undefined;
 	if (context.hs.readable()) {

app/server/headscale/api-client.ts

@@ -1,9 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { data } from 'react-router';
-import { Agent, Dispatcher, request } from 'undici';
-import { errors } from 'undici';
+import { Agent, Dispatcher, errors, request } from 'undici';
 import log from '~/utils/log';
-import ResponseError from './api-error';
+import ResponseError from './api/error';
 
 function isNodeNetworkError(error: unknown): error is NodeJS.ErrnoException {
 	const keys = Object.keys(error as Record<string, unknown>);

app/server/headscale/api-error.ts

@@ -1,19 +0,0 @@
-// Represents an error that occurred during a response
-// Thrown when status codes are >= 400
-export default class ResponseError extends Error {
-	status: number;
-	response: string;
-	responseObject?: Record<string, unknown>;
-
-	constructor(status: number, response: string) {
-		super(`Response Error (${status}): ${response}`);
-		this.name = 'ResponseError';
-		this.status = status;
-		this.response = response;
-
-		try {
-			// Try to parse the response as JSON to get a response object
-			this.responseObject = JSON.parse(response);
-		} catch {}
-	}
-}

app/server/headscale/api/endpoints/api-keys.ts

@@ -0,0 +1,27 @@
+import type { Key } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface ApiKeyEndpoints {
+	/**
+	 * Retrieves all API keys from the Headscale instance.
+	 *
+	 * @returns An array of `Key` objects representing the API keys.
+	 */
+	getApiKeys(): Promise<Key[]>;
+}
+
+export default defineApiEndpoints<ApiKeyEndpoints>((client, apiKey) => ({
+	getApiKeys: async () => {
+		if (client.isAtleast('0.27.0')) {
+			console.log('wow we are at least 0.27.0!');
+		}
+
+		const { apiKeys } = await client.apiFetch<{ apiKeys: Key[] }>(
+			'GET',
+			'v1/apikey',
+			apiKey,
+		);
+
+		return apiKeys;
+	},
+}));

app/server/headscale/api/endpoints/index.ts

@@ -0,0 +1,48 @@
+import {
+	composeEndpoints,
+	type ExtractApiEndpoints,
+	type UnionToIntersection,
+} from '../factory';
+import type { HeadscaleApiInterface } from '../index';
+import apiKeyEndpoints from './api-keys';
+import nodeEndpoints from './nodes';
+import policyEndpoints from './policy';
+import preAuthKeyEndpoints from './pre-auth-keys';
+import userEndpoints from './users';
+
+/**
+ * A constant list of all endpoint groups.
+ * Add new endpoint groups here.
+ */
+export const endpointSets = [
+	apiKeyEndpoints,
+	nodeEndpoints,
+	policyEndpoints,
+	preAuthKeyEndpoints,
+	userEndpoints,
+] as const;
+
+/**
+ * All of the available API methods when interacting with Headscale's API.
+ * We have wrapped each operation with nice methods and parameters to make it
+ * easier to do integration testing by spinning up an actual Headscale instance
+ * and calling these methods against it.
+ *
+ * We also have the benefit of supporting multiple Headscale versions by
+ * passing in different internal implementations based on the OpenAPI spec.
+ */
+export type RuntimeApiClient = UnionToIntersection<
+	ExtractApiEndpoints<(typeof endpointSets)[number]>
+>;
+
+/**
+ * Composes all endpoint groups into a single runtime API client.
+ *
+ * @param client - The client helpers for making API requests.
+ * @param apiKey - The API key for authentication.
+ * @returns A fully composed runtime API client.
+ */
+export default (
+	client: HeadscaleApiInterface['clientHelpers'],
+	apiKey: string,
+) => composeEndpoints(endpointSets, client, apiKey);

app/server/headscale/api/endpoints/nodes.ts

@@ -0,0 +1,150 @@
+import type { Machine } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface NodeEndpoints {
+	/**
+	 * Retrieves all nodes (machines) from the Headscale instance.
+	 *
+	 * @returns An array of `Machine` objects representing the nodes.
+	 */
+	getNodes(): Promise<Machine[]>;
+
+	/**
+	 * Retrieves a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to retrieve.
+	 * @returns A `Machine` object representing the node.
+	 */
+	getNode(id: string): Promise<Machine>;
+
+	/**
+	 * Deletes a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to delete.
+	 */
+	deleteNode(id: string): Promise<void>;
+
+	/**
+	 * Registers a new node (machine) with the given user and key.
+	 *
+	 * @param user The user to associate with the node.
+	 * @param key The registration key for the node.
+	 * @returns A `Machine` object representing the newly registered node.
+	 */
+	registerNode(user: string, key: string): Promise<Machine>;
+
+	/**
+	 * Approves routes for a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node.
+	 * @param routes An array of routes to approve for the node.
+	 */
+	approveNodeRoutes(id: string, routes: string[]): Promise<void>;
+
+	/**
+	 * Expires a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to expire.
+	 */
+	expireNode(id: string): Promise<void>;
+
+	/**
+	 * Renames a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node to rename.
+	 * @param newName The new name for the node.
+	 */
+	renameNode(id: string, newName: string): Promise<void>;
+
+	/**
+	 * Sets tags for a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node.
+	 * @param tags An array of tags to set for the node.
+	 */
+	setNodeTags(id: string, tags: string[]): Promise<void>;
+
+	/**
+	 * Sets the user for a specific node (machine) by its ID.
+	 *
+	 * @param id The ID of the node.
+	 * @param user The user to set for the node.
+	 */
+	setNodeUser(id: string, user: string): Promise<void>;
+}
+
+export default defineApiEndpoints<NodeEndpoints>((client, apiKey) => ({
+	getNodes: async () => {
+		const { nodes } = await client.apiFetch<{ nodes: Machine[] }>(
+			'GET',
+			'v1/node',
+			apiKey,
+		);
+
+		return nodes;
+	},
+
+	getNode: async (nodeId) => {
+		const { node } = await client.apiFetch<{ node: Machine }>(
+			'GET',
+			`v1/node/${nodeId}`,
+			apiKey,
+		);
+
+		return node;
+	},
+
+	deleteNode: async (nodeId) => {
+		await client.apiFetch<void>('DELETE', `v1/node/${nodeId}`, apiKey);
+	},
+
+	registerNode: async (user, key) => {
+		const qp = new URLSearchParams();
+		qp.append('user', user);
+		qp.append('key', key);
+		const { node } = await client.apiFetch<{ node: Machine }>(
+			'POST',
+			`v1/node/register?${qp.toString()}`,
+			apiKey,
+			{
+				user,
+				key,
+			},
+		);
+
+		return node;
+	},
+
+	approveNodeRoutes: async (nodeId, routes) => {
+		await client.apiFetch<void>(
+			'POST',
+			`v1/node/${nodeId}/approve_routes`,
+			apiKey,
+			{ routes },
+		);
+	},
+
+	expireNode: async (nodeId) => {
+		await client.apiFetch<void>('POST', `v1/node/${nodeId}/expire`, apiKey);
+	},
+
+	renameNode: async (nodeId, newName) => {
+		await client.apiFetch<void>(
+			'POST',
+			`v1/node/${nodeId}/rename/${newName}`,
+			apiKey,
+		);
+	},
+
+	setNodeTags: async (nodeId, tags) => {
+		await client.apiFetch<void>('POST', `v1/node/${nodeId}/tags`, apiKey, {
+			tags,
+		});
+	},
+
+	setNodeUser: async (nodeId, user) => {
+		await client.apiFetch<void>('POST', `v1/node/${nodeId}/user`, apiKey, {
+			user,
+		});
+	},
+}));

app/server/headscale/api/endpoints/policy.ts

@@ -0,0 +1,41 @@
+import { defineApiEndpoints } from '../factory';
+
+export interface PolicyEndpoints {
+	/**
+	 * Retrieves the current ACL policy from the Headscale instance.
+	 *
+	 * @returns The ACL policy as a string.
+	 */
+	getPolicy(): Promise<string>;
+
+	/**
+	 * Sets the ACL policy for the Headscale instance.
+	 *
+	 * @param policy The ACL policy as a string.
+	 * @returns The expiration date of the new policy.
+	 */
+	setPolicy(policy: string): Promise<Date>;
+}
+
+export default defineApiEndpoints<PolicyEndpoints>((client, apiKey) => ({
+	getPolicy: async () => {
+		const { policy } = await client.apiFetch<{ policy: string }>(
+			'GET',
+			'v1/policy',
+			apiKey,
+		);
+
+		return policy;
+	},
+
+	setPolicy: async (policy) => {
+		const { updatedAt } = await client.apiFetch<{ updatedAt: string }>(
+			'PUT',
+			'v1/policy',
+			apiKey,
+			{ policy },
+		);
+
+		return new Date(updatedAt);
+	},
+}));

app/server/headscale/api/endpoints/pre-auth-keys.ts

@@ -0,0 +1,69 @@
+import type { PreAuthKey } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface PreAuthKeyEndpoints {
+	/**
+	 * Retrieves all pre-authentication keys for a specific user.
+	 *
+	 * @param user The user to retrieve pre-authentication keys for.
+	 * @returns An array of `PreAuthKey` objects representing the pre-authentication keys.
+	 */
+	getPreAuthKeys(user: string): Promise<PreAuthKey[]>;
+
+	/**
+	 * Creates a new pre-authentication key for a specific user.
+	 *
+	 * @param user The user to create the pre-authentication key for.
+	 * @param ephemeral Whether the key is ephemeral.
+	 * @param uses The number of uses for the key.
+	 * @param expiration The expiration date of the key, or `null` for no expiration.
+	 * @param aclTags An array of ACL tags to associate with the key, or `null` for none.
+	 * @returns A `PreAuthKey` object representing the newly created pre-authentication key.
+	 */
+	createPreAuthKey(
+		user: string,
+		ephemeral: boolean,
+		uses: number,
+		expiration: Date | null,
+		aclTags: string[] | null,
+	): Promise<PreAuthKey>;
+
+	/**
+	 * Expires a specific pre-authentication key for a user.
+	 *
+	 * @param user The user associated with the pre-authentication key.
+	 * @param key The pre-authentication key to expire.
+	 */
+	expirePreAuthKey(user: string, key: string): Promise<void>;
+}
+
+export default defineApiEndpoints<PreAuthKeyEndpoints>((client, apiKey) => ({
+	getPreAuthKeys: async (user) => {
+		const { preAuthKeys } = await client.apiFetch<{
+			preAuthKeys: PreAuthKey[];
+		}>('GET', 'v1/preauthkey', apiKey, { user });
+
+		return preAuthKeys;
+	},
+
+	createPreAuthKey: async (user, ephemeral, uses, expiration, aclTags) => {
+		const { preAuthKey } = await client.apiFetch<{
+			preAuthKey: PreAuthKey;
+		}>('POST', 'v1/preauthkey', apiKey, {
+			user,
+			ephemeral,
+			uses,
+			expiration: expiration ? expiration.toISOString() : null,
+			aclTags,
+		});
+
+		return preAuthKey;
+	},
+
+	expirePreAuthKey: async (user, key) => {
+		await client.apiFetch<void>('POST', 'v1/preauthkey/expire', apiKey, {
+			user,
+			key,
+		});
+	},
+}));

app/server/headscale/api/endpoints/users.ts

@@ -0,0 +1,88 @@
+import type { User } from '~/types';
+import { defineApiEndpoints } from '../factory';
+
+export interface UserEndpoints {
+	/**
+	 * Retrieves users from the Headscale instance, optionally filtering by ID, name, or email.
+	 *
+	 * @param id Optional ID of the user to retrieve.
+	 * @param name Optional name of the user to retrieve.
+	 * @param email Optional email of the user to retrieve.
+	 * @returns An array of `User` objects representing the users.
+	 */
+	getUsers(id?: string, name?: string, email?: string): Promise<User[]>;
+
+	/**
+	 * Creates a new user in the Headscale instance.
+	 *
+	 * @param username The username of the new user.
+	 * @param email Optional email of the new user.
+	 * @param displayName Optional display name of the new user.
+	 * @param pictureUrl Optional picture URL of the new user.
+	 * @returns A `User` object representing the newly created user.
+	 */
+	createUser(
+		username: string,
+		email?: string,
+		displayName?: string,
+		pictureUrl?: string,
+	): Promise<User>;
+
+	/**
+	 * Deletes a specific user by its ID.
+	 *
+	 * @param id The ID of the user to delete.
+	 */
+	deleteUser(id: string): Promise<void>;
+
+	/**
+	 * Renames a specific user by its ID.
+	 *
+	 * @param id The ID of the user to rename.
+	 * @param newName The new name for the user.
+	 */
+	renameUser(id: string, newName: string): Promise<void>;
+}
+
+export default defineApiEndpoints<UserEndpoints>((client, apiKey) => ({
+	getUsers: async (id, name, email) => {
+		const moreThanOneFilter =
+			[id, name, email].filter((v) => v !== undefined).length > 1;
+
+		if (moreThanOneFilter) {
+			throw new Error('Only one of id, name, or email filters can be provided');
+		}
+
+		const { users } = await client.apiFetch<{ users: User[] }>(
+			'GET',
+			'v1/user',
+			apiKey,
+			{ id, name, email },
+		);
+
+		return users;
+	},
+
+	createUser: async (username, email, displayName, pictureUrl) => {
+		const { user } = await client.apiFetch<{ user: User }>(
+			'POST',
+			'v1/user',
+			apiKey,
+			{ name: username, email, displayName, pictureUrl },
+		);
+
+		return user;
+	},
+
+	deleteUser: async (id) => {
+		await client.apiFetch<void>('DELETE', `v1/user/${id}`, apiKey);
+	},
+
+	renameUser: async (oldId, newName) => {
+		await client.apiFetch<void>(
+			'POST',
+			`v1/user/${oldId}/rename/${newName}`,
+			apiKey,
+		);
+	},
+}));

app/server/headscale/api/error.ts

@@ -0,0 +1,143 @@
+import { data } from 'react-router';
+import { errors } from 'undici';
+
+// Represents an error that occurred during a response
+// Thrown when status codes are >= 400
+export default class ResponseError extends Error {
+	status: number;
+	response: string;
+	responseObject?: Record<string, unknown>;
+
+	constructor(status: number, response: string, requestUrl: string) {
+		super(`${requestUrl}: status ${status} - ${response}`);
+		this.name = 'ResponseError';
+		this.status = status;
+		this.response = response;
+
+		try {
+			// Try to parse the response as JSON to get a response object
+			this.responseObject = JSON.parse(response);
+		} catch {}
+	}
+}
+
+function isNodeNetworkError(error: unknown): error is NodeJS.ErrnoException {
+	if (typeof error !== 'object' || error === null) {
+		return false;
+	}
+
+	const keys = Object.keys(error as Record<string, unknown>);
+	return keys.includes('code') && keys.includes('errno');
+}
+
+export function friendlyError(givenError: unknown) {
+	let error: unknown = givenError;
+	if (error instanceof AggregateError) {
+		error = error.errors[0];
+	}
+
+	switch (true) {
+		case error instanceof errors.BodyTimeoutError:
+		case error instanceof errors.ConnectTimeoutError:
+		case error instanceof errors.HeadersTimeoutError:
+			return data('Timed out waiting for a response from the Headscale API', {
+				statusText: 'Request Timeout',
+				status: 408,
+			});
+
+		case error instanceof errors.SocketError:
+		case error instanceof errors.SecureProxyConnectionError:
+		case error instanceof errors.ClientClosedError:
+		case error instanceof errors.ClientDestroyedError:
+		case error instanceof errors.RequestAbortedError:
+			return data('The Headscale API is not reachable', {
+				statusText: 'Service Unavailable',
+				status: 503,
+			});
+
+		case error instanceof errors.InvalidArgumentError:
+		case error instanceof errors.InvalidReturnValueError:
+		case error instanceof errors.NotSupportedError:
+			return data('Unable to make a request (this is most likely a bug)', {
+				statusText: 'Internal Server Error',
+				status: 500,
+			});
+
+		case error instanceof errors.HeadersOverflowError:
+		case error instanceof errors.RequestContentLengthMismatchError:
+		case error instanceof errors.ResponseContentLengthMismatchError:
+		case error instanceof errors.ResponseExceededMaxSizeError:
+			return data('The Headscale API returned a malformed response', {
+				statusText: 'Bad Gateway',
+				status: 502,
+			});
+
+		case isNodeNetworkError(error):
+			if (error.code === 'ECONNREFUSED') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			if (error.code === 'ENOTFOUND') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			if (error.code === 'EAI_AGAIN') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			if (error.code === 'ETIMEDOUT') {
+				return data('Timed out waiting for a response from the Headscale API', {
+					statusText: 'Request Timeout',
+					status: 408,
+				});
+			}
+
+			if (error.code === 'ECONNRESET') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			if (error.code === 'EPIPE') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			if (error.code === 'ENETUNREACH') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			if (error.code === 'ENETRESET') {
+				return data('The Headscale API is not reachable', {
+					statusText: 'Service Unavailable',
+					status: 503,
+				});
+			}
+
+			return data('The Headscale API is not reachable', {
+				statusText: 'Service Unavailable',
+				status: 503,
+			});
+
+		default:
+			return data((error as Error).message ?? 'An unknown error occurred', {
+				statusText: 'Internal Server Error',
+				status: 500,
+			});
+	}
+}

app/server/headscale/api/factory.ts

@@ -0,0 +1,45 @@
+import { HeadscaleApiInterface } from '../api';
+
+/**
+ * Creates a strongly-typed group factory for a given endpoint interface.
+ *
+ * Example:
+ *   export const apiKeyGroup = defineGroup<ApiKeyEndpoints>({...})
+ */
+
+export interface EndpointFactory<T extends object> {
+	__type?: T;
+	(client: HeadscaleApiInterface['clientHelpers'], apiKey: string): T;
+}
+
+export function defineApiEndpoints<T extends object>(
+	factories: (
+		client: HeadscaleApiInterface['clientHelpers'],
+		apiKey: string,
+	) => T,
+): EndpointFactory<T> {
+	return factories;
+}
+
+export type ExtractApiEndpoints<F> = F extends EndpointFactory<infer T>
+	? T
+	: never;
+export type UnionToIntersection<U> = (
+	U extends any
+		? (k: U) => void
+		: never
+) extends (k: infer I) => void
+	? I
+	: never;
+
+/**
+ * Compose multiple endpoint sets into a single typed runtime client
+ */
+export function composeEndpoints<T extends readonly EndpointFactory<any>[]>(
+	factories: T,
+	clientHelpers: any,
+	apiKey: string,
+): UnionToIntersection<ExtractApiEndpoints<T[number]>> {
+	const instances = factories.map((f) => f(clientHelpers, apiKey));
+	return Object.assign({}, ...instances) as any;
+}

app/server/headscale/api/hasher.ts

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import { dereference } from '@readme/openapi-parser';
+import { OpenAPIV2 } from 'openapi-types';
+
+/**
+ * A map of operation IDs to their hashes.
+ */
+export interface DocumentHash {
+	[operationId: string]: string;
+}
+
+/**
+ * Given an OpenAPI v2 document, generate a map of operations with hashes.
+ * This gives us deterministic identifers to determine the version of Headscale
+ * that is being used at runtime.
+ *
+ * @param doc The OpenAPI v2 document to hash.
+ * @returns A map of operation IDs to their hashes.
+ */
+export async function hashOpenApiDocument(
+	doc: OpenAPIV2.Document,
+): Promise<DocumentHash> {
+	const spec = await dereference(doc);
+	const hashes: DocumentHash = {};
+	const seen = new Set<string>();
+
+	for (const [path, item] of Object.entries(spec.paths)) {
+		for (const [method, operation] of Object.entries(item)) {
+			if (typeof operation !== 'object') {
+				continue;
+			}
+
+			const { parameters, responses } = operation as OpenAPIV2.OperationObject;
+			const raw = JSON.stringify(
+				{
+					path,
+					method: method.toUpperCase(),
+					parameters,
+					responses,
+				},
+				Object.keys({ path, method, parameters, responses }).sort(),
+			);
+
+			const hash = createHash('md5').update(raw).digest('hex').slice(0, 16);
+			const final = seen.has(hash) ? `${hash}_${seen.size}` : hash;
+			seen.add(final);
+			hashes[`${method.toUpperCase()} ${path}`] = final;
+		}
+	}
+
+	return hashes;
+}

app/server/headscale/api/index.ts

@@ -0,0 +1,317 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { dereference } from '@readme/openapi-parser';
+import type { OpenAPIV2 } from 'openapi-types';
+import { Agent, type Dispatcher, request } from 'undici';
+import type { Key, Machine, PreAuthKey, User } from '~/types';
+import log from '~/utils/log';
+import endpointSets, { RuntimeApiClient } from './endpoints';
+import ResponseError, { friendlyError } from './error';
+import { detectApiVersion, isAtLeast, type Version } from './version';
+
+export type RuntimeApiClient2 = {};
+
+/**
+ * A low-level composed interface for interacting with the Headscale API.
+ * This interface provides direct access to the underlying Undici agent
+ * and methods for making API requests.
+ *
+ * It is also responsible for handling OpenAPI spec polling and hashing to
+ * determine the implementations of API methods when requested for use.
+ */
+export interface HeadscaleApiInterface {
+	/**
+	 * The underlying Undici agent used for making requests.
+	 */
+	undiciAgent: Agent;
+
+	/**
+	 * The base URL of the Headscale API.
+	 */
+	baseUrl: string;
+
+	/**
+	 * The OpenAPI hashes retrieved from the Headscale instance at runtime.
+	 * This is used to determine which implementations of API methods to use.
+	 */
+	openapiHashes: Record<string, string> | null;
+
+	/**
+	 * The detected API version of the connected Headscale instance.
+	 */
+	apiVersion: Version;
+
+	/**
+	 * Retrieves a runtime API client for the given API key.
+	 *
+	 * @param apiKey The API key to use for authentication.
+	 * @returns A `RuntimeApiClient` instance for interacting with the API.
+	 */
+	getRuntimeClient(apiKey: string): RuntimeApiClient;
+
+	/**
+	 * A set of helper methods made available to API method implementations.
+	 * The idea is to make interacting with the API easier by providing
+	 * common functionality that can be reused across multiple methods.
+	 */
+	clientHelpers: {
+		/**
+		 * Checks if the connected Headscale instance's API version
+		 * is at least the specified version.
+		 *
+		 * @param version The version to check against.
+		 * @returns `true` if the API version is at least the specified version, `false` otherwise.
+		 */
+		isAtleast(version: Version): boolean;
+
+		/**
+		 * Makes a raw fetch request to the Headscale API via the Undici agent.
+		 * This method is used internally by API method implementations
+		 * to make requests to the Headscale API.
+		 *
+		 * @param path The API path to request.
+		 * @param options Optional request options.
+		 * @returns A promise that resolves to the response data.
+		 */
+		rawFetch(
+			path: string,
+			options?: Partial<Dispatcher.RequestOptions>,
+		): Promise<Dispatcher.ResponseData>;
+
+		/**
+		 * Makes a typed API fetch request to the Headscale API.
+		 * This method is used internally by API method implementations
+		 * to make requests to the Headscale API and parse the response.
+		 *
+		 * @param method The HTTP method to use.
+		 * @param apiPath The API path to request.
+		 * @param apiKey The API key to use for authentication.
+		 * @param bodyOrQuery Optional body or query parameters.
+		 * @returns A promise that resolves to the typed response data.
+		 */
+		apiFetch<T>(
+			method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+			apiPath: `v1/${string}`,
+			apiKey: string,
+			bodyOrQuery?: Record<string, unknown>,
+		): Promise<T>;
+	};
+}
+
+/**
+ * Creates a new Headscale API client interface.
+ *
+ * @param baseUrl The base URL of the Headscale API.
+ * @param certPath Optional path to a custom TLS certificate for secure connections.
+ * @returns A promise that resolves to a `HeadscaleApiClient` instance.
+ */
+export async function createHeadscaleInterface(
+	baseUrl: string,
+	certPath?: string,
+): Promise<HeadscaleApiInterface> {
+	const undiciAgent = await createUndiciAgent(certPath);
+	let openapiHashes: Record<string, string> | null = null;
+	let apiVersion: Version;
+
+	const rawFetch = async (
+		url: string,
+		options?: Partial<Dispatcher.RequestOptions>,
+	): Promise<Dispatcher.ResponseData> => {
+		const method = options?.method ?? 'GET';
+		log.debug('api', '%s %s', method, url);
+
+		try {
+			const res = await request(new URL(url, baseUrl), {
+				dispatcher: undiciAgent,
+				headers: {
+					...options?.headers,
+					Accept: 'application/json',
+					'User-Agent': `Headplane/${__VERSION__}`,
+				},
+
+				body: options?.body,
+				method,
+			});
+
+			return res;
+		} catch (error) {
+			throw friendlyError(error);
+		}
+	};
+
+	const apiFetch = async <T>(
+		method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+		apiPath: `v1/${string}`,
+		apiKey: string,
+		bodyOrQuery?: Record<string, unknown>,
+	): Promise<T> => {
+		let url = `/api/${apiPath}`;
+		const options: Partial<Dispatcher.RequestOptions> = {
+			method: method,
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+			},
+		};
+
+		if (bodyOrQuery) {
+			if (method === 'GET' || method === 'DELETE') {
+				// Filter out undefined values
+
+				const params = new URLSearchParams();
+				for (const [key, value] of Object.entries(bodyOrQuery)) {
+					if (value !== undefined) {
+						params.append(key, String(value));
+					}
+				}
+
+				if ([...params.keys()].length > 0) {
+					url += `?${params.toString()}`;
+				}
+			} else {
+				options.body = JSON.stringify(bodyOrQuery);
+				options.headers = {
+					...options.headers,
+					'Content-Type': 'application/json',
+				};
+			}
+		}
+
+		const res = await rawFetch(url, options);
+		if (res.statusCode >= 400) {
+			log.debug(
+				'api',
+				'%s %s failed with status %d',
+				method,
+				apiPath,
+				res.statusCode,
+			);
+			throw new ResponseError(
+				res.statusCode,
+				await res.body.text(),
+				`${method} ${apiPath}`,
+			);
+		}
+
+		return res.body.json() as Promise<T>;
+	};
+
+	/**
+	 * Polls the OpenAPI spec endpoint and generates operation hashes.
+	 * This is used to determine which implementations of API methods to use.
+	 *
+	 * @returns A promise that resolves to the OpenAPI operation hashes.
+	 */
+	async function fetchAndHashOpenapi(): Promise<Record<string, string> | null> {
+		try {
+			const res = await rawFetch('/swagger/v1/openapiv2.json');
+			if (res.statusCode !== 200) {
+				log.error('api', 'Failed to fetch OpenAPI spec: %d', res.statusCode);
+				return null;
+			}
+
+			const body = await res.body.json();
+			const spec = await dereference(body as OpenAPIV2.Document);
+			const hashes = generateSpecHashes(spec);
+			log.debug(
+				'api',
+				'OpenAPI hashes updated (%d endpoints)',
+				Object.keys(hashes).length,
+			);
+			return hashes;
+		} catch (err) {
+			log.warn('api', 'Error during OpenAPI polling: %o', err);
+			return null;
+		}
+	}
+
+	const isAtleast = (version: Version): boolean => {
+		return isAtLeast(apiVersion, version);
+	};
+
+	openapiHashes = await fetchAndHashOpenapi();
+	apiVersion = detectApiVersion(openapiHashes);
+
+	setInterval(async () => {
+		const hashes = await fetchAndHashOpenapi();
+		if (hashes) {
+			openapiHashes = hashes;
+			apiVersion = detectApiVersion(openapiHashes);
+		}
+	}, 60_000); // every 60 seconds
+
+	return {
+		undiciAgent,
+		baseUrl,
+		openapiHashes,
+		apiVersion,
+		getRuntimeClient: (apiKey: string) =>
+			endpointSets(
+				{
+					rawFetch,
+					apiFetch,
+					isAtleast,
+				},
+				apiKey,
+			),
+		clientHelpers: {
+			rawFetch,
+			apiFetch,
+			isAtleast,
+		},
+	};
+}
+
+/**
+ * Creates a new Undici agent for making HTTP requests.
+ *
+ * @param certPath Optional path to a custom TLS certificate for secure connections.
+ * @returns A promise that resolves to an `Agent` instance.
+ */
+async function createUndiciAgent(certPath?: string): Promise<Agent> {
+	if (!certPath) {
+		return new Agent();
+	}
+
+	try {
+		log.debug('config', 'Loading certificate from %s', certPath);
+		const data = await readFile(certPath, 'utf8');
+
+		log.info('config', 'Using certificate from %s', certPath);
+		return new Agent({ connect: { ca: data.trim() } });
+	} catch (error) {
+		log.error('config', 'Failed to load Headscale TLS cert: %s', error);
+		log.debug('config', 'Error Details: %o', error);
+		return new Agent();
+	}
+}
+
+function generateSpecHashes(spec: OpenAPIV2.Document) {
+	const hashes: Record<string, string> = {};
+	const seen = new Set<string>();
+
+	for (const [path, item] of Object.entries(spec.paths)) {
+		for (const [method, operation] of Object.entries(item)) {
+			if (typeof operation !== 'object') {
+				continue;
+			}
+
+			const { parameters, responses } = operation as OpenAPIV2.OperationObject;
+			const raw = JSON.stringify(
+				{
+					path,
+					method: method.toUpperCase(),
+					parameters,
+					responses,
+				},
+				Object.keys({ path, method, parameters, responses }).sort(),
+			);
+
+			const hash = createHash('md5').update(raw).digest('hex').slice(0, 16);
+			const final = seen.has(hash) ? `${hash}_${seen.size}` : hash;
+			seen.add(final);
+			hashes[`${method.toUpperCase()} ${path}`] = final;
+		}
+	}
+
+	return hashes;
+}

app/server/headscale/api/version.ts

@@ -0,0 +1,79 @@
+import hashes from '~/openapi-operation-hashes.json';
+import log from '~/utils/log';
+
+/**
+ * The known API versions based on operation hashes.
+ */
+export type Version = keyof typeof hashes;
+const VERSIONS = Object.keys(hashes) as Version[];
+
+/**
+ * Detects the closest matching API version using operation hashes.
+ * Falls back to the latest known version and emits a warning if unknown.
+ *
+ * @param observed - A mapping of operation identifiers to their hashes.
+ * @returns The detected API version.
+ */
+export function detectApiVersion(
+	observed: Record<string, string> | null,
+): Version {
+	if (!observed) {
+		const latest = VERSIONS.at(-1)!;
+		log.warn(
+			'api',
+			'No operation hashes observed, defaulting to version %s',
+			latest,
+		);
+		return latest;
+	}
+
+	let bestVersion: Version | null = null;
+	let bestScore = -1;
+
+	for (const [version, known] of Object.entries(hashes) as [
+		Version,
+		Record<string, string>,
+	][]) {
+		let score = 0;
+		for (const [op, hash] of Object.entries(observed)) {
+			if (known[op] === hash) score++;
+		}
+		if (score > bestScore) {
+			bestVersion = version;
+			bestScore = score;
+		}
+	}
+
+	if (!bestVersion || bestScore === 0) {
+		const latest = VERSIONS.at(-1)!;
+		log.warn(
+			'api',
+			'Could not determine API version, defaulting to %s',
+			latest,
+		);
+		return latest;
+	}
+
+	if (bestScore < Object.keys(observed).length) {
+		log.warn(
+			'api',
+			'Partial version match: %d/%d endpoints for version %s',
+			bestScore,
+			Object.keys(observed).length,
+			bestVersion,
+		);
+	}
+
+	return bestVersion;
+}
+
+/**
+ * Checks if the current version is at least the baseline version.
+ *
+ * @param current - The current API version.
+ * @param baseline - The baseline API version to compare against.
+ * @returns True if current is at least baseline, false otherwise.
+ */
+export function isAtLeast(current: Version, baseline: Version) {
+	return VERSIONS.indexOf(current) >= VERSIONS.indexOf(baseline);
+}

app/server/index.ts

@@ -6,6 +6,7 @@ import { configureConfig, configureLogger, envVariables } from './config/env';
 import { loadIntegration } from './config/integration';
 import { loadConfig } from './config/loader';
 import { createDbClient } from './db/client.server';
+import { createHeadscaleInterface } from './headscale/api';
 import { createApiClient } from './headscale/api-client';
 import { loadHeadscaleConfig } from './headscale/config-loader';
 import { createHeadplaneAgent } from './hp-agent';
@@ -67,6 +68,11 @@ const appLoadContext = {
 		},
 	}),
 
+	hsApi: await createHeadscaleInterface(
+		config.headscale.url,
+		config.headscale.tls_cert_path,
+	),
+
 	client: await createApiClient(
 		config.headscale.url,
 		config.headscale.tls_cert_path,