systemd-ml/lib/systemd.mli

(** [Systemd] is a module for interacting with the {{:https://systemd.io/}systemd} service manager.
    It provides functions for most common systemd functionality, such as the protocols for
    detecting systemd/journald presence, startup/status notifications, the file descriptor store,
    and the watchdog. See also {!Systemd_xlog} for integration with {!Xlog} to log via journald *)

(** [is_systemd_booted env] checks if the current system is running on systemd. [env] is the Eio
    environment from [Eio_main.run] *)
val is_systemd_booted : Eio_unix.Stdenv.base -> bool

(** [is_in_systemd ()] checks if the program was started as a systemd service *)
val is_in_systemd : unit -> bool

(** [invocation_id ()] returns the systemd invocation ID if the program was started using systemd,
    or if it is the child of a systemd service that has not unset the environment variable *)
val invocation_id : unit -> string

(** [is_journald_attached ()] checks if the program is currently connected to a journald stream.
    This can indicate the ability to upgrade to rich log messages, eg with {!Systemd_xlog}. *)
val is_journald_attached : unit -> bool

(** [Systemd.Dirs] provides convenience functions for various directories passed in by systemd *)
module Dirs : sig

  (** When started with a [RuntimeDirectory=] option, provides the runtime directory given by
      systemd *)
  val runtime_dir : unit -> string

  (** When started with a [StateDirectory=] option, provides the state directory given by systemd *)
  val state_dir : unit -> string

  (** When started with a [CacheDirectory=] option, provides the cache directory given by systemd *)
  val cache_dir : unit -> string

  (** When started with a [LogsDirectory=] option, provides the logs directory given by systemd *)
  val logs_dir : unit -> string

  (** When started with a [ConfigurationDirectory=] option, provides the configuration directory
      given by systemd *)
  val configuration_dir : unit -> string

  (** When started with a [LoadCredential=] or [LoadCredentialEncrypted=] option, provides the
      directory with the credentials given by systemd *)
  val credentials_dir : unit -> string
end

(** [Systemd.Notify] implements the notification protocol to inform systemd of service readiness
    and other state changes *)
module Notify : sig

  (** Holds context for using this module *)
  type t

  (** [Notify.make ~sw ~env] creates a new notify context, which must be passed to the other
      functions in this module. [sw] is a [Eio.Switch] which will register the resources associated
      with the context, and [env] is the Eio environment from [Eio_main.run] *)
  val make :
    sw:Eio.Switch.t ->
    env:Eio_unix.Stdenv.base -> t

  (** [Notify.notify t ~fds msg] sends [msg] and optionally file descriptors in [fds] to systemd.
      This is a low-level function and should only be used if the convenience functions in this
      module do not provide the functionality you need. In particular, [fds] should only be set
      if [msg] corresponds to a command that accepts file descriptors. *)
  val notify :
    t ->
    ?fds:Eio_unix.Fd.t list ->
    string -> unit

  (** [Notify.ready t] tells systemd that this program has finished initialization and can be
      considered fully operational. An optional [status] can be sent containing a status message.
      Status messages should not contain any newlines.
      [mainpid] corresponds to the [MAINPID=] field of the underlying notification command and is
      typically not needed. *)
  val ready :
    ?status:string option ->
    ?mainpid:int ->
    t -> unit

  (** [Notify.send_status t status] updates the status message of this program as reported by
      systemd to the given text. Note that status messages should not contain any newlines. *)
  val send_status :
    t ->
    string -> unit

  (** [Notify.send_status_errno t status errno] is like [Notify.send_status t status] but contains
      an additional [Unix.error] corresponding to some error condition encountered by the program. *)
  val send_status_errno :
    t ->
    string ->
    Unix.error -> unit

  (** [Notify.reloading t] reports that the program is currently reloading its configuration.
      If used, [Notify.ready t] must be called at some point to report completion. *)
  val reloading : t -> unit
    
  (** [Notify.stopping t] reports that the program is stopping. The program should exit soon after
      calling this function. *)
  val stopping : t -> unit

  (** Represents the different values of the systemd [NotifyAccess=] setting. *)
  module NotifyAccess : sig

    (** Possible values for systemd [NotifyAccess=] *)
    type t =
    | None (** ["none"] *)
    | Main (** ["main"] *)
    | Exec (** ["exec"] *)
    | All (** ["all"] *)

    (** [to_string t] returns the systemd-compatible string representation of [t] *)
    val to_string : t -> string
  end

  (** [Notify.update_access t acc] changes the access setting for the notification socket,
      overriding the systemd [NotifyAccess=] setting *)
  val update_access :
    t ->
    NotifyAccess.t -> unit

  (** [Notify.extend_timeout t span] attempts to add a duration [span] to the
      current startup, runtime or shutdown service timeout. A further notification message must be
      sent within the duration specified by [span]. *)
  val extend_timeout :
    t ->
    Mtime.Span.t -> unit

  (** [Notify.barrier t] performs a barrier protocol to synchronize systemd with the program. Once
      this function returns, systemd is guaranteed to have processed all notification messages sent
      before this function was called. *)
  val barrier : t -> unit
end

(** [Systemd.Watchdog] implements the systemd watchdog protocol, when the program is used with eg
    [WatchdogSec=] *)
module Watchdog : sig

  (** [Watchdog.get_interval_opt ()] returns either the interval on which the program must send
      watchdog notifications, or [None] if the watchdog is not enabled *)
  val get_interval_opt : unit -> Mtime.Span.t option

  (** [Watchdog.pet t] sends a keep-alive notification to systemd *)
  val pet : Notify.t -> unit

  (** [Watchdog.trigger t] tells systemd to trigger the watchdog action, as if a failure has
      occurred *)
  val trigger : Notify.t -> unit

  (** [Watchdog.set_watchdog_time t span] updates the watchdog interval to [span] *)
  val set_watchdog_time :
    Notify.t ->
    Mtime.Span.t -> unit
end

(** [Systemd.Fdstore] implements the systemd
    {{:https://systemd.io/FILE_DESCRIPTOR_STORE/}file descriptor store} and socket-passing protocol,
    when relevent options are enabled *)
module Fdstore : sig

  (** [Fdstore.is_valid_fdname s] checks if [s] is a valid fdstore name according to systemd *)
  val is_valid_fdname : string -> bool

  (** [Fdstore.get_fd_limit ()] retrieves the maximum number of file descriptors that can be stored
      with systemd. Returns 0 if fdstore is not enabled *)
  val get_fd_limit : unit -> int

  (** [Fdstore.store t name fd] registers [fd] with [name] in the systemd fdstore. If
      [poll=false] then systemd will not automatically remove the fd when it's closed, so it must
      be manually unregistered. *)
  val store :
    Notify.t ->
    string ->
    ?poll:bool ->
    Eio_unix.Fd.t -> unit

  (** [Fdstore.remove t name] removes any file descriptor previously registered with [name] from
      systemd *)
  val remove :
    Notify.t ->
    string -> unit

  (** [Fdstore.listen_fds ~sw] returns a list of file descriptors passed into this process by
      systemd. This can be fds previously registered with [Fdstore.store], or fds associatd with
      systemd socket activation (or both). The fds get registered with Eio Switch [sw]. Environment
      variables corresponding to this fd-passing protocol get unset when this function completes. *)
  val listen_fds :
    sw:Eio.Switch.t ->
    (string option * Eio_unix.Fd.t) list
end

module MemPressure : sig
  val memory_trim : unit -> unit
end