@outfitter/daemon 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,771 @@
+import { Result, TaggedErrorClass } from "@outfitter/contracts";
+import { LoggerInstance } from "@outfitter/logging";
+declare const DaemonErrorBase: TaggedErrorClass<"DaemonError", {
+	code: DaemonErrorCode;
+	message: string;
+}>;
+/**
+* Error codes for daemon operations.
+*
+* - `ALREADY_RUNNING`: Daemon start requested but already running
+* - `NOT_RUNNING`: Daemon stop requested but not running
+* - `SHUTDOWN_TIMEOUT`: Graceful shutdown exceeded timeout
+* - `PID_ERROR`: PID file operations failed
+* - `START_FAILED`: Daemon failed to start
+*/
+type DaemonErrorCode = "ALREADY_RUNNING" | "NOT_RUNNING" | "SHUTDOWN_TIMEOUT" | "PID_ERROR" | "START_FAILED";
+/**
+* Error type for daemon operations.
+*
+* Uses the TaggedError pattern for type-safe error handling with Result types.
+*
+* @example
+* ```typescript
+* const error = new DaemonError({
+*   code: "ALREADY_RUNNING",
+*   message: "Daemon is already running with PID 1234",
+* });
+*
+* if (error.code === "ALREADY_RUNNING") {
+*   console.log("Stop the existing daemon first");
+* }
+* ```
+*/
+declare class DaemonError extends DaemonErrorBase {}
+/**
+* Daemon lifecycle states.
+*
+* State machine transitions:
+* - `stopped` -> `starting` (via start())
+* - `starting` -> `running` (when initialization complete)
+* - `starting` -> `stopped` (if start fails)
+* - `running` -> `stopping` (via stop() or signal)
+* - `stopping` -> `stopped` (when shutdown complete)
+*/
+type DaemonState = "stopped" | "starting" | "running" | "stopping";
+/**
+* Configuration options for creating a daemon.
+*
+* @example
+* ```typescript
+* const options: DaemonOptions = {
+*   name: "my-daemon",
+*   pidFile: "/var/run/my-daemon.pid",
+*   logger: myLogger,
+*   shutdownTimeout: 10000, // 10 seconds
+* };
+*
+* const daemon = createDaemon(options);
+* ```
+*/
+interface DaemonOptions {
+	/**
+	* Unique name identifying this daemon.
+	* Used in log messages and error context.
+	*/
+	name: string;
+	/**
+	* Absolute path to the PID file.
+	* The daemon writes its process ID here on start and removes it on stop.
+	* Used to prevent multiple instances and for external process management.
+	*/
+	pidFile: string;
+	/**
+	* Optional logger instance for daemon messages.
+	* If not provided, logging is disabled.
+	*/
+	logger?: LoggerInstance;
+	/**
+	* Maximum time in milliseconds to wait for graceful shutdown.
+	* After this timeout, the daemon will force stop.
+	* @defaultValue 5000
+	*/
+	shutdownTimeout?: number;
+}
+/**
+* Shutdown handler function type.
+*
+* Called during graceful shutdown to allow cleanup of resources.
+* Must complete within the shutdown timeout.
+*/
+type ShutdownHandler = () => Promise<void>;
+/**
+* Daemon instance interface.
+*
+* Provides lifecycle management for a background process including
+* start/stop operations, signal handling, and shutdown hooks.
+*
+* @example
+* ```typescript
+* const daemon = createDaemon({
+*   name: "my-service",
+*   pidFile: "/var/run/my-service.pid",
+* });
+*
+* // Register cleanup handlers
+* daemon.onShutdown(async () => {
+*   await database.close();
+* });
+*
+* // Start the daemon
+* const result = await daemon.start();
+* if (result.isErr()) {
+*   console.error("Failed to start:", result.error.message);
+*   process.exit(1);
+* }
+*
+* // Daemon is now running...
+* // Stop gracefully when needed
+* await daemon.stop();
+* ```
+*/
+interface Daemon {
+	/**
+	* Current lifecycle state of the daemon.
+	*/
+	readonly state: DaemonState;
+	/**
+	* Start the daemon.
+	*
+	* Creates PID file and registers signal handlers.
+	* Transitions from `stopped` to `starting` then `running`.
+	*
+	* @returns Result with void on success, or DaemonError on failure
+	*/
+	start(): Promise<Result<void, DaemonError>>;
+	/**
+	* Stop the daemon gracefully.
+	*
+	* Runs shutdown handlers, removes PID file, and cleans up signal handlers.
+	* Transitions from `running` to `stopping` then `stopped`.
+	*
+	* @returns Result with void on success, or DaemonError on failure
+	*/
+	stop(): Promise<Result<void, DaemonError>>;
+	/**
+	* Check if the daemon is currently running.
+	*
+	* @returns true if state is "running", false otherwise
+	*/
+	isRunning(): boolean;
+	/**
+	* Register a shutdown handler to be called during graceful shutdown.
+	*
+	* Multiple handlers can be registered and will be called in registration order.
+	* Handlers must complete within the shutdown timeout.
+	*
+	* @param handler - Async function to execute during shutdown
+	*/
+	onShutdown(handler: ShutdownHandler): void;
+}
+import { TaggedErrorClass as TaggedErrorClass2 } from "@outfitter/contracts";
+declare const StaleSocketErrorBase: TaggedErrorClass2<"StaleSocketError", {
+	message: string;
+	socketPath: string;
+	pid?: number;
+}>;
+declare const ConnectionRefusedErrorBase: TaggedErrorClass2<"ConnectionRefusedError", {
+	message: string;
+	socketPath: string;
+}>;
+declare const ConnectionTimeoutErrorBase: TaggedErrorClass2<"ConnectionTimeoutError", {
+	message: string;
+	socketPath: string;
+	timeoutMs: number;
+}>;
+declare const ProtocolErrorBase: TaggedErrorClass2<"ProtocolError", {
+	message: string;
+	socketPath: string;
+	details?: string;
+}>;
+declare const LockErrorBase: TaggedErrorClass2<"LockError", {
+	message: string;
+	lockPath: string;
+	pid?: number;
+}>;
+/**
+* Socket exists but daemon process is dead.
+*
+* Indicates a stale socket from a crashed daemon that needs cleanup
+* before a new daemon can start.
+*
+* @example
+* ```typescript
+* const error = new StaleSocketError({
+*   message: "Daemon socket is stale",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+*   pid: 12345,
+* });
+* ```
+*/
+declare class StaleSocketError extends StaleSocketErrorBase {}
+/**
+* Daemon is not running (connection refused).
+*
+* Socket does not exist or connection was actively refused,
+* indicating no daemon is listening.
+*
+* @example
+* ```typescript
+* const error = new ConnectionRefusedError({
+*   message: "Connection refused",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+* });
+* ```
+*/
+declare class ConnectionRefusedError extends ConnectionRefusedErrorBase {}
+/**
+* Daemon did not respond within timeout.
+*
+* Connection was established but daemon failed to respond
+* to ping or request within the configured timeout.
+*
+* @example
+* ```typescript
+* const error = new ConnectionTimeoutError({
+*   message: "Connection timed out after 5000ms",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+*   timeoutMs: 5000,
+* });
+* ```
+*/
+declare class ConnectionTimeoutError extends ConnectionTimeoutErrorBase {}
+/**
+* Invalid response format from daemon.
+*
+* Daemon responded but the response could not be parsed
+* or did not match the expected protocol format.
+*
+* @example
+* ```typescript
+* const error = new ProtocolError({
+*   message: "Invalid JSON response",
+*   socketPath: "/run/user/1000/waymark/daemon.sock",
+*   details: "Unexpected token at position 42",
+* });
+* ```
+*/
+declare class ProtocolError extends ProtocolErrorBase {}
+/**
+* Failed to acquire or release daemon lock.
+*
+* Used when PID file operations fail due to permissions,
+* concurrent access, or file system errors.
+*
+* @example
+* ```typescript
+* const error = new LockError({
+*   message: "Daemon already running",
+*   lockPath: "/run/user/1000/waymark/daemon.lock",
+*   pid: 12345,
+* });
+* ```
+*/
+declare class LockError extends LockErrorBase {}
+/**
+* Union of all daemon connection error types.
+*
+* Use for exhaustive matching on connection failures:
+*
+* @example
+* ```typescript
+* function handleError(error: DaemonConnectionError): string {
+*   switch (error._tag) {
+*     case "StaleSocketError":
+*       return `Stale socket at ${error.socketPath}`;
+*     case "ConnectionRefusedError":
+*       return "Daemon not running";
+*     case "ConnectionTimeoutError":
+*       return `Timeout after ${error.timeoutMs}ms`;
+*     case "ProtocolError":
+*       return `Protocol error: ${error.details}`;
+*   }
+* }
+* ```
+*/
+type DaemonConnectionError = StaleSocketError | ConnectionRefusedError | ConnectionTimeoutError | ProtocolError;
+/**
+* Check if running on a Unix-like platform (macOS or Linux).
+*
+* @returns true on macOS/Linux, false on Windows
+*
+* @example
+* ```typescript
+* if (isUnixPlatform()) {
+*   // Use Unix domain sockets
+* } else {
+*   // Use named pipes
+* }
+* ```
+*/
+declare function isUnixPlatform(): boolean;
+/**
+* Get the Unix domain socket path for a tool's daemon.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon socket
+*
+* @example
+* ```typescript
+* const socketPath = getSocketPath("waymark");
+* // "/run/user/1000/waymark/daemon.sock" on Linux
+* // "/var/folders/.../waymark/daemon.sock" on macOS
+* ```
+*/
+declare function getSocketPath(toolName: string): string;
+/**
+* Get the lock file path for a tool's daemon.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon lock file
+*
+* @example
+* ```typescript
+* const lockPath = getLockPath("waymark");
+* // "/run/user/1000/waymark/daemon.lock" on Linux
+* ```
+*/
+declare function getLockPath(toolName: string): string;
+/**
+* Get the PID file path for a tool's daemon.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon PID file
+*
+* @example
+* ```typescript
+* const pidPath = getPidPath("waymark");
+* // "/run/user/1000/waymark/daemon.pid" on Linux
+* ```
+*/
+declare function getPidPath(toolName: string): string;
+/**
+* Get the directory containing daemon files for a tool.
+*
+* @param toolName - Name of the tool (e.g., "waymark", "firewatch")
+* @returns Absolute path to the daemon directory
+*
+* @example
+* ```typescript
+* const daemonDir = getDaemonDir("waymark");
+* // "/run/user/1000/waymark" on Linux
+* ```
+*/
+declare function getDaemonDir(toolName: string): string;
+import { Result as Result2 } from "@outfitter/contracts";
+/**
+* Handle returned when a lock is successfully acquired.
+*
+* Must be passed to `releaseDaemonLock` to properly release the lock.
+*/
+interface LockHandle {
+	/** Path to the lock file */
+	readonly lockPath: string;
+	/** PID that owns the lock */
+	readonly pid: number;
+}
+/**
+* Check if a process with the given PID is alive.
+*
+* Uses `process.kill(pid, 0)` which sends no signal but checks
+* if the process exists and is accessible.
+*
+* @param pid - Process ID to check
+* @returns true if process exists and is accessible, false otherwise
+*
+* @example
+* ```typescript
+* if (isProcessAlive(12345)) {
+*   console.log("Process is still running");
+* } else {
+*   console.log("Process has exited");
+* }
+* ```
+*/
+declare function isProcessAlive(pid: number): boolean;
+/**
+* Check if a daemon is alive by reading its lock file.
+*
+* @param lockPath - Path to the daemon lock file
+* @returns true if lock file exists and process is alive, false otherwise
+*
+* @example
+* ```typescript
+* const alive = await isDaemonAlive("/run/user/1000/waymark/daemon.lock");
+* if (!alive) {
+*   // Safe to start a new daemon
+* }
+* ```
+*/
+declare function isDaemonAlive(lockPath: string): Promise<boolean>;
+/**
+* Acquire an exclusive lock for a daemon.
+*
+* Uses a PID file approach compatible with Bun:
+* 1. Check if lock file exists with a valid PID
+* 2. If PID is alive, refuse (daemon already running)
+* 3. If PID is stale or no lock, write our PID atomically
+*
+* @param lockPath - Path to create the lock file
+* @returns Result with LockHandle on success, LockError on failure
+*
+* @example
+* ```typescript
+* const result = await acquireDaemonLock("/run/user/1000/waymark/daemon.lock");
+*
+* if (result.isOk()) {
+*   console.log(`Lock acquired for PID ${result.value.pid}`);
+*   // ... run daemon ...
+*   await releaseDaemonLock(result.value);
+* } else {
+*   console.error(`Failed to acquire lock: ${result.error.message}`);
+* }
+* ```
+*/
+declare function acquireDaemonLock(lockPath: string): Promise<Result2<LockHandle, LockError>>;
+/**
+* Release a daemon lock.
+*
+* Removes the lock file only if the PID inside matches the handle.
+* This prevents accidentally removing a lock acquired by another process.
+*
+* @param handle - Lock handle returned from acquireDaemonLock
+*
+* @example
+* ```typescript
+* const result = await acquireDaemonLock(lockPath);
+* if (result.isOk()) {
+*   try {
+*     // ... run daemon ...
+*   } finally {
+*     await releaseDaemonLock(result.value);
+*   }
+* }
+* ```
+*/
+declare function releaseDaemonLock(handle: LockHandle): Promise<void>;
+/**
+* Read the PID from a lock file.
+*
+* @param lockPath - Path to the lock file
+* @returns The PID if valid, undefined otherwise
+*
+* @internal
+*/
+declare function readLockPid(lockPath: string): Promise<number | undefined>;
+/**
+* Create a new daemon instance.
+*
+* The daemon manages its own lifecycle including PID file creation/removal,
+* signal handling for graceful shutdown, and execution of registered
+* shutdown handlers.
+*
+* @param options - Daemon configuration options
+* @returns Daemon instance
+*
+* @example
+* ```typescript
+* const daemon = createDaemon({
+*   name: "my-service",
+*   pidFile: "/var/run/my-service.pid",
+*   shutdownTimeout: 10000,
+* });
+*
+* daemon.onShutdown(async () => {
+*   await database.close();
+* });
+*
+* const result = await daemon.start();
+* if (result.isErr()) {
+*   console.error("Failed to start:", result.error.message);
+*   process.exit(1);
+* }
+* ```
+*/
+declare function createDaemon(options: DaemonOptions): Daemon;
+/**
+* Message handler type for processing incoming IPC messages.
+*
+* Receives a parsed message and returns a response to send back to the client.
+* Throwing an error will result in an error response to the client.
+*/
+type IpcMessageHandler = (message: unknown) => Promise<unknown>;
+/**
+* IPC server interface for receiving messages from clients.
+*
+* The server listens on a Unix socket and processes incoming messages
+* using the registered message handler.
+*
+* @example
+* ```typescript
+* const server = createIpcServer("/var/run/my-daemon.sock");
+*
+* server.onMessage(async (msg) => {
+*   if (msg.type === "status") {
+*     return { status: "ok", uptime: process.uptime() };
+*   }
+*   return { error: "Unknown command" };
+* });
+*
+* await server.listen();
+* ```
+*/
+interface IpcServer {
+	/**
+	* Start listening for connections on the Unix socket.
+	*
+	* Creates the socket file and begins accepting client connections.
+	* Messages are processed using the handler registered via onMessage.
+	*/
+	listen(): Promise<void>;
+	/**
+	* Stop listening and close all connections.
+	*
+	* Removes the socket file and cleans up resources.
+	*/
+	close(): Promise<void>;
+	/**
+	* Register a message handler for incoming messages.
+	*
+	* Only one handler can be registered. Calling this multiple times
+	* replaces the previous handler.
+	*
+	* @param handler - Function to process incoming messages
+	*/
+	onMessage(handler: IpcMessageHandler): void;
+}
+/**
+* IPC client interface for sending messages to a server.
+*
+* The client connects to a Unix socket and can send messages,
+* receiving responses asynchronously.
+*
+* @example
+* ```typescript
+* const client = createIpcClient("/var/run/my-daemon.sock");
+*
+* await client.connect();
+*
+* const response = await client.send<StatusResponse>({ type: "status" });
+* console.log("Daemon uptime:", response.uptime);
+*
+* client.close();
+* ```
+*/
+interface IpcClient {
+	/**
+	* Connect to the IPC server.
+	*
+	* Establishes a connection to the Unix socket. Throws if the
+	* server is not available.
+	*/
+	connect(): Promise<void>;
+	/**
+	* Send a message and wait for a response.
+	*
+	* Serializes the message to JSON, sends it to the server, and
+	* waits for a response.
+	*
+	* @typeParam T - Expected response type
+	* @param message - Message to send (must be JSON-serializable)
+	* @returns Promise resolving to the server's response
+	* @throws Error if not connected or communication fails
+	*/
+	send<T>(message: unknown): Promise<T>;
+	/**
+	* Close the connection to the server.
+	*
+	* Can be called multiple times safely.
+	*/
+	close(): void;
+}
+/**
+* Create an IPC server listening on a Unix socket.
+*
+* @param socketPath - Path to the Unix socket file
+* @returns IpcServer instance
+*
+* @example
+* ```typescript
+* const server = createIpcServer("/var/run/my-daemon.sock");
+*
+* server.onMessage(async (msg) => {
+*   return { echo: msg };
+* });
+*
+* await server.listen();
+* // Server is now accepting connections
+* ```
+*/
+declare function createIpcServer(socketPath: string): IpcServer;
+/**
+* Create an IPC client for connecting to a server.
+*
+* @param socketPath - Path to the Unix socket file
+* @returns IpcClient instance
+*
+* @example
+* ```typescript
+* const client = createIpcClient("/var/run/my-daemon.sock");
+*
+* await client.connect();
+* const response = await client.send({ command: "status" });
+* console.log(response);
+* client.close();
+* ```
+*/
+declare function createIpcClient(socketPath: string): IpcClient;
+import { Result as Result3 } from "@outfitter/contracts";
+/**
+* A single health check definition.
+*
+* Health checks are used to verify that a service or resource is functioning
+* correctly. Each check has a name for identification and a check function
+* that returns a Result indicating success or failure.
+*
+* @example
+* ```typescript
+* const databaseCheck: HealthCheck = {
+*   name: "database",
+*   check: async () => {
+*     try {
+*       await db.ping();
+*       return Result.ok(undefined);
+*     } catch (error) {
+*       return Result.err(error);
+*     }
+*   },
+* };
+* ```
+*/
+interface HealthCheck {
+	/**
+	* Unique name identifying this health check.
+	* Used as the key in the HealthStatus.checks record.
+	*/
+	name: string;
+	/**
+	* Function that performs the health check.
+	*
+	* Should return Result.ok(undefined) if healthy, or Result.err(error)
+	* with details about the failure.
+	*/
+	check(): Promise<Result3<void, Error>>;
+}
+/**
+* Result of an individual health check.
+*
+* Contains the healthy/unhealthy status and an optional message
+* providing more details (typically the error message on failure).
+*/
+interface HealthCheckResult {
+	/** Whether this check passed (true) or failed (false) */
+	healthy: boolean;
+	/** Optional message, typically the error message on failure */
+	message?: string;
+}
+/**
+* Aggregated health status from all registered checks.
+*
+* The overall healthy status is true only if ALL individual checks pass.
+* Includes the uptime of the health checker in seconds.
+*
+* @example
+* ```typescript
+* const status: HealthStatus = {
+*   healthy: false,
+*   checks: {
+*     database: { healthy: true },
+*     cache: { healthy: false, message: "Connection refused" },
+*   },
+*   uptime: 3600,
+* };
+* ```
+*/
+interface HealthStatus {
+	/** Overall health status - true only if ALL checks pass */
+	healthy: boolean;
+	/** Individual check results keyed by check name */
+	checks: Record<string, HealthCheckResult>;
+	/** Uptime in seconds since the health checker was created */
+	uptime: number;
+}
+/**
+* Health checker interface for managing and running health checks.
+*
+* Provides methods to run all registered checks and get the aggregated
+* health status, as well as dynamically registering new checks at runtime.
+*
+* @example
+* ```typescript
+* const checker = createHealthChecker([
+*   { name: "db", check: checkDatabase },
+*   { name: "cache", check: checkCache },
+* ]);
+*
+* // Later, add more checks
+* checker.register({ name: "queue", check: checkQueue });
+*
+* // Get health status
+* const status = await checker.check();
+* console.log("Healthy:", status.healthy);
+* ```
+*/
+interface HealthChecker {
+	/**
+	* Run all registered health checks and return aggregated status.
+	*
+	* Checks are run in parallel for efficiency. The overall healthy
+	* status is true only if all individual checks pass.
+	*
+	* @returns Aggregated health status
+	*/
+	check(): Promise<HealthStatus>;
+	/**
+	* Register a new health check at runtime.
+	*
+	* The check will be included in all subsequent calls to check().
+	*
+	* @param check - Health check to register
+	*/
+	register(check: HealthCheck): void;
+}
+/**
+* Create a health checker with initial checks.
+*
+* The health checker runs all registered checks in parallel and aggregates
+* their results. Individual check failures are isolated and don't prevent
+* other checks from running.
+*
+* @param checks - Initial health checks to register
+* @returns HealthChecker instance
+*
+* @example
+* ```typescript
+* const checker = createHealthChecker([
+*   {
+*     name: "database",
+*     check: async () => {
+*       await db.ping();
+*       return Result.ok(undefined);
+*     },
+*   },
+*   {
+*     name: "cache",
+*     check: async () => {
+*       await redis.ping();
+*       return Result.ok(undefined);
+*     },
+*   },
+* ]);
+*
+* // Run health checks
+* const status = await checker.check();
+*
+* if (!status.healthy) {
+*   console.error("Service unhealthy:", status.checks);
+* }
+* ```
+*/
+declare function createHealthChecker(checks: HealthCheck[]): HealthChecker;
+export { releaseDaemonLock, readLockPid, isUnixPlatform, isProcessAlive, isDaemonAlive, getSocketPath, getPidPath, getLockPath, getDaemonDir, createIpcServer, createIpcClient, createHealthChecker, createDaemon, acquireDaemonLock, StaleSocketError, ShutdownHandler, ProtocolError, LockHandle, LockError, IpcServer, IpcMessageHandler, IpcClient, HealthStatus, HealthChecker, HealthCheckResult, HealthCheck, DaemonState, DaemonOptions, DaemonErrorCode, DaemonError, DaemonConnectionError, Daemon, ConnectionTimeoutError, ConnectionRefusedError };