From cbbd64e91a9fa3b18937d5aa15bacce29a988644 Mon Sep 17 00:00:00 2001 From: Aarnav Tale Date: Thu, 20 Mar 2025 15:30:34 -0400 Subject: [PATCH] feat: initial server side systems --- app/server/README.md | 19 +++ app/server/config/env.ts | 64 ++++++++ app/server/config/loader.ts | 225 +++++++++++++++++++++++++++++ app/server/config/schema.ts | 88 +++++++++++ app/server/headscale/api-client.ts | 143 ++++++++++++++++++ app/server/index.ts | 62 ++++++++ app/server/middleware.ts | 8 + app/server/web/sessions.ts | 81 +++++++++++ 8 files changed, 690 insertions(+) create mode 100644 app/server/README.md create mode 100644 app/server/config/env.ts create mode 100644 app/server/config/loader.ts create mode 100644 app/server/config/schema.ts create mode 100644 app/server/headscale/api-client.ts create mode 100644 app/server/index.ts create mode 100644 app/server/middleware.ts create mode 100644 app/server/web/sessions.ts diff --git a/app/server/README.md b/app/server/README.md new file mode 100644 index 0000000..f6851b1 --- /dev/null +++ b/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. diff --git a/app/server/config/env.ts b/app/server/config/env.ts new file mode 100644 index 0000000..0ae42ca --- /dev/null +++ b/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; +} diff --git a/app/server/config/loader.ts b/app/server/config/loader.ts new file mode 100644 index 0000000..8307f5b --- /dev/null +++ b/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 { + 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 = {}; + 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; + } + + 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 = + | { + [P in keyof T]?: DeepPartial; + } + | undefined; + +function deepMerge(target: T, source: DeepPartial): 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; +} diff --git a/app/server/config/schema.ts b/app/server/config/schema.ts new file mode 100644 index 0000000..c4e3c6c --- /dev/null +++ b/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; diff --git a/app/server/headscale/api-client.ts b/app/server/headscale/api-client.ts new file mode 100644 index 0000000..8cf9691 --- /dev/null +++ b/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, + ) { + 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(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; + } + + async post(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; + } + + async put(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; + } + + async delete(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; + } +} diff --git a/app/server/index.ts b/app/server/index.ts new file mode 100644 index 0000000..7b3f93b --- /dev/null +++ b/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}`); + }, +}); diff --git a/app/server/middleware.ts b/app/server/middleware.ts new file mode 100644 index 0000000..6aec11c --- /dev/null +++ b/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(); + }); +} diff --git a/app/server/web/sessions.ts b/app/server/web/sessions.ts new file mode 100644 index 0000000..05b85b4 --- /dev/null +++ b/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; + 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; + } + + 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); +}