Expand lifecycle APIs and unit validation

Author: dannote

README.md

@@ -36,7 +36,7 @@ The package depends on [`rebus`](https://hex.pm/packages/rebus) for the D-Bus wi
 
 APIs return idiomatic `{:ok, value}` / `{:error, %Systemd.Error{}}` tuples. Permission and polkit failures are classified with `category: :permission` and can be checked with `Systemd.Error.permission?/1`.
 
-See `examples/` for service, timer, and user-bus snippets, and `guides/xamal-style-deployment.md` for a deployment-oriented template unit example.
+See `examples/` for service, timer, and user-bus snippets, `guides/dbus-manager.md` for D-Bus manager operations, and `guides/xamal-style-deployment.md` for a deployment-oriented template unit example.
 
 ## Permissions
 

guides/dbus-manager.md

@@ -0,0 +1,76 @@
+# D-Bus manager operations
+
+`systemdkit` talks to `org.freedesktop.systemd1` over D-Bus and returns
+idiomatic `{:ok, value}` / `{:error, %Systemd.Error{}}` tuples. It does not
+retry through `sudo` or shell out to `systemctl`.
+
+## Short-lived connections
+
+Use the top-level `Systemd` module for one-off operations:
+
+```elixir
+{:ok, units} = Systemd.list_units()
+{:ok, jobs} = Systemd.list_jobs()
+{:ok, unit_files} = Systemd.list_unit_files()
+{:ok, state} = Systemd.unit_file_state("sshd.service")
+
+:ok = Systemd.reload()
+:ok = Systemd.start_unit("my_app@4000.service")
+:ok = Systemd.reload_or_restart_unit("my_app@4000.service")
+:ok = Systemd.reset_failed_unit("my_app@4000.service")
+```
+
+Mutating operations may fail with a policy or polkit error:
+
+```elixir
+case Systemd.start_unit("my_app@4000.service") do
+  :ok -> :ok
+  {:error, error} ->
+    if Systemd.Error.permission?(error) do
+      # Ask the operator to run with suitable policy/root privileges.
+      {:error, :permission_denied}
+    else
+      {:error, error}
+    end
+end
+```
+
+## Reusing a connection
+
+For multiple calls, keep a D-Bus connection open:
+
+```elixir
+Systemd.with_connection([], fn conn ->
+  with {:ok, unit} <- Systemd.Manager.get_unit(conn, "dbus.service"),
+       {:ok, state} <- Systemd.UnitObject.state(conn, unit),
+       {:ok, jobs} <- Systemd.Manager.list_jobs(conn) do
+    {:ok, {state, jobs}}
+  end
+end)
+```
+
+## Job tracking
+
+Unit lifecycle methods return jobs through `Systemd.Manager`. Top-level helpers
+wait for jobs by default; pass `wait: false` to inspect the job yourself:
+
+```elixir
+{:ok, conn} = Systemd.Manager.connect()
+{:ok, job} = Systemd.Manager.restart_unit(conn, "my_app@4000.service")
+{:ok, :running} = Systemd.Job.state(conn, job)
+:ok = Systemd.Job.await(conn, job, timeout: 10_000)
+```
+
+Jobs can be cancelled through the job object when systemd still exposes it:
+
+```elixir
+Systemd.Job.cancel(conn, job)
+```
+
+## User bus
+
+Pass `bus: :session` for user units when a systemd user session bus is available:
+
+```elixir
+Systemd.list_units(bus: :session)
+```

lib/systemd.ex

@@ -61,6 +61,14 @@ defmodule Systemd do
     with_connection(opts, &Manager.list_units/1)
   end
 
+  @doc """
+  Lists queued jobs using a short-lived connection.
+  """
+  @spec list_jobs(keyword()) :: {:ok, [Systemd.JobStatus.t()]} | {:error, Error.t()}
+  def list_jobs(opts \\ []) do
+    with_connection(opts, &Manager.list_jobs/1)
+  end
+
   @doc """
   Reads common state for a unit using a short-lived connection.
   """
@@ -121,6 +129,49 @@ defmodule Systemd do
     run_unit_operation(:reload_unit, name, opts)
   end
 
+  @doc """
+  Tries to restart a unit only if it is already active.
+  """
+  @spec try_restart_unit(String.t(), keyword()) ::
+          :ok | {:ok, Systemd.Job.t()} | {:error, Error.t()}
+  def try_restart_unit(name, opts \\ []) do
+    run_unit_operation(:try_restart_unit, name, opts)
+  end
+
+  @doc """
+  Reloads a unit if supported, otherwise restarts it.
+  """
+  @spec reload_or_restart_unit(String.t(), keyword()) ::
+          :ok | {:ok, Systemd.Job.t()} | {:error, Error.t()}
+  def reload_or_restart_unit(name, opts \\ []) do
+    run_unit_operation(:reload_or_restart_unit, name, opts)
+  end
+
+  @doc """
+  Reloads a unit if supported, otherwise tries to restart it only if active.
+  """
+  @spec reload_or_try_restart_unit(String.t(), keyword()) ::
+          :ok | {:ok, Systemd.Job.t()} | {:error, Error.t()}
+  def reload_or_try_restart_unit(name, opts \\ []) do
+    run_unit_operation(:reload_or_try_restart_unit, name, opts)
+  end
+
+  @doc """
+  Resets failed state for a unit using a short-lived connection.
+  """
+  @spec reset_failed_unit(String.t(), keyword()) :: :ok | {:error, Error.t()}
+  def reset_failed_unit(name, opts \\ []) do
+    with_connection(opts, &Manager.reset_failed_unit(&1, name))
+  end
+
+  @doc """
+  Sends a Unix signal to processes belonging to a unit using a short-lived connection.
+  """
+  @spec kill_unit(String.t(), String.t(), integer(), keyword()) :: :ok | {:error, Error.t()}
+  def kill_unit(name, who \\ "all", signal \\ 15, opts \\ []) do
+    with_connection(opts, &Manager.kill_unit(&1, name, who, signal))
+  end
+
   @doc """
   Enables unit files using a short-lived connection.
   """

lib/systemd/dbus/signature.ex

@@ -4,6 +4,7 @@ defmodule Systemd.DBus.Signature do
   @supported_complex_signatures MapSet.new([
                                   "a(ssssssouso)",
                                   "a(ss)",
+                                  "a(usssoo)",
                                   "a{sv}",
                                   "a(sv)",
                                   "a(sa(sv))",

lib/systemd/job.ex

@@ -3,7 +3,7 @@ defmodule Systemd.Job do
   A systemd job returned by manager operations such as `StartUnit`.
   """
 
-  alias Systemd.{Error, Properties}
+  alias Systemd.{DBus, Error, Properties}
 
   @interface "org.freedesktop.systemd1.Job"
 
@@ -25,6 +25,32 @@ defmodule Systemd.Job do
     Properties.get(conn, path, @interface, property)
   end
 
+  @doc """
+  Cancels this job through its D-Bus object.
+  """
+  @spec cancel(pid(), t()) :: :ok | {:error, Error.t()}
+  def cancel(conn, %__MODULE__{object_path: path}) do
+    with {:ok, []} <-
+           DBus.call_body(conn,
+             destination: "org.freedesktop.systemd1",
+             path: path,
+             interface: @interface,
+             member: "Cancel"
+           ) do
+      :ok
+    end
+  end
+
+  @doc """
+  Reads and normalizes the job state.
+  """
+  @spec state(pid(), t()) :: {:ok, state()} | {:error, Error.t()}
+  def state(conn, job) do
+    with {:ok, value} <- property(conn, job, "State") do
+      {:ok, normalize_state(value)}
+    end
+  end
+
   @doc """
   Polls until a job leaves `waiting`/`running` or disappears from the bus.
   """
@@ -58,12 +84,6 @@ defmodule Systemd.Job do
     end
   end
 
-  defp state(conn, job) do
-    with {:ok, value} <- property(conn, job, "State") do
-      {:ok, normalize_state(value)}
-    end
-  end
-
   defp normalize_state("waiting"), do: :waiting
   defp normalize_state("running"), do: :running
   defp normalize_state("done"), do: :done

lib/systemd/job_status.ex

@@ -0,0 +1,34 @@
+defmodule Systemd.JobStatus do
+  @moduledoc """
+  Runtime job information returned by systemd's `ListJobs` D-Bus method.
+  """
+
+  @enforce_keys [:id, :unit, :type, :state, :job_path, :unit_path]
+  @type t :: %__MODULE__{
+          id: non_neg_integer(),
+          unit: String.t(),
+          type: String.t(),
+          state: String.t(),
+          job_path: String.t(),
+          unit_path: String.t()
+        }
+
+  defstruct [:id, :unit, :type, :state, :job_path, :unit_path]
+
+  @doc false
+  @spec from_dbus(tuple() | list()) :: t()
+  def from_dbus({id, unit, type, state, job_path, unit_path}) do
+    from_dbus([id, unit, type, state, job_path, unit_path])
+  end
+
+  def from_dbus([id, unit, type, state, job_path, unit_path]) do
+    %__MODULE__{
+      id: id,
+      unit: unit,
+      type: type,
+      state: state,
+      job_path: job_path,
+      unit_path: unit_path
+    }
+  end
+end

lib/systemd/manager.ex

@@ -3,7 +3,7 @@ defmodule Systemd.Manager do
   Client for `org.freedesktop.systemd1.Manager`.
   """
 
-  alias Systemd.{DBus, Error, Job, Unit, UnitFileOperation, UnitFileStatus, UnitObject}
+  alias Systemd.{DBus, Error, Job, JobStatus, Unit, UnitFileOperation, UnitFileStatus, UnitObject}
   alias Systemd.Manager.Options
   alias Systemd.TransientUnit.{AuxUnit, Property}
 
@@ -41,6 +41,16 @@ defmodule Systemd.Manager do
     end
   end
 
+  @doc """
+  Lists currently queued jobs.
+  """
+  @spec list_jobs(pid()) :: {:ok, [JobStatus.t()]} | {:error, Error.t()}
+  def list_jobs(conn) when is_pid(conn) do
+    with {:ok, [jobs]} <- call(conn, "ListJobs") do
+      {:ok, Enum.map(jobs, &JobStatus.from_dbus/1)}
+    end
+  end
+
   @doc """
   Gets the D-Bus object path for a loaded unit.
   """
@@ -113,6 +123,51 @@ defmodule Systemd.Manager do
     unit_operation(conn, "ReloadUnit", unit_name, opts)
   end
 
+  @doc """
+  Tries to restart a unit only if it is already active.
+  """
+  @spec try_restart_unit(pid(), String.t(), keyword()) :: {:ok, Job.t()} | {:error, Error.t()}
+  def try_restart_unit(conn, unit_name, opts \\ []) do
+    unit_operation(conn, "TryRestartUnit", unit_name, opts)
+  end
+
+  @doc """
+  Reloads a unit if supported, otherwise restarts it.
+  """
+  @spec reload_or_restart_unit(pid(), String.t(), keyword()) ::
+          {:ok, Job.t()} | {:error, Error.t()}
+  def reload_or_restart_unit(conn, unit_name, opts \\ []) do
+    unit_operation(conn, "ReloadOrRestartUnit", unit_name, opts)
+  end
+
+  @doc """
+  Reloads a unit if supported, otherwise tries to restart it only if active.
+  """
+  @spec reload_or_try_restart_unit(pid(), String.t(), keyword()) ::
+          {:ok, Job.t()} | {:error, Error.t()}
+  def reload_or_try_restart_unit(conn, unit_name, opts \\ []) do
+    unit_operation(conn, "ReloadOrTryRestartUnit", unit_name, opts)
+  end
+
+  @doc """
+  Resets failed state for a unit.
+  """
+  @spec reset_failed_unit(pid(), String.t()) :: :ok | {:error, Error.t()}
+  def reset_failed_unit(conn, unit_name) when is_pid(conn) and is_binary(unit_name) do
+    with {:ok, []} <- call(conn, "ResetFailedUnit", [unit_name], "s"), do: :ok
+  end
+
+  @doc """
+  Sends a Unix signal to processes belonging to a unit.
+  """
+  @spec kill_unit(pid(), String.t(), String.t(), integer()) :: :ok | {:error, Error.t()}
+  def kill_unit(conn, unit_name, who \\ "all", signal \\ 15)
+
+  def kill_unit(conn, unit_name, who, signal)
+      when is_pid(conn) and is_binary(unit_name) and is_binary(who) and is_integer(signal) do
+    with {:ok, []} <- call(conn, "KillUnit", [unit_name, who, signal], "ssi"), do: :ok
+  end
+
   @doc """
   Starts a transient unit and returns the queued systemd job.
   """

lib/systemd/unit_file.ex

@@ -32,6 +32,24 @@ defmodule Systemd.UnitFile do
   @spec timer(keyword()) :: t()
   defdelegate timer(opts), to: Builder
 
+  @doc """
+  Builds a mount unit file from common `Unit`, `Mount`, and `Install` sections.
+  """
+  @spec mount(keyword()) :: t()
+  defdelegate mount(opts), to: Builder
+
+  @doc """
+  Builds a path unit file from common `Unit`, `Path`, and `Install` sections.
+  """
+  @spec path(keyword()) :: t()
+  defdelegate path(opts), to: Builder
+
+  @doc """
+  Builds a target unit file from common `Unit`, `Target`, and `Install` sections.
+  """
+  @spec target(keyword()) :: t()
+  defdelegate target(opts), to: Builder
+
   @doc """
   Parses unit file text.
   """

lib/systemd/unit_file/builder.ex

@@ -70,6 +70,39 @@ defmodule Systemd.UnitFile.Builder do
     |> maybe_append_section("Install", Keyword.get(opts, :install, []))
   end
 
+  @doc """
+  Builds a mount unit file from common `Unit`, `Mount`, and `Install` sections.
+  """
+  @spec mount(keyword()) :: UnitFile.t()
+  def mount(opts) when is_list(opts) do
+    UnitFile.parse!("")
+    |> maybe_append_section("Unit", Keyword.get(opts, :unit, []))
+    |> maybe_append_section("Mount", Keyword.get(opts, :mount, []))
+    |> maybe_append_section("Install", Keyword.get(opts, :install, []))
+  end
+
+  @doc """
+  Builds a path unit file from common `Unit`, `Path`, and `Install` sections.
+  """
+  @spec path(keyword()) :: UnitFile.t()
+  def path(opts) when is_list(opts) do
+    UnitFile.parse!("")
+    |> maybe_append_section("Unit", Keyword.get(opts, :unit, []))
+    |> maybe_append_section("Path", Keyword.get(opts, :path, []))
+    |> maybe_append_section("Install", Keyword.get(opts, :install, []))
+  end
+
+  @doc """
+  Builds a target unit file from common `Unit`, `Target`, and `Install` sections.
+  """
+  @spec target(keyword()) :: UnitFile.t()
+  def target(opts) when is_list(opts) do
+    UnitFile.parse!("")
+    |> maybe_append_section("Unit", Keyword.get(opts, :unit, []))
+    |> maybe_append_section("Target", Keyword.get(opts, :target, []))
+    |> maybe_append_section("Install", Keyword.get(opts, :install, []))
+  end
+
   @doc """
   Builds a unit file with one section.
   """