systemd-ts 0.3.0 → 0.3.2

package/src/main/errors.ts

@@ -0,0 +1,348 @@
+import type { StartStatus } from "./types.ts";
+
+export type SystemdTsErrorCode =
+  | `SYSTEMD_TS_INVALID_EXEC_DIRECTIVE`
+  | `SYSTEMD_TS_NO_UNITS_PROVIDED`
+  | `SYSTEMD_TS_EXECUTABLE_INFERENCE`
+  | `SYSTEMD_TS_UNIT_MATERIALIZATION`
+  | `SYSTEMD_TS_UNIT_ENABLE`
+  | `SYSTEMD_TS_UNIT_START`
+  | `SYSTEMD_TS_UNIT_LOGS`
+  | `SYSTEMD_TS_SYSTEMCTL`
+  | `SYSTEMD_TS_NOTIFY_SEND`;
+
+export interface SystemdTsErrorOptions {
+  readonly cause?: unknown;
+}
+
+export interface SystemdCommandErrorOptions extends SystemdTsErrorOptions {
+  readonly args?: readonly string[];
+  readonly command?: string;
+  readonly environmentReason?: SystemdCommandEnvironmentReason;
+  readonly stage?: string;
+  readonly unitName?: string;
+  readonly unitPath?: string;
+}
+
+export interface UnitStartDiagnostics {
+  readonly showOutput?: string;
+  readonly showStatus?: StartStatus;
+  readonly statusOutput?: string;
+}
+
+export interface UnitStartErrorOptions extends SystemdCommandErrorOptions {
+  readonly diagnostics?: UnitStartDiagnostics;
+}
+
+export interface UnitMaterializationErrorOptions extends SystemdTsErrorOptions {
+  readonly reason?: UnitMaterializationErrorReason;
+  readonly operation?: `create-directory` | `write-file`;
+  readonly unitName?: string;
+  readonly unitPath?: string;
+}
+
+export type UnitMaterializationErrorReason =
+  | `file-system-failed`
+  | `invalid-unit-directory`
+  | `permission-denied`;
+
+export interface UnitLogsReadErrorOptions extends SystemdCommandErrorOptions {
+  readonly reason?: UnitLogsReadErrorReason;
+  readonly unitPath?: string;
+}
+
+export type UnitLogsReadErrorReason =
+  | `missing-log-file`
+  | `log-file-read-failed`
+  | `status-command-failed`;
+
+export interface NotifySendErrorOptions extends SystemdCommandErrorOptions {
+  readonly reason?: NotifySendErrorReason;
+}
+
+export type NotifySendErrorReason = `executor-failed` | `systemd-notify-failed`;
+
+export interface SystemctlCommandErrorOptions extends SystemdCommandErrorOptions {
+  readonly operation?: string;
+  readonly reason?: SystemctlCommandErrorReason;
+}
+
+export type SystemctlCommandErrorReason = `executor-failed` | `invalid-json`;
+
+export type SystemdCommandEnvironmentReason =
+  | `manager-unavailable`
+  | `missing-command`
+  | `permission-denied`;
+
+export class SystemdTsError extends Error {
+  public readonly code: SystemdTsErrorCode;
+
+  public constructor(
+    code: SystemdTsErrorCode,
+    message: string,
+    options: SystemdTsErrorOptions = {},
+  ) {
+    super(message, { cause: options.cause });
+    this.code = code;
+    this.name = new.target.name;
+  }
+}
+
+export class InvalidExecDirectiveError extends SystemdTsError {
+  public readonly directive: string;
+
+  public constructor(directive: string, options: SystemdTsErrorOptions = {}) {
+    super(
+      `SYSTEMD_TS_INVALID_EXEC_DIRECTIVE`,
+      `${directive} must use an absolute executable path for systemd`,
+      options,
+    );
+    this.directive = directive;
+  }
+}
+
+export class NoUnitsProvidedError extends SystemdTsError {
+  public readonly operation: string;
+
+  public constructor(operation: string, options: SystemdTsErrorOptions = {}) {
+    super(
+      `SYSTEMD_TS_NO_UNITS_PROVIDED`,
+      `${operation} requires at least one service or timer`,
+      options,
+    );
+    this.operation = operation;
+  }
+}
+
+export class ExecutableInferenceError extends SystemdTsError {
+  public constructor(options: SystemdTsErrorOptions = {}) {
+    super(
+      `SYSTEMD_TS_EXECUTABLE_INFERENCE`,
+      `Could not infer the calling module path for defineExecutable(); pass { modulePath } explicitly`,
+      options,
+    );
+  }
+}
+
+export class UnitMaterializationError extends SystemdTsError {
+  public readonly operation: `create-directory` | `write-file` | undefined;
+  public readonly reason: UnitMaterializationErrorReason | undefined;
+  public readonly unitName: string | undefined;
+  public readonly unitPath: string | undefined;
+
+  public constructor(message: string, options: UnitMaterializationErrorOptions = {}) {
+    super(`SYSTEMD_TS_UNIT_MATERIALIZATION`, message, options);
+    this.operation = options.operation;
+    this.reason = options.reason;
+    this.unitName = options.unitName;
+    this.unitPath = options.unitPath;
+  }
+}
+
+export class UnitEnableError extends SystemdTsError {
+  public readonly args: readonly string[] | undefined;
+  public readonly command: string | undefined;
+  public readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  public readonly exitCode: number | undefined;
+  public readonly stage: string | undefined;
+  public readonly stderr: string | undefined;
+  public readonly stdout: string | undefined;
+  public readonly unitName: string | undefined;
+  public readonly unitPath: string | undefined;
+
+  public constructor(message: string, options: SystemdCommandErrorOptions = {}) {
+    super(`SYSTEMD_TS_UNIT_ENABLE`, message, options);
+    const details = extractCommandErrorDetails(options.cause);
+    this.args = options.args;
+    this.command = options.command;
+    this.environmentReason =
+      options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+    this.exitCode = details.exitCode;
+    this.stage = options.stage;
+    this.stderr = details.stderr;
+    this.stdout = details.stdout;
+    this.unitName = options.unitName;
+    this.unitPath = options.unitPath;
+  }
+}
+
+export class UnitStartError extends SystemdTsError {
+  public readonly args: readonly string[] | undefined;
+  public readonly command: string | undefined;
+  public readonly diagnostics: UnitStartDiagnostics | undefined;
+  public readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  public readonly exitCode: number | undefined;
+  public readonly stage: string | undefined;
+  public readonly stderr: string | undefined;
+  public readonly stdout: string | undefined;
+  public readonly unitName: string | undefined;
+  public readonly unitPath: string | undefined;
+
+  public constructor(message: string, options: UnitStartErrorOptions = {}) {
+    super(`SYSTEMD_TS_UNIT_START`, message, options);
+    const details = extractCommandErrorDetails(options.cause);
+    this.args = options.args;
+    this.command = options.command;
+    this.diagnostics = options.diagnostics;
+    this.environmentReason =
+      options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+    this.exitCode = details.exitCode;
+    this.stage = options.stage;
+    this.stderr = details.stderr;
+    this.stdout = details.stdout;
+    this.unitName = options.unitName;
+    this.unitPath = options.unitPath;
+  }
+}
+
+export class UnitLogsReadError extends SystemdTsError {
+  public readonly args: readonly string[] | undefined;
+  public readonly command: string | undefined;
+  public readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  public readonly exitCode: number | undefined;
+  public readonly reason: UnitLogsReadErrorReason | undefined;
+  public readonly stage: string | undefined;
+  public readonly stderr: string | undefined;
+  public readonly stdout: string | undefined;
+  public readonly unitName: string | undefined;
+  public readonly unitPath: string | undefined;
+
+  public constructor(message: string, options: UnitLogsReadErrorOptions = {}) {
+    super(`SYSTEMD_TS_UNIT_LOGS`, message, options);
+    const details = extractCommandErrorDetails(options.cause);
+    this.args = options.args;
+    this.command = options.command;
+    this.environmentReason =
+      options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+    this.exitCode = details.exitCode;
+    this.reason = options.reason;
+    this.stage = options.stage;
+    this.stderr = details.stderr;
+    this.stdout = details.stdout;
+    this.unitName = options.unitName;
+    this.unitPath = options.unitPath;
+  }
+}
+
+export class NotifySendError extends SystemdTsError {
+  public readonly args: readonly string[] | undefined;
+  public readonly command: string | undefined;
+  public readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  public readonly exitCode: number | undefined;
+  public readonly reason: NotifySendErrorReason | undefined;
+  public readonly stage: string | undefined;
+  public readonly stderr: string | undefined;
+  public readonly stdout: string | undefined;
+
+  public constructor(message: string, options: NotifySendErrorOptions = {}) {
+    super(`SYSTEMD_TS_NOTIFY_SEND`, message, options);
+    const details = extractCommandErrorDetails(options.cause);
+    this.args = options.args;
+    this.command = options.command;
+    this.environmentReason =
+      options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+    this.exitCode = details.exitCode;
+    this.reason = options.reason;
+    this.stage = options.stage;
+    this.stderr = details.stderr;
+    this.stdout = details.stdout;
+  }
+}
+
+export class SystemctlCommandError extends SystemdTsError {
+  public readonly args: readonly string[] | undefined;
+  public readonly command: string | undefined;
+  public readonly environmentReason: SystemdCommandEnvironmentReason | undefined;
+  public readonly exitCode: number | undefined;
+  public readonly operation: string | undefined;
+  public readonly reason: SystemctlCommandErrorReason | undefined;
+  public readonly stage: string | undefined;
+  public readonly stderr: string | undefined;
+  public readonly stdout: string | undefined;
+
+  public constructor(message: string, options: SystemctlCommandErrorOptions = {}) {
+    super(`SYSTEMD_TS_SYSTEMCTL`, message, options);
+    const details = extractCommandErrorDetails(options.cause);
+    this.args = options.args;
+    this.command = options.command;
+    this.environmentReason =
+      options.environmentReason ?? classifyCommandEnvironmentReason(options.cause);
+    this.exitCode = details.exitCode;
+    this.operation = options.operation;
+    this.reason = options.reason;
+    this.stage = options.stage;
+    this.stderr = details.stderr;
+    this.stdout = details.stdout;
+  }
+}
+
+export function classifyCommandEnvironmentReason(
+  cause: unknown,
+): SystemdCommandEnvironmentReason | undefined {
+  if (cause === null || typeof cause !== `object`) {
+    return undefined;
+  }
+
+  const record = cause as Record<string, unknown>;
+  if (record[`code`] === `ENOENT`) {
+    return `missing-command`;
+  }
+
+  if (record[`code`] === `EACCES` || record[`code`] === `EPERM`) {
+    return `permission-denied`;
+  }
+
+  const combinedOutput = [record[`stderr`], record[`stdout`]]
+    .filter((value): value is string => typeof value === `string` && value.length > 0)
+    .join(`\n`);
+
+  if (
+    combinedOutput.includes(`Failed to connect to bus`) ||
+    combinedOutput.includes(`System has not been booted with systemd`) ||
+    combinedOutput.includes(`Failed to get D-Bus connection`)
+  ) {
+    return `manager-unavailable`;
+  }
+
+  return undefined;
+}
+
+export function classifyMaterializationReason(
+  cause: unknown,
+): UnitMaterializationErrorReason | undefined {
+  if (cause === null || typeof cause !== `object`) {
+    return undefined;
+  }
+
+  const record = cause as Record<string, unknown>;
+  if (record[`code`] === `EACCES` || record[`code`] === `EPERM` || record[`code`] === `EROFS`) {
+    return `permission-denied`;
+  }
+
+  if (record[`code`] === `EEXIST` || record[`code`] === `ENOTDIR` || record[`code`] === `EISDIR`) {
+    return `invalid-unit-directory`;
+  }
+
+  return `file-system-failed`;
+}
+
+function extractCommandErrorDetails(cause: unknown): {
+  readonly exitCode: number | undefined;
+  readonly stderr: string | undefined;
+  readonly stdout: string | undefined;
+} {
+  if (cause === null || typeof cause !== `object`) {
+    return {
+      exitCode: undefined,
+      stderr: undefined,
+      stdout: undefined,
+    };
+  }
+
+  const record = cause as Record<string, unknown>;
+  return {
+    exitCode: typeof record[`code`] === `number` ? record[`code`] : undefined,
+    stderr: typeof record[`stderr`] === `string` ? record[`stderr`] : undefined,
+    stdout: typeof record[`stdout`] === `string` ? record[`stdout`] : undefined,
+  };
+}

package/src/main/executable.ts

@@ -0,0 +1,175 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { ExecutableInferenceError } from "./errors.ts";
+import type { Result } from "./internal.ts";
+import type { ExecutableOptions } from "./types.ts";
+
+const currentModulePath = fileURLToPath(import.meta.url);
+
+/**
+ * An immutable description of a runnable module entrypoint that can be used in
+ * executable-valued systemd unit directives.
+ *
+ * `Executable` captures three pieces of information:
+ * - the absolute runtime binary that should launch the module
+ * - the absolute path to the module itself
+ * - any additional arguments that should be passed after the module path
+ *
+ * Most consumers will create one via {@link defineExecutable} and then pass it
+ * into a {@link SystemdService} directive such as `ExecStart`, `ExecStop`, or
+ * `ExecReload`.
+ */
+export class Executable {
+  /** Additional arguments passed after the module path. */
+  public readonly args: readonly string[];
+  /** Inference issue captured when no explicit module path was provided. */
+  public readonly inferenceError: ExecutableInferenceError | undefined;
+  /** Absolute path to the module that should be executed. */
+  public readonly modulePath: string;
+  /** Absolute path to the runtime binary that should launch the module. */
+  public readonly runtimeEntrypoint: string;
+
+  /**
+   * Creates an executable description.
+   *
+   * When `modulePath` is omitted, the calling module is inferred from the
+   * current stack so `defineExecutable()` can be used inline from the module
+   * that should become runnable.
+   *
+   * When `runtimeEntrypoint` is omitted, the current process executable is
+   * used. This works well for the common case where the same runtime that is
+   * evaluating your module should also be used by systemd.
+   */
+  public constructor(options: ExecutableOptions = {}) {
+    this.runtimeEntrypoint = options.runtimeEntrypoint ?? process.execPath;
+    const inferredModulePath = options.modulePath ?? tryInferCallerModulePath();
+    this.inferenceError =
+      inferredModulePath === undefined && options.modulePath === undefined
+        ? new ExecutableInferenceError()
+        : undefined;
+    this.modulePath = inferredModulePath ?? ``;
+    this.args = Object.freeze([...(options.args ?? [])]);
+    Object.freeze(this);
+  }
+
+  /**
+   * Returns the executable as raw command parts.
+   *
+   * The first element is always the runtime entrypoint, followed by the module
+   * path and any configured arguments.
+   */
+  public toCommandParts(): Result<readonly [string, ...string[]], ExecutableInferenceError> {
+    if (this.inferenceError !== undefined) {
+      return {
+        ok: false,
+        error: this.inferenceError,
+      };
+    }
+
+    return {
+      ok: true,
+      value: [this.runtimeEntrypoint, this.modulePath, ...this.args],
+    };
+  }
+
+  /**
+   * Renders the executable as a shell-quoted command string suitable for
+   * executable-valued systemd directives such as `ExecStart=`.
+   */
+  public toExecStart(): Result<string, ExecutableInferenceError> {
+    const commandParts = this.toCommandParts();
+    if (!commandParts.ok) {
+      return commandParts;
+    }
+
+    return {
+      ok: true,
+      value: commandParts.value.map(shellQuote).join(` `),
+    };
+  }
+}
+
+/**
+ * Defines a module as a runnable executable and returns its immutable
+ * `Executable` description.
+ *
+ * This helper is designed for the pattern:
+ *
+ * ```ts
+ * export default defineExecutable(async () => {
+ *   // do work here
+ * });
+ * ```
+ *
+ * When the defining module is executed as the main entrypoint, `fn` is invoked.
+ * When the module is merely imported, `fn` is not run and only the executable
+ * description is returned.
+ *
+ * Pass `options.runtimeEntrypoint` to override the default runtime binary when
+ * the current process is not the exact runtime you want systemd to use.
+ */
+export function defineExecutable(
+  fn: () => void | Promise<void>,
+  options: ExecutableOptions = {},
+): Executable {
+  const executable = new Executable(options);
+
+  if (executable.inferenceError === undefined && isMainModule(executable.modulePath)) {
+    void Promise.resolve(fn()).catch((error: unknown) => {
+      process.exitCode = 1;
+      throw error;
+    });
+  }
+
+  return executable;
+}
+
+function tryInferCallerModulePath(): string | undefined {
+  const stack = new Error().stack ?? ``;
+  for (const line of stack.split(`\n`).slice(1)) {
+    const candidate = extractStackPath(line);
+    if (candidate === undefined || candidate === currentModulePath) {
+      continue;
+    }
+
+    return candidate;
+  }
+
+  return undefined;
+}
+
+function extractStackPath(line: string): string | undefined {
+  const fileUrlMatch = line.match(/(file:\/\/\/[^)\s:]+(?:\.[cm]?[jt]s)?)/u);
+  if (fileUrlMatch !== null) {
+    return fileURLToPath(fileUrlMatch[1]);
+  }
+
+  const pathMatch = line.match(/(\/[^)\s:]+(?:\.[cm]?[jt]s)?)/u);
+  if (pathMatch !== null) {
+    return pathMatch[1];
+  }
+
+  return undefined;
+}
+
+function isMainModule(modulePath: string): boolean {
+  const mainArg = process.argv[1];
+  if (mainArg === undefined) {
+    return false;
+  }
+
+  return normalizeFilePath(mainArg) === normalizeFilePath(modulePath);
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll(`'`, `'\\''`)}'`;
+}
+
+function normalizeFilePath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}

package/src/main/index.ts

@@ -0,0 +1,76 @@
+export {
+  ExecutableInferenceError,
+  InvalidExecDirectiveError,
+  NoUnitsProvidedError,
+  NotifySendError,
+  SystemctlCommandError,
+  SystemdTsError,
+  UnitEnableError,
+  UnitLogsReadError,
+  UnitMaterializationError,
+  UnitStartError,
+} from "./errors.ts";
+export { Executable, defineExecutable } from "./executable.ts";
+export { notify } from "./notify.ts";
+export { SystemdService } from "./systemd-service.ts";
+export { SystemdTimer } from "./systemd-timer.ts";
+export { Systemctl } from "./systemctl.ts";
+export { Systemd, SystemdMaterialization, SystemdTs, defaultSystemd } from "./systemd.ts";
+export type {
+  SystemdTsAttachmentSelector,
+  SystemdTsAttachOptions,
+  SystemdTsAttachmentResult,
+  SystemdTsDetachOptions,
+  SystemdTsReattachOptions,
+} from "./systemd.ts";
+export type { Result } from "./internal.ts";
+export type {
+  AnySystemdService,
+  AnySystemdTimer,
+  CommandExecutionOptions,
+  CommandExecutor,
+  CommandOutput,
+  ExecutableOptions,
+  MaterializedUnit,
+  LogsOptions,
+  NotifyOptions,
+  ServiceBaseName,
+  ServiceFilename,
+  StartStatus,
+  SystemdOptions,
+  SystemdServiceOptions,
+  SystemctlActiveState,
+  SystemctlEnablementState,
+  SystemctlIsEnabledOptions,
+  SystemctlIsSystemRunningOptions,
+  SystemctlListTimersOptions,
+  SystemctlOptions,
+  SystemctlServiceStatus,
+  SystemctlSystemRunningState,
+  SystemctlStateQueryOptions,
+  SystemctlShowOptions,
+  SystemctlStatusOptions,
+  SystemctlTimerListEntry,
+  SystemdTimerOptions,
+  SystemdUnit,
+  TimerBaseName,
+  TimerFilename,
+  TimerTargetServiceName,
+  TimerTargetUnit,
+  UnitValue,
+  ValidInstallUnits,
+} from "./types.ts";
+export type {
+  NotifySendErrorReason,
+  SystemctlCommandErrorReason,
+  SystemdCommandEnvironmentReason,
+  UnitLogsReadErrorReason,
+  UnitMaterializationErrorReason,
+} from "./errors.ts";
+
+import * as I from "./internal.ts";
+/**
+ * Internal helpers are exposed for advanced use, but they are not a stable public API.
+ * Expect breaking changes here outside the package's normal compatibility guarantees.
+ */
+export const Internal: typeof I = I;