systemd-ts 0.3.0 → 0.3.2

package/src/main/internal.ts

@@ -0,0 +1,406 @@
+import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { promisify } from "node:util";
+
+import { ExecutableInferenceError, InvalidExecDirectiveError, NotifySendError } from "./errors.ts";
+import { Executable } from "./executable.ts";
+import type {
+  CommandExecutionOptions,
+  CommandOutput,
+  NotifyOptions,
+  SystemdServiceSection,
+  StartStatus,
+  SystemdServiceOptions,
+  SystemdTimerOptions,
+  UnitValue,
+} from "./types.ts";
+
+export type Result<TValue, TError> =
+  | {
+      readonly ok: true;
+      readonly value: TValue;
+    }
+  | {
+      readonly ok: false;
+      readonly error: TError;
+    };
+
+type ExecDirectiveKey = (typeof EXEC_DIRECTIVE_KEYS)[number];
+
+const EXEC_DIRECTIVE_KEYS = [
+  `ExecCondition`,
+  `ExecReload`,
+  `ExecReloadPost`,
+  `ExecStart`,
+  `ExecStartPost`,
+  `ExecStartPre`,
+  `ExecStop`,
+  `ExecStopPost`,
+] as const;
+const execFileAsync = promisify(execFile);
+type SectionLike = object;
+
+export function normalizeUnitName(name: string, suffix: `.service` | `.timer`): string {
+  return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+}
+
+export function resolveTimerTargetUnit(options: SystemdTimerOptions): string {
+  const explicitTarget = options.timer[`Unit`];
+  if (typeof explicitTarget === `string` && explicitTarget.length > 0) {
+    return explicitTarget;
+  }
+
+  return `${normalizeUnitName(options.name, `.timer`)}.service`;
+}
+
+export function defaultUnitDirForScope(scope: `system` | `user`): string {
+  if (scope === `user`) {
+    return `${process.env[`HOME`] ?? `~`}/.config/systemd/user`;
+  }
+
+  return `/etc/systemd/system`;
+}
+
+export function freezeUnitOptions<TOptions extends SystemdServiceOptions | SystemdTimerOptions>(
+  options: TOptions,
+): Readonly<TOptions> {
+  return Object.freeze({
+    ...options,
+    ...(options.unit === undefined ? {} : { unit: cloneUnitSection(options.unit) }),
+    ...(options.install === undefined ? {} : { install: cloneUnitSection(options.install) }),
+    ...(hasServiceSection(options) ? { service: cloneUnitSection(options.service) } : {}),
+    ...(hasTimerSection(options) ? { timer: cloneUnitSection(options.timer) } : {}),
+  }) as Readonly<TOptions>;
+}
+
+export function cloneUnitSection<TSection extends SectionLike | undefined>(
+  section: TSection,
+): TSection {
+  if (section === undefined) {
+    return section;
+  }
+
+  const entries = Object.entries(section).map(([key, value]) => {
+    if (isUnitValueList(value)) {
+      return [key, Object.freeze([...value])] as const;
+    }
+
+    return [key, value] as const;
+  });
+
+  return Object.freeze(Object.fromEntries(entries)) as TSection;
+}
+
+export function validateServiceSection(
+  service: SystemdServiceSection,
+): Result<void, InvalidExecDirectiveError> {
+  for (const key of EXEC_DIRECTIVE_KEYS) {
+    const validation = assertAbsoluteExecValue(key, service[key]);
+    if (!validation.ok) {
+      return validation;
+    }
+  }
+
+  return {
+    ok: true,
+    value: undefined,
+  };
+}
+
+export function parseStartStatus(unit: string, output: string): StartStatus {
+  const properties = Object.fromEntries(
+    output
+      .split(`\n`)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .map((line) => {
+        const separatorIndex = line.indexOf(`=`);
+        if (separatorIndex === -1) {
+          return [line, ``] as const;
+        }
+
+        return [line.slice(0, separatorIndex), line.slice(separatorIndex + 1)] as const;
+      }),
+  );
+
+  return {
+    activeState: properties[`ActiveState`] ?? `unknown`,
+    execMainStatus:
+      properties[`ExecMainStatus`] === undefined || properties[`ExecMainStatus`] === ``
+        ? undefined
+        : Number(properties[`ExecMainStatus`]),
+    result: properties[`Result`] ?? `unknown`,
+    subState: properties[`SubState`] ?? `unknown`,
+    unit: properties[`Id`] ?? unit,
+  };
+}
+
+export function renderUnitFile(
+  sections: ReadonlyArray<readonly [string, SectionLike | undefined]>,
+): Result<string, ExecutableInferenceError> {
+  try {
+    const renderedSections = sections
+      .flatMap(([sectionName, section]) => {
+        if (section === undefined) {
+          return [];
+        }
+
+        const lines: string[] = [];
+        for (const [key, value] of Object.entries(section as Record<string, unknown>)) {
+          if (value === undefined) {
+            continue;
+          }
+
+          if (isUnitValueList(value)) {
+            for (const entry of value) {
+              const rendered = stringifyUnitValue(entry);
+              if (!rendered.ok) {
+                throw rendered.error;
+              }
+              lines.push(`${key}=${rendered.value}`);
+            }
+            continue;
+          }
+
+          const rendered = stringifyUnitValue(value as UnitValue);
+          if (!rendered.ok) {
+            throw rendered.error;
+          }
+          lines.push(`${key}=${rendered.value}`);
+        }
+
+        if (lines.length === 0) {
+          return [];
+        }
+
+        return [`[${sectionName}]`, ...lines, ``];
+      })
+      .join(`\n`);
+
+    return {
+      ok: true,
+      value: renderedSections.endsWith(`\n`) ? renderedSections : `${renderedSections}\n`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error:
+        error instanceof ExecutableInferenceError
+          ? error
+          : new ExecutableInferenceError({ cause: error }),
+    };
+  }
+}
+
+export async function defaultCommandExecutor(
+  command: string,
+  args: readonly string[],
+  options: CommandExecutionOptions = {},
+): Promise<CommandOutput> {
+  const result = await execFileAsync(
+    command,
+    [...args],
+    options.env === undefined ? {} : { env: { ...process.env, ...options.env } },
+  );
+  return {
+    stderr: result.stderr,
+    stdout: result.stdout,
+  };
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function sendNotify(
+  state: `READY=1` | `WATCHDOG=1`,
+  options: NotifyOptions,
+): Promise<void> {
+  const args: string[] = [`--no-block`, state];
+  if (options.pid !== undefined) {
+    args.push(`MAINPID=${options.pid}`);
+  }
+  if (options.status !== undefined) {
+    args.push(`STATUS=${options.status}`);
+  }
+
+  if (options.executor !== undefined) {
+    try {
+      await options.executor(
+        `systemd-notify`,
+        args,
+        options.socketPath === undefined ? {} : { env: { NOTIFY_SOCKET: options.socketPath } },
+      );
+    } catch (cause) {
+      throw new NotifySendError(
+        `Failed to send systemd notification through the configured executor`,
+        {
+          args,
+          cause,
+          command: `systemd-notify`,
+          reason: `executor-failed`,
+          stage: `executor`,
+        },
+      );
+    }
+    return;
+  }
+
+  try {
+    const result = await execFileAsync(`systemd-notify`, args, {
+      env: {
+        ...process.env,
+        ...(options.socketPath === undefined ? {} : { NOTIFY_SOCKET: options.socketPath }),
+      },
+    });
+
+    void result;
+  } catch (cause) {
+    throw new NotifySendError(`Failed to send systemd notification with systemd-notify`, {
+      args,
+      cause,
+      command: `systemd-notify`,
+      reason: `systemd-notify-failed`,
+      stage: `systemd-notify`,
+    });
+  }
+}
+
+export function extractCommandOutput(cause: unknown): CommandOutput | undefined {
+  if (cause === null || typeof cause !== `object`) {
+    return undefined;
+  }
+
+  const record = cause as Record<string, unknown>;
+  const stdout = typeof record[`stdout`] === `string` ? record[`stdout`] : undefined;
+  const stderr = typeof record[`stderr`] === `string` ? record[`stderr`] : undefined;
+  if (stdout === undefined && stderr === undefined) {
+    return undefined;
+  }
+
+  return {
+    stderr: stderr ?? ``,
+    stdout: stdout ?? ``,
+  };
+}
+
+function hasServiceSection(
+  options: SystemdServiceOptions | SystemdTimerOptions,
+): options is SystemdServiceOptions {
+  return `service` in options;
+}
+
+function hasTimerSection(
+  options: SystemdServiceOptions | SystemdTimerOptions,
+): options is SystemdTimerOptions {
+  return `timer` in options;
+}
+
+function assertAbsoluteExecValue(
+  key: ExecDirectiveKey,
+  value: unknown,
+): Result<void, InvalidExecDirectiveError> {
+  if (isUnitValueList(value)) {
+    for (const entry of value) {
+      const validation = assertAbsoluteExecEntry(key, entry);
+      if (!validation.ok) {
+        return validation;
+      }
+    }
+
+    return {
+      ok: true,
+      value: undefined,
+    };
+  }
+
+  return assertAbsoluteExecEntry(key, value as UnitValue | undefined);
+}
+
+function assertAbsoluteExecEntry(
+  key: ExecDirectiveKey,
+  value: UnitValue | undefined,
+): Result<void, InvalidExecDirectiveError> {
+  if (typeof value === `string` && value.length > 0 && !isAbsoluteExecCommand(value)) {
+    return {
+      ok: false,
+      error: new InvalidExecDirectiveError(key),
+    };
+  }
+
+  if (value instanceof Executable && !value.runtimeEntrypoint.startsWith(`/`)) {
+    return {
+      ok: false,
+      error: new InvalidExecDirectiveError(key),
+    };
+  }
+
+  return {
+    ok: true,
+    value: undefined,
+  };
+}
+
+function stringifyUnitValue(value: UnitValue): Result<string, ExecutableInferenceError> {
+  if (value instanceof Executable) {
+    return value.toExecStart();
+  }
+
+  if (typeof value === `boolean`) {
+    return {
+      ok: true,
+      value: value ? `true` : `false`,
+    };
+  }
+
+  return {
+    ok: true,
+    value: String(value),
+  };
+}
+
+function isUnitValueList(value: unknown): value is readonly UnitValue[] {
+  return Array.isArray(value);
+}
+
+function isAbsoluteExecCommand(value: string): boolean {
+  let index = 0;
+  let hasPrivilegePrefix = false;
+
+  while (index < value.length) {
+    const prefix = value[index];
+    if (prefix === `@` || prefix === `-` || prefix === `:`) {
+      index += 1;
+      continue;
+    }
+
+    if (prefix === `+`) {
+      if (hasPrivilegePrefix) {
+        return false;
+      }
+
+      hasPrivilegePrefix = true;
+      index += 1;
+      continue;
+    }
+
+    if (prefix === `!`) {
+      if (hasPrivilegePrefix) {
+        return false;
+      }
+
+      hasPrivilegePrefix = true;
+      index += value[index + 1] === `!` ? 2 : 1;
+      continue;
+    }
+
+    break;
+  }
+
+  return value[index] === `/`;
+}

package/src/main/notify.ts

@@ -0,0 +1,67 @@
+import { NotifySendError } from "./errors.ts";
+import { sendNotify, type Result } from "./internal.ts";
+import type { NotifyOptions } from "./types.ts";
+
+/**
+ * Helpers for sending `sd_notify` state updates to systemd.
+ *
+ * These helpers send notification payloads to the socket identified by
+ * `NOTIFY_SOCKET`, or to `options.socketPath` when one is provided explicitly.
+ * They are useful both in real services and in tests that want to observe
+ * readiness or watchdog traffic directly.
+ *
+ * Source:
+ * - https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+ * - https://www.freedesktop.org/software/systemd/man/latest/systemd-notify.html
+ */
+export const notify = {
+  /**
+   * Sends `READY=1` to systemd.
+   *
+   * Use this when a `Type=notify` service has completed its startup work and is
+   * ready to be considered fully started. If `options.status` is provided, it is
+   * sent as an additional `STATUS=...` field.
+   */
+  async ready(options: NotifyOptions = {}): Promise<Result<void, NotifySendError>> {
+    try {
+      await sendNotify(`READY=1`, options);
+      return { ok: true, value: undefined };
+    } catch (error) {
+      return {
+        ok: false,
+        error:
+          error instanceof NotifySendError
+            ? error
+            : new NotifySendError(`Failed to send READY=1 notification`, {
+                cause: error,
+                stage: `ready`,
+              }),
+      };
+    }
+  },
+
+  /**
+   * Sends `WATCHDOG=1` to systemd.
+   *
+   * Use this when a service configured with `WatchdogSec=` needs to emit a
+   * watchdog heartbeat. If `options.pid` is provided, it is sent as
+   * `MAINPID=...`, and `options.status` is forwarded as `STATUS=...`.
+   */
+  async watchdog(options: NotifyOptions = {}): Promise<Result<void, NotifySendError>> {
+    try {
+      await sendNotify(`WATCHDOG=1`, options);
+      return { ok: true, value: undefined };
+    } catch (error) {
+      return {
+        ok: false,
+        error:
+          error instanceof NotifySendError
+            ? error
+            : new NotifySendError(`Failed to send WATCHDOG=1 notification`, {
+                cause: error,
+                stage: `watchdog`,
+              }),
+      };
+    }
+  },
+};