Service Shape

Source: core/service.gleam

The service shape defines the contract that all fixed-branch services must conform to. It is a minimal record type with a lifecycle interface used by the service supervisor to start, monitor, and stop services.

Type Definition

pub type Service {
  Service(
    name: String,
    supervised: Bool,
    start: fn() -> Result(Nil, String),
    stop: fn() -> Nil,
    health: fn() -> Bool,
  )
}

Field	Type	Description
name	String	Human-readable service name (used in logs and supervision reports)
supervised	Bool	If True, the service needs OTP process supervision; the supervisor spawns and monitors its process
start	fn() -> Result(Nil, String)	Boot function. Returns Ok(Nil) on success or Error(String) with a failure reason.
stop	fn() -> Nil	Graceful shutdown. Called during controlled shutdown or restart.
health	fn() -> Bool	Health check. True means the service is operational. Polled periodically by the supervisor.

Usage

The service supervisor (services/supervisor/supervisor.gleam) iterates over all registered Service values. For each one:

• If supervised is True, it starts the service as a supervised OTP child process
• If supervised is False, it calls start() directly and tracks the service without process supervision
• Periodically calls health() to detect failures
• Calls stop() during controlled shutdown or when restarting

Every fixed-branch service in src/services/ exports a function that returns a Service value conforming to this shape. This keeps service lifecycle management consistent and the supervisor generic.

Related Pages

• OTP Supervision -- The supervisor tree that manages service lifecycles
• Project Structure -- Where services live in the file tree