Expand validation and release readiness

Author: dannote

README.md

@@ -9,6 +9,7 @@ The current spike exposes a small D-Bus backed manager client:
 {:ok, units} = Systemd.Manager.list_units(conn)
 {:ok, unit} = Systemd.Manager.get_unit(conn, "dbus.service")
 {:ok, state} = Systemd.UnitObject.state(conn, unit)
+{:ok, service_state} = Systemd.UnitObject.service_state(conn, unit)
 ```
 
 It also includes a NimbleParsec-backed unit file parser/generator:
@@ -43,7 +44,7 @@ Systemd.list_units(bus: :session)
 
 ## Unit files
 
-`Systemd.UnitFile` preserves comments, blank lines, duplicate directives, reset directives, and source spans. Validation is intentionally separate from parsing:
+`Systemd.UnitFile` preserves comments, blank lines, duplicate directives, reset directives, and source spans. Validation is intentionally separate from parsing and includes directive-specific value checks for common service, socket, timer, and install keys:
 
 ```elixir
 unit_file = Systemd.UnitFile.parse!("[Service]\nExecStart=/bin/true\n")
@@ -65,9 +66,17 @@ cd /Users/dannote/Development/systemd
 SYSTEMD_INTEGRATION=1 mix test
 ```
 
+Or from macOS, copy the source into the VM and run the full integration suite:
+
+```sh
+scripts/integration_test.sh
+```
+
 Quick VM checks:
 
 ```sh
 ~/.local/bin/limactl shell systemd-test -- systemctl is-system-running
 ~/.local/bin/limactl shell systemd-test -- busctl --system list --no-pager
 ```
+
+See `docs/RELEASE_CHECKLIST.md` before publishing a release.

docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,11 @@
+# Release Checklist
+
+Before publishing a pre-release or Hex package:
+
+- Run `mix ci` locally.
+- Run `mix docs` and inspect generated module examples.
+- Run `scripts/integration_test.sh` against the Lima systemd VM.
+- Confirm public APIs return `{:ok, value}` or `{:error, %Systemd.Error{}}`.
+- Confirm mutating D-Bus calls classify permission and polkit failures as `:permission`.
+- Review package metadata in `mix.exs` for version, links, licenses, and files.
+- Tag the release from a clean git working tree.

lib/systemd.ex

@@ -4,6 +4,24 @@ defmodule Systemd do
 
   The package provides a D-Bus backed manager client, unit object/property APIs,
   job awaiting, installation helpers, and a loss-aware unit file parser/generator.
+
+  ## Examples
+
+      {:ok, units} = Systemd.list_units()
+      :ok = Systemd.start_unit("example.service")
+      {:ok, state} = Systemd.unit_state("dbus.service")
+
+      unit_file =
+        Systemd.UnitFile.service(
+          unit: [description: "Example"],
+          service: [exec_start: "/bin/true", type: :oneshot],
+          install: [wanted_by: "multi-user.target"]
+        )
+
+      :ok = Systemd.UnitFile.validate(unit_file, :service)
+
+  Mutating calls can return `{:error, %Systemd.Error{category: :permission}}`
+  when systemd or polkit denies the D-Bus operation.
   """
 
   alias Systemd.{Error, Manager}
@@ -46,7 +64,7 @@ defmodule Systemd do
   @doc """
   Reads common state for a unit using a short-lived connection.
   """
-  @spec unit_state(String.t(), keyword()) :: {:ok, map()} | {:error, Error.t()}
+  @spec unit_state(String.t(), keyword()) :: {:ok, Systemd.UnitState.t()} | {:error, Error.t()}
   def unit_state(name, opts \\ []) do
     with_connection(opts, fn conn ->
       with {:ok, unit} <- Manager.get_unit(conn, name) do

lib/systemd/dbus.ex

@@ -8,7 +8,7 @@ defmodule Systemd.DBus do
 
   alias Rebus.Connection
   alias Rebus.Message
-  alias Systemd.DBus.Result
+  alias Systemd.DBus.{Result, Signature}
   alias Systemd.Error
 
   @type bus ::
@@ -42,7 +42,8 @@ defmodule Systemd.DBus do
   """
   @spec call(pid(), [call_option()]) :: {:ok, Result.t()} | {:error, Error.t()}
   def call(conn, opts) when is_pid(conn) and is_list(opts) do
-    with {:ok, message} <- message(opts) do
+    with :ok <- validate_signature(opts),
+         {:ok, message} <- message(opts) do
       send_message(conn, message)
     end
   end
@@ -55,6 +56,16 @@ defmodule Systemd.DBus do
     with {:ok, %Result{body: body}} <- call(conn, opts), do: {:ok, body}
   end
 
+  defp validate_signature(opts) do
+    signature = Keyword.get(opts, :signature, "")
+
+    if Signature.supported?(signature) do
+      :ok
+    else
+      {:error, Error.encoding_error({:unsupported_signature, signature})}
+    end
+  end
+
   defp message(opts) do
     Message.new(:method_call,
       destination: Keyword.fetch!(opts, :destination),

lib/systemd/dbus/signature.ex

@@ -0,0 +1,23 @@
+defmodule Systemd.DBus.Signature do
+  @moduledoc false
+
+  @supported_complex_signatures MapSet.new([
+                                  "a(ssssssouso)",
+                                  "a{sv}",
+                                  "a(sv)",
+                                  "a(sa(sv))",
+                                  "ssa(sv)a(sa(sv))"
+                                ])
+
+  @doc false
+  @spec supported?(String.t()) :: boolean()
+  def supported?(signature) when is_binary(signature) do
+    primitive?(signature) or MapSet.member?(@supported_complex_signatures, signature)
+  end
+
+  defp primitive?(""), do: true
+
+  defp primitive?(signature) do
+    String.match?(signature, ~r/^[syobintqxuagdvh]+$/)
+  end
+end

lib/systemd/service_state.ex

@@ -0,0 +1,27 @@
+defmodule Systemd.ServiceState do
+  @moduledoc """
+  Common state properties for a systemd service object.
+  """
+
+  @type t :: %__MODULE__{
+          type: String.t() | nil,
+          result: String.t() | nil,
+          exec_main_pid: non_neg_integer() | nil,
+          exec_main_status: non_neg_integer() | nil,
+          restart: String.t() | nil
+        }
+
+  defstruct [:type, :result, :exec_main_pid, :exec_main_status, :restart]
+
+  @doc false
+  @spec from_properties(map()) :: t()
+  def from_properties(properties) when is_map(properties) do
+    %__MODULE__{
+      type: Map.get(properties, "Type"),
+      result: Map.get(properties, "Result"),
+      exec_main_pid: Map.get(properties, "ExecMainPID"),
+      exec_main_status: Map.get(properties, "ExecMainStatus"),
+      restart: Map.get(properties, "Restart")
+    }
+  end
+end

lib/systemd/socket_state.ex

@@ -0,0 +1,25 @@
+defmodule Systemd.SocketState do
+  @moduledoc """
+  Common state properties for a systemd socket object.
+  """
+
+  @type t :: %__MODULE__{
+          result: String.t() | nil,
+          listen: [term()] | nil,
+          accept: boolean() | nil,
+          n_connections: non_neg_integer() | nil
+        }
+
+  defstruct [:result, :listen, :accept, :n_connections]
+
+  @doc false
+  @spec from_properties(map()) :: t()
+  def from_properties(properties) when is_map(properties) do
+    %__MODULE__{
+      result: Map.get(properties, "Result"),
+      listen: Map.get(properties, "Listen"),
+      accept: Map.get(properties, "Accept"),
+      n_connections: Map.get(properties, "NConnections")
+    }
+  end
+end

lib/systemd/timer_state.ex

@@ -0,0 +1,27 @@
+defmodule Systemd.TimerState do
+  @moduledoc """
+  Common state properties for a systemd timer object.
+  """
+
+  @type t :: %__MODULE__{
+          result: String.t() | nil,
+          unit: String.t() | nil,
+          next_elapse_usec_realtime: non_neg_integer() | nil,
+          last_trigger_usec: non_neg_integer() | nil,
+          timers_calendar: [term()] | nil
+        }
+
+  defstruct [:result, :unit, :next_elapse_usec_realtime, :last_trigger_usec, :timers_calendar]
+
+  @doc false
+  @spec from_properties(map()) :: t()
+  def from_properties(properties) when is_map(properties) do
+    %__MODULE__{
+      result: Map.get(properties, "Result"),
+      unit: Map.get(properties, "Unit"),
+      next_elapse_usec_realtime: Map.get(properties, "NextElapseUSecRealtime"),
+      last_trigger_usec: Map.get(properties, "LastTriggerUSec"),
+      timers_calendar: Map.get(properties, "TimersCalendar")
+    }
+  end
+end