feat: initial server side systems

app/server/README.md

@@ -0,0 +1,19 @@
+# Headplane Server
+This code is responsible for all code that is necessary *before* any
+web server is started. It is the only part of the code that contains
+many side-effects (in this case, importing a module may run code).
+
+# Hierarchy
+```
+server
+├── index.ts: Loads everything and starts the web server.
+├── config/
+│   ├── env.ts: Checks the environment variables for custom overrides.
+│   ├── loader.ts: Checks the configuration file and coalesces with ENV.
+│   ├── schema.ts: Defines the schema for the Headplane configuration.
+├── headscale/
+│   ├── api-client.ts: Creates the HTTP client that talks to the Headscale API.
+│   ├── config.ts: Loads the Headscale configuration (if available).
+├── web/
+│   ├── oidc.ts: Loads and validates an OIDC configuration (if available).
+│   ├── sessions.ts: Initializes the session store and methods to manage it.

app/server/config/env.ts

@@ -0,0 +1,64 @@
+import { exit } from 'node:process';
+import { type } from 'arktype';
+import log from '~/utils/log';
+
+// Custom type for boolean environment variables, allowing for values like
+// 1, true, yes, and on to count as a truthy value.
+const booleanEnv = type('string | undefined').pipe((v) => {
+	return ['1', 'true', 'yes', 'on'].includes(v?.toLowerCase() ?? '');
+});
+
+export const envVariables = {
+	debugLog: 'HEADPLANE_DEBUG_LOG',
+	envOverrides: 'HEADPLANE_LOAD_ENV_OVERRIDES',
+	configPath: 'HEADPLANE_CONFIG_PATH',
+} as const;
+
+export function configureLogger(env: string | undefined) {
+	const result = booleanEnv(env);
+	if (result instanceof type.errors) {
+		log.error(
+			'config',
+			'HEADPLANE_DEBUG_LOG value is invalid: %s',
+			result.summary,
+		);
+		log.info('config', 'Using a default value: false');
+		log.debug = () => {}; // Disable debug logging if the value is invalid
+		log.debugEnabled = false;
+		return;
+	}
+
+	if (result === false) {
+		log.debug = () => {}; // Disable debug logging if the value is false
+		log.debugEnabled = false;
+		return;
+	}
+
+	log.debug('config', 'Debug logging has been enabled');
+	log.debug('config', 'It is recommended this be disabled in production');
+}
+
+interface Overrides {
+	loadEnv: string | undefined;
+	path: string | undefined;
+}
+
+export type EnvOverrides = typeof schema.infer;
+const schema = type({
+	loadEnv: booleanEnv.default('false'),
+	path: 'string = "/etc/headplane/config.yaml"',
+});
+
+export function configureConfig(overrides: Overrides) {
+	const result = schema(overrides);
+	if (result instanceof type.errors) {
+		log.error(
+			'config',
+			'HEADPLANE_LOAD_ENV_OVERRIDES or HEADPLANE_CONFIG_PATH value is invalid: %s',
+			result.summary,
+		);
+		exit(1);
+	}
+
+	return result;
+}

app/server/config/loader.ts

@@ -0,0 +1,225 @@
+import { constants, access, readFile } from 'node:fs/promises';
+import { env, exit } from 'node:process';
+import { type } from 'arktype';
+import dotenv, { configDotenv } from 'dotenv';
+import { parseDocument } from 'yaml';
+import log from '~/utils/log';
+import { EnvOverrides, envVariables } from './env';
+import {
+	HeadplaneConfig,
+	headplaneConfig,
+	partialHeadplaneConfig,
+} from './schema';
+
+// loadConfig is a has a lifetime of the entire application and is
+// used to load the configuration for Headplane. It is called once.
+//
+// TODO: Potential for file watching on the configuration
+// But this may not be necessary as a use-case anyways
+export async function loadConfig({ loadEnv, path }: EnvOverrides) {
+	log.debug('config', 'Loading configuration file: %', path);
+	const valid = await validateConfigPath(path);
+	if (!valid) {
+		exit(1);
+	}
+
+	const data = await loadConfigFile(path);
+	if (!data) {
+		exit(1);
+	}
+
+	let config = validateConfig({ ...data, debug: log.debugEnabled });
+	if (!config) {
+		exit(1);
+	}
+
+	if (!loadEnv) {
+		log.debug('config', 'Environment variable overrides are disabled');
+		log.debug('config', 'This also disables the loading of a .env file');
+		return config;
+	}
+
+	log.info('config', 'Loading a .env file (if available)');
+	configDotenv({ override: true });
+	config = coalesceEnv(config);
+	if (!config) {
+		exit(1);
+	}
+
+	return config;
+}
+
+export async function hp_loadConfig() {
+	// 	// OIDC Related Checks
+	// 	if (config.oidc) {
+	// 		if (!config.oidc.client_secret && !config.oidc.client_secret_path) {
+	// 			log.error('CFGX', 'OIDC configuration is missing a secret, disabling');
+	// 			log.error(
+	// 				'CFGX',
+	// 				'Please specify either `oidc.client_secret` or `oidc.client_secret_path`',
+	// 			);
+	// 		}
+	// 		if (config.oidc?.strict_validation) {
+	// 			const result = await testOidc(config.oidc);
+	// 			if (!result) {
+	// 				log.error('CFGX', 'OIDC configuration failed validation, disabling');
+	// 			}
+	// 		}
+	// 	}
+}
+
+async function validateConfigPath(path: string) {
+	try {
+		await access(path, constants.F_OK | constants.R_OK);
+		log.info('config', 'Found a valid configuration file at %s', path);
+		return true;
+	} catch (error) {
+		log.error('config', 'Unable to read a configuration file at %s', path);
+		log.error('config', '%s', error);
+		return false;
+	}
+}
+
+async function loadConfigFile(path: string): Promise<unknown> {
+	log.debug('config', 'Reading configuration file at %s', path);
+	try {
+		const data = await readFile(path, 'utf8');
+		const configYaml = parseDocument(data);
+		if (configYaml.errors.length > 0) {
+			log.error('config', 'Cannot parse configuration file at %s', path);
+			for (const error of configYaml.errors) {
+				log.error('config', ` - ${error.toString()}`);
+			}
+
+			return false;
+		}
+
+		if (configYaml.warnings.length > 0) {
+			log.warn(
+				'config',
+				'Warnings while parsing configuration file at %s',
+				path,
+			);
+			for (const warning of configYaml.warnings) {
+				log.warn('config', ` - ${warning.toString()}`);
+			}
+		}
+
+		return configYaml.toJSON() as unknown;
+	} catch (e) {
+		log.error('config', 'Error reading configuration file at %s', path);
+		log.error('config', '%s', e);
+		return false;
+	}
+}
+
+export function validateConfig(config: unknown) {
+	log.debug('config', 'Validating Headplane configuration');
+	const result = headplaneConfig(config);
+	if (result instanceof type.errors) {
+		log.error('config', 'Error parsing Headplane configuration:');
+		for (const [number, error] of result.entries()) {
+			log.error('config', ` - (${number}): ${error.toString()}`);
+		}
+
+		return;
+	}
+
+	return result;
+}
+
+function coalesceEnv(config: HeadplaneConfig) {
+	const envConfig: Record<string, unknown> = {};
+	const rootKeys: string[] = Object.values(envVariables);
+
+	// Typescript is still insanely stupid at nullish filtering
+	const vars = Object.entries(env).filter(([key, value]) => {
+		if (!value) {
+			return false;
+		}
+
+		if (!key.startsWith('HEADPLANE_')) {
+			return false;
+		}
+
+		// Filter out the rootEnv configurations
+		if (rootKeys.includes(key)) {
+			return false;
+		}
+
+		return true;
+	}) as [string, string][];
+
+	log.debug('config', 'Coalescing %s environment variables', vars.length);
+	for (const [key, value] of vars) {
+		const configPath = key.replace('HEADPLANE_', '').toLowerCase().split('__');
+		log.debug(
+			'config',
+			` - ${key}=${new Array(value.length).fill('*').join('')}`,
+		);
+
+		let current = envConfig;
+		while (configPath.length > 1) {
+			const path = configPath.shift() as string;
+			if (!(path in current)) {
+				current[path] = {};
+			}
+
+			current = current[path] as Record<string, unknown>;
+		}
+
+		current[configPath[0]] = value;
+	}
+
+	const toMerge = coalesceConfig(envConfig);
+	if (!toMerge) {
+		return;
+	}
+
+	// Deep merge the environment variables into the configuration
+	// This will overwrite any existing values in the configuration
+	return deepMerge(config, toMerge);
+}
+
+export function coalesceConfig(config: unknown) {
+	log.debug('config', 'Revalidating config after coalescing variables');
+	const out = partialHeadplaneConfig(config);
+	if (out instanceof type.errors) {
+		log.error('config', 'Error parsing variables:');
+		for (const [number, error] of out.entries()) {
+			log.error('config', ` - (${number}): ${error.toString()}`);
+		}
+
+		return;
+	}
+
+	return out;
+}
+
+type DeepPartial<T> =
+	| {
+			[P in keyof T]?: DeepPartial<T[P]>;
+	  }
+	| undefined;
+
+function deepMerge<T>(target: T, source: DeepPartial<T>): T {
+	if (typeof target !== 'object' || typeof source !== 'object')
+		return source as T;
+	const result = { ...target } as T;
+
+	for (const key in source) {
+		const val = source[key];
+		if (val === undefined) {
+			continue;
+		}
+
+		if (typeof val === 'object') {
+			result[key] = deepMerge(result[key], val);
+			continue;
+		}
+
+		result[key] = val;
+	}
+
+	return result;
+}

app/server/config/schema.ts

@@ -0,0 +1,88 @@
+import { type } from 'arktype';
+
+const stringToBool = type('string | boolean').pipe((v) => Boolean(v));
+const serverConfig = type({
+	host: 'string.ip',
+	port: type('string | number.integer').pipe((v) => Number(v)),
+	cookie_secret: '32 <= string <= 32',
+	cookie_secure: stringToBool,
+	agent: type({
+		authkey: 'string = ""',
+		ttl: 'number.integer = 180000', // Default to 3 minutes
+		cache_path: 'string = "/var/lib/headplane/agent_cache.json"',
+	})
+		.onDeepUndeclaredKey('reject')
+		.default(() => ({
+			authkey: '',
+			ttl: 180000,
+			cache_path: '/var/lib/headplane/agent_cache.json',
+		})),
+});
+
+const oidcConfig = type({
+	issuer: 'string.url',
+	client_id: 'string',
+	client_secret: 'string?',
+	client_secret_path: 'string?',
+	token_endpoint_auth_method:
+		'"client_secret_basic" | "client_secret_post" | "client_secret_jwt"',
+	redirect_uri: 'string.url?',
+	disable_api_key_login: stringToBool,
+	headscale_api_key: 'string',
+	strict_validation: stringToBool.default(true),
+}).onDeepUndeclaredKey('reject');
+
+const headscaleConfig = type({
+	url: type('string.url').pipe((v) => (v.endsWith('/') ? v.slice(0, -1) : v)),
+	tls_cert_path: 'string?',
+	public_url: 'string.url?',
+	config_path: 'string?',
+	config_strict: stringToBool,
+}).onDeepUndeclaredKey('reject');
+
+const dockerConfig = type({
+	enabled: stringToBool,
+	container_name: 'string',
+	socket: 'string = "unix:///var/run/docker.sock"',
+});
+
+const kubernetesConfig = type({
+	enabled: stringToBool,
+	pod_name: 'string',
+	validate_manifest: stringToBool,
+});
+
+const procConfig = type({
+	enabled: stringToBool,
+});
+
+const integrationConfig = type({
+	'docker?': dockerConfig,
+	'kubernetes?': kubernetesConfig,
+	'proc?': procConfig,
+}).onDeepUndeclaredKey('reject');
+
+const partialIntegrationConfig = type({
+	'docker?': dockerConfig.partial(),
+	'kubernetes?': kubernetesConfig.partial(),
+	'proc?': procConfig.partial(),
+}).partial();
+
+export const headplaneConfig = type({
+	debug: stringToBool,
+	server: serverConfig,
+	'oidc?': oidcConfig,
+	'integration?': integrationConfig,
+	headscale: headscaleConfig,
+}).onDeepUndeclaredKey('reject');
+
+export const partialHeadplaneConfig = type({
+	debug: stringToBool,
+	server: serverConfig.partial(),
+	'oidc?': oidcConfig.partial(),
+	'integration?': partialIntegrationConfig,
+	headscale: headscaleConfig.partial(),
+}).partial();
+
+export type HeadplaneConfig = typeof headplaneConfig.infer;
+export type PartialHeadplaneConfig = typeof partialHeadplaneConfig.infer;

app/server/headscale/api-client.ts

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises';
+import { Agent, Dispatcher, request } from 'undici';
+import log from '~/utils/log';
+
+export async function createApiClient(base: string, certPath?: string) {
+	if (!certPath) {
+		return new ApiClient(new Agent(), base);
+	}
+
+	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 ApiClient(new Agent({ connect: { ca: data.trim() } }), base);
+	} catch (error) {
+		log.error('config', 'Failed to load Headscale TLS cert: %s', error);
+		log.debug('config', 'Error Details: %o', error);
+		return new ApiClient(new Agent(), base);
+	}
+}
+
+// Represents an error that occurred during a response
+// Thrown when status codes are >= 400
+export class ResponseError extends Error {
+	status: number;
+	response: string;
+
+	constructor(status: number, response: string) {
+		super(`Response Error (${status}): ${response}`);
+		this.name = 'ResponseError';
+		this.status = status;
+		this.response = response;
+	}
+}
+
+// Represents an error that occurred during a request
+// class RequestError extends Error {
+
+class ApiClient {
+	private agent: Agent;
+	private base: string;
+
+	constructor(agent: Agent, base: string) {
+		this.agent = agent;
+		this.base = base;
+	}
+
+	private async defaultFetch(
+		url: string,
+		options?: Partial<Dispatcher.RequestOptions>,
+	) {
+		const method = options?.method ?? 'GET';
+		log.debug('api', '%s %s', method, url);
+
+		return await request(new URL(url, this.base), {
+			dispatcher: this.agent,
+			throwOnError: false,
+			headers: {
+				...options?.headers,
+				Accept: 'application/json',
+				'User-Agent': `Headplane/${__VERSION__}`,
+			},
+			body: options?.body,
+			method,
+		});
+	}
+
+	async healthcheck() {
+		try {
+			const res = await this.defaultFetch('/health');
+			return res.statusCode === 200;
+		} catch (error) {
+			log.debug('api', 'Healthcheck failed %o', error);
+			return false;
+		}
+	}
+
+	async get<T = unknown>(url: string, key: string) {
+		const res = await this.defaultFetch(`/api/${url}`, {
+			headers: {
+				Authorization: `Bearer ${key}`,
+			},
+		});
+
+		if (res.statusCode >= 400) {
+			log.debug('api', 'GET %s failed with status %d', url, res.statusCode);
+			throw new ResponseError(res.statusCode, await res.body.text());
+		}
+
+		return res.body.json() as Promise<T>;
+	}
+
+	async post<T = unknown>(url: string, key: string, body?: unknown) {
+		const res = await this.defaultFetch(`/api/${url}`, {
+			method: 'POST',
+			body: body ? JSON.stringify(body) : undefined,
+			headers: {
+				Authorization: `Bearer ${key}`,
+			},
+		});
+
+		if (res.statusCode >= 400) {
+			log.debug('api', 'POST %s failed with status %d', url, res.statusCode);
+			throw new ResponseError(res.statusCode, await res.body.text());
+		}
+
+		return res.body.json() as Promise<T>;
+	}
+
+	async put<T = unknown>(url: string, key: string, body?: unknown) {
+		const res = await this.defaultFetch(`/api/${url}`, {
+			method: 'PUT',
+			body: body ? JSON.stringify(body) : undefined,
+			headers: {
+				Authorization: `Bearer ${key}`,
+			},
+		});
+
+		if (res.statusCode >= 400) {
+			log.debug('api', 'PUT %s failed with status %d', url, res.statusCode);
+			throw new ResponseError(res.statusCode, await res.body.text());
+		}
+
+		return res.body.json() as Promise<T>;
+	}
+
+	async delete<T = unknown>(url: string, key: string) {
+		const res = await this.defaultFetch(`/api/${url}`, {
+			method: 'DELETE',
+			headers: {
+				Authorization: `Bearer ${key}`,
+			},
+		});
+
+		if (res.statusCode >= 400) {
+			log.debug('api', 'DELETE %s failed with status %d', url, res.statusCode);
+			throw new ResponseError(res.statusCode, await res.body.text());
+		}
+
+		return res.body.json() as Promise<T>;
+	}
+}

app/server/index.ts

@@ -0,0 +1,62 @@
+import { versions } from 'node:process';
+import { createHonoServer } from 'react-router-hono-server/node';
+import log from '~/utils/log';
+import { configureConfig, configureLogger, envVariables } from './config/env';
+import { loadConfig } from './config/loader';
+import { createApiClient } from './headscale/api-client';
+import { exampleMiddleware } from './middleware';
+import { createSessionStorage } from './web/sessions';
+
+// MARK: Side-Effects
+// This module contains a side-effect because everything running here
+// exists for the lifetime of the process, making it appropriate.
+log.info('server', 'Running Node.js %s', versions.node);
+configureLogger(process.env[envVariables.debugLog]);
+const config = await loadConfig(
+	configureConfig({
+		loadEnv: process.env[envVariables.envOverrides],
+		path: process.env[envVariables.configPath],
+	}),
+);
+
+// We also use this file to load anything needed by the react router code.
+// These are usually per-request things that we need access to, like the
+// helper that can issue and revoke cookies.
+export type LoadContext = typeof appLoadContext;
+const appLoadContext = {
+	config,
+
+	// TODO: Better cookie options in config
+	sessionizer: createSessionStorage({
+		name: '_hp_session',
+		maxAge: 60 * 60 * 24, // 24 hours
+		secure: config.server.cookie_secure,
+		secrets: [config.server.cookie_secret],
+	}),
+
+	client: await createApiClient(
+		config.headscale.url,
+		config.headscale.tls_cert_path,
+	),
+};
+
+declare module 'react-router' {
+	interface AppLoadContext extends LoadContext {}
+}
+
+export default await createHonoServer({
+	useWebSocket: true,
+	overrideGlobalObjects: true,
+
+	getLoadContext(c, { build, mode }) {
+		// This is the place where we can handle reverse proxy translation
+		return appLoadContext;
+	},
+
+	configure(server) {
+		server.use('*', exampleMiddleware());
+	},
+	listeningListener(info) {
+		console.log(`Server is listening on http://localhost:${info.port}`);
+	},
+});

app/server/middleware.ts

@@ -0,0 +1,8 @@
+import { createMiddleware } from 'hono/factory';
+
+export function exampleMiddleware() {
+	return createMiddleware(async (c, next) => {
+		console.log('accept-language', c.req.header('accept-language'));
+		return next();
+	});
+}

app/server/web/sessions.ts

@@ -0,0 +1,81 @@
+import {
+	Session,
+	SessionStorage,
+	createCookieSessionStorage,
+} from 'react-router';
+
+export interface AuthSession {
+	state: 'auth';
+	api_key: string;
+	user: {
+		subject: string;
+		name: string;
+		email?: string;
+		username?: string;
+		picture?: string;
+	};
+}
+
+interface OidcFlowSession {
+	state: 'flow';
+	oidc: {
+		state: string;
+		nonce: string;
+		code_verifier: string;
+		redirect_uri: string;
+	};
+}
+
+type JoinedSession = AuthSession | OidcFlowSession;
+interface Error {
+	error: string;
+}
+
+interface CookieOptions {
+	name: string;
+	secure: boolean;
+	maxAge: number;
+	secrets: string[];
+	domain?: string;
+}
+
+class Sessionizer {
+	private storage: SessionStorage<JoinedSession, Error>;
+	constructor(options: CookieOptions) {
+		this.storage = createCookieSessionStorage({
+			cookie: {
+				...options,
+				httpOnly: true,
+				path: __PREFIX__, // Only match on the prefix
+				sameSite: 'lax', // TODO: Strictify with Domain,
+			},
+		});
+	}
+
+	async auth(request: Request) {
+		const cookie = request.headers.get('cookie');
+		const session = await this.storage.getSession(cookie);
+		const type = session.get('state');
+		if (!type) {
+			return false;
+		}
+
+		if (type !== 'auth') {
+			return false;
+		}
+
+		return session as Session<AuthSession>;
+	}
+
+	destroy(session: Session) {
+		return this.storage.destroySession(session);
+	}
+
+	commit(session: Session) {
+		return this.storage.commitSession(session);
+	}
+}
+
+export function createSessionStorage(options: CookieOptions) {
+	return new Sessionizer(options);
+}