KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #ai #dsh-plugin #ai-agent #mcp #deepseek-harness #windows

release

★ 51 Open GitHub ↗

A multi-process daemon framework for OCaml

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Release

## Introduction

Release is a multi-process daemon framework for OCaml with support for
asynchronous computation, providing facilities for type-safe inter-process
communication and privilege-dropping.

Its goal is to make it easy to write servers that are released from the calling
terminal and to release root privileges when those are not necessary.

In this documentation, any mention of a "thread" refers to a lightweight thread in an asynchronous computation library such as Async or Lwt.

All quotes are from the Pearl Jam song _Release - Master/Slave_ :)

## Build and installation

After cloning the repository, run the commands below to build Release. You can
built it with support for Async, Lwt or both.

$ ocaml setup.ml -configure --enable-async --enable-lwt
    $ ocaml setup.ml -build

Documentation can be generated with the command below.

$ ocaml setup.ml -doc

To install Release, run

# ocaml setup.ml -install

## Opening the appropriate library

Release is not a complete library, but a functor that can be instantiated when
given a module with signature `Release_future.S` that provides asynchronous
computation capabilities, also known as "futures". Two sub-libraries are
included with Release: `release.async` and `release.lwt`, providing
implementations for the two popular OCaml libraries.

The modules mentioned in the documentation below all live inside either
`Release_async` or `Release_lwt`, depending on your library of choice. It is
assumed that these modules have been `open`ed at the top of your code.

Function signatures below will use types from the `Future` module. The actual
types depend on the asynchronous computation library being used:

* `Future.t` is `Deferred.t` in Async and `Lwt.t` in Lwt;
* `Future.Unix.fd` is `Fd.t` in Async and `Lwt_unix.file_descr` in Lwt;
* `Future.Logger.t` is `Log.t` in Async and `Lwt_log.logger` in Lwt;

## Forking daemons

> Oh dear dad
> Can you see me now
> I am myself
> Like you somehow

The simplest way to use the library is to simply daemonize a process. Release
provides an Lwt-enabled function to do this in the `Release` module.

val daemon : (unit -> unit Future.t) -> unit Future.t

Upon calling `Release.daemon f`, the usual steps to create a daemon
process will be executed.

1.  The `umask` will be set to 0;
2.  `fork` will be called;
3.  The parent process exits;
4.  The child process calls `setsid`, ignores the `SIGHUP` and `SIGPIPE`
    signals, calls `fork` again and exits.
5.  The grandchild process changes the working directory to `/`, redirects
    `stdin`, `stdout` and `stderr` to `/dev/null` and finally calls `f`.

## Master/slave processes

A common pattern when writing multi-process servers is to have a master process
and _n_ slave processes. Usually the master process runs as a privileged user,
while the slaves run unprivileged. This allows one to design a server such
that the bulk of the code runs as a normal user in a slave process, and a
minimum amount of code that actually requires root privileges is implemented
in the master process. Thus, in case of a bug, the likelihood that it can be
exploited with root escalation is considerably decreased.

Consider the type of an inter-process communication callback function, defined
as `Release.IPC.handler`:

type handler = (Future.Unix.fd -> unit Future.t)

The simple case of a master process and one slave process is implemented in
the function `Release.master_slave`.

val master_slave :
         slave:((string * string array) * Release.IPC.handler)
      -> ?background:bool
      -> ?logger:Future.Logger.t
      -> ?privileged:bool
      -> ?slave_env:[`Inherit | `Keep of string list]
      -> ?control:(string * Release.IPC.handler)
      -> ?main:((unit -> (int * IPC.connection) list) -> unit Future.t)
      -> lock_file:string
      -> unit -> unit

The `slave` argument is a tuple whose first argument is the path to the slave
process executable. The second argument is a callback function that is used by
the master to handle inter-process communication with the slave. This function
receives the file descriptor to be used as a communication channel with the
slave process. More details about slave processes and IPC in Release will be
described in more details below.

The `background` argument indicates whether `Release.daemon` will be called.
The `logger` argument provides a logging facility for the master process.
If the master process is supposed to run as root, then the `privileged` argument
must be set to `true`. The slave process environment variables can be controlled
by the `slave_env` argument; they can be inherited from the master process, or
filtered via a whitelist of variable names. By default, only the `OCAMLRUNPARAM`
environment variable is passed to slave processes.

The `master_slave` function will create a lock file in the path given in the
`lock_file` argument. This file will contain the PID of the master process.
If the lock file already exists and contains the PID of a running process,
the master process will refuse to start.

The `control` argument consists of a tuple specifying the path to a Unix socket
and a callback function. The master process will create and listen on this
socket on startup. This is useful for the implementation of control programs
that communicate with the master process.

If given, the `main` callback function argument will be called with a function
that returns a list of PID and file descriptors pairs corresponding to the
currently running slave processes and the IPC sockets that can be used by the
master process for communication.
This list can be useful to implement broadcast-style messaging from the master
to the slaves.

The general case of _n_ slave processes is handled by the function
`Release.master_slaves`.

val master_slaves :
         ?background:bool
      -> ?logger:Future.Logger.t
      -> ?privileged:bool
      -> ?slave_env:[`Inherit | `Keep of string list]
      -> ?control:(string * Release.IPC.handler)
      -> ?main:((unit -> (int * IPC.connection) list) -> unit Future.t)
      -> lock_file:string
      -> slaves:((string * string array) * Release.IPC.handler * int) list
      -> unit -> unit

This function generalizes `Release.master_slave`, allowing the creation of
heterogeneous groups of slave process via the `slaves` argument. This argument
is a list of 3-element tuples containing the path to the slave executables,
the IPC callback function and the number of processes that will be created for
the given executable.

### Slaves

> I'll ride the wave
> Where it takes me
> I'll hold the pain
> Release me

When a slave process is run, some code must be run in order to setup
communication with the master, and also to drop privileges to a non-root user.
The `Release.me` function deals with this:

val me : ?logger:Future.Logger.t
          -> ?user:string
          -> main:(IPC.connection -> unit Future.t)
          -> unit -> unit

The `logger` argument works like in `master_slave`, but for the slave process.
The `user` argument, if given, indicates the user whose UID and GID the slave
process will set its own IDs to. This argument can only be given is `privileged`
is `true` in the master process.

The `main` argument is a function that returns the slave's main thread. It
accepts a file descriptor for communication with the master process.

### Inter-process communication

> I'll wait up in the dark
> For you to speak to me

Inter-process communication in `Release` is handled in a type-safe manner in
the module `Release.IPC`.

The `Release.IPC.Make` functor receives as an argument a module with the
following signature.

module type Ops = sig
      type request
      type response

val string_of_request : request -> string
      val request_of_string : string -> request

val string_of_response : response -> string
      val response_of_string : string -> response
    end

The types `request` and `response` correspond to the respective IPC operations,
and the convertion functions of requests and responses to and from strings
must be provided.

The output of `Release.IPC.Make` is a module with the signature below.

module type S = sig
      type request
      type response

module Server : sig
        val read_request : ?timeout:float
                        -> IPC.connection
                        -> [`Request of request | `EOF | `Timeout] Future.t

val write_response : IPC.connection -> response -> unit Future.t

val handle_request : ?timeout:float
                          -> ?eof_warning:bool
                          -> connection
                          -> (request -> response Future.t)
                          -> unit Future.t
      end

module Client : sig
        val read_response : ?timeout:float
                         -> connection
                         -> [`Response of response | `EOF | `Timeout] Future.t

val write_request : connection -> request -> unit Future.t

val make_request : ?timeout:float
                        -> connection
                        -> request
                        -> ([`Response of response | `EOF | `Timeout] ->
                             'a Future.t)
                        -> 'a Future.t
      end
    end

The functions `read` and `write` will perform these operations on the IPC file
descriptor given as an argument, and operate on buffers.

The `read_{request,response}` and `write_{request,response}` are the building
blocks for interprocess communication, respectively reading and writing IPC
requests and responses.

The functions `make_request` and `handle_request` are IPC wrappers around
the functions above. A slave process can call `make_request conn req handler` to
make an IPC request to the master process and wait for a response, which will
be passed as an argument to the `handler` callback. The master process can call
`handle_request conn handler` to wait for an IPC request from a slave. This
request will be passed to the callback function, which must return a response
that will be written back to the slave.

#### Control sockets

It may be useful for slaves to have control sockets like the one available
to the master process. This can be useful for writing control programs or for
communication between slave processes. The `Release.IPC` module provides the
`control_socket` function to help setting up the socket and spawning a handler
thread.

val control_socket : string -> IPC.handler -> unit Future.t

#### The IPC protocol

Release uses a very simple IPC protocol. This information is not necessary for
writing applications using this library, but it is useful for creating control
programs or scripts in languages other than OCaml, which can't use Release
(see the `control` argument described above).

Every Release IPC message consists of a 4-byte field containing the length of
the payload portion of the message and a payload field of variable length.
Thus, a message containing the payload string "hello" will have the length field
set to `5` (the length of the string) and the payload field will be the string
itself.

Higher-level protocols are left for the library users to implement according
to the needs of their respective applications.

## Extras

### The `Release.Buffer` module

This module provides a buffer whose implementation is based on the asynchronous
computation library's buffer type, usually based on OCaml's `Bigarray` module,
to minimize data copying. It is used by Release in its I/O functions.

Please check the `ocamldoc` documentation for the module interface.

### The `Release.IO` module

This module exports utility I/O functions that are useful when dealing with
network I/O. The functions in this module are based on the `Release.Buffer.t`
type, which has already appeared in some function signatures in the IPC module.

The first function in the module is `Release.IO.read_once`. It has similar
semantics to the usual `Unix.read`, but works on `Release.Buffer.t`.

val read_once : Future.Unix.fd
                 -> Release.Buffer.t
                 -> int
                 -> int
                 -> int Future.t

Calling `Release.IO.read_once fd buf off n` will read at most `n` bytes
from `fd` and store them into `buf` starting at offset `off`. This function
is safe against temporary errors, retrying on `Unix.EINTR` and `Unix.EAGAIN`
automatically.

The second function is `Release.IO.read`, which has the following signature.

val read : ?timeout:float
            -> Future.Unix.fd
            -> int
            -> [`Data of Release.Buffer.t | `EOF | `Timeout] Future.t

Calling `Release.IO.read fd n` will try to read at most `n` bytes from `fd`,
returning the appropriate result. Like `Release.IO.read_once`, this function
is safe against temporary errors.

The third function is `Release.IO.write`.

val write : Future.Unix.fd -> Release.Buffer.t -> unit Future.t

Calling `Release.IO.write fd buf` will ensure that the full length of buffer
`buf` is written on file descriptor `fd`. This function is also safe against
`Unix.EINTR` and `Unix.EAGAIN`.

### The `Release.Socket` module

Sockets in `Release` are modelled after Async's `Unix.Socket.t` type, which
use OCaml's type system encode the socket state and address type. In module
`Release.Socket`, the type is defined as

type unix = [ `Unix of string ]
    type inet = [ `Inet of Unix.inet_addr * int ]
    type addr = [ unix | inet ]
    type ('state, 'addr) t
      constraint 'state = [< `Unconnected | `Bound | `Passive | `Active ]
      constraint 'addr  = [< addr ]

This module contains utility socket functions. Currently the only exported
function is `Release.Socket.accept_loop`.

val accept_loop : ?backlog:int
                   -> ?timeout:float
                   -> ([`Unconnected], 'addr) Release.Socket.t
                   -> 'addr
                   -> (([`Active], 'addr) t -> unit Future.t)
                   -> unit Future.t

This function implements a traditional accept loop, spawning one thread per
client connection. The function creates a socket of the specified type, binds
it to the given address and listens for client connections. When a new
connection is accepted, the callback function given as the last argument is
executed in a separate thread (which may be interrupted depending on the
`timeout` argument), while `accept_loop` goes back to wait for new connections.

## Other Release sub-modules

### The `Release.Bytes` module

When writing network-based daemons, the need to implement some kind of binary
protocol is very common. Very often, these protocols have numeric fields that
must be read or written by the application. Since the network I/O functions
take buffers as arguments, the need to perform integer reads writes from and
into buffers, respectively, is quite frequent.

The Release library offers the `Release.Bytes` module to help in such
conversions. This module contains a set of functions that take a buffer as an
argument and read or write integers of various sizes at a given offset on the
buffer. The functions that read and write single bytes are available directly
`Release.Bytes`, while functions for integers of other sizes can be accessed
from the modules `Release.Bytes.Big_endian` and `Release.Bytes.Little_endian`.

The functions available in `Release.Bytes`, with their respective
signatures, are listed below.

* `val read_byte_at : int -> Release.Buffer.t -> int`
* `val read_byte : Release.Buffer.t -> int`
* `val write_byte : int -> Release.Buffer.t -> unit`

The following functions are available in both `Release.Bytes.Little_endian` and
`Release.Bytes.Little_endian`.

* `val read_int16_at : int -> Release.Buffer.t -> int`
* `val read_int16 : Release.Buffer.t -> int`
* `val write_int16_byte : int -> Release.Buffer.t -> unit`
* `val write_int16 : int -> Release.Buffer.t -> unit`

* `val read_int_at : int -> Release.Buffer.t -> int`
* `val read_int : Release.Buffer.t -> int`
* `val write_int_byte : int -> Release.Buffer.t -> unit`
* `val write_int : int -> Release.Buffer.t -> unit`

* `val read_int32_at : int -> Release.Buffer.t -> int32`
* `val read_int32 : Release.Buffer.t -> int32`
* `val write_int32_byte : int32 -> Release.Buffer.t -> unit`
* `val write_int32 : int32 -> Release.Buffer.t -> unit`

* `val read_uint32_at : int -> Release.Buffer.t -> Uint32.t`
* `val read_uint32 : Release.Buffer.t -> Uint32.t`
* `val write_uint32_byte : Uint32.t -> Release.Buffer.t -> unit`
* `val write_uint32 : Uint32.t -> Release.Buffer.t -> unit`

* `val read_int64_at : int -> Release.Buffer.t -> int64`
* `val read_int64 : Release.Buffer.t -> int64`
* `val write_int64_byte : int64 -> Release.Buffer.t -> unit`
* `val write_int64 : int64 -> Release.Buffer.t -> unit`

* `val read_uint64_at : int -> Release.Buffer.t -> Uint64.t`
* `val read_uint64 : Release.Buffer.t -> Uint64.t`
* `val write_uint64_byte : Uint64.t -> Release.Buffer.t -> unit`
* `val write_uint64 : Uint64.t -> Release.Buffer.t -> unit`

* `val read_uint128_at : int -> Release.Buffer.t -> Uint128.t`
* `val read_uint128 : Release.Buffer.t -> Uint128.t`
* `val write_uint128_byte : Uint128.t -> Release.Buffer.t -> unit`
* `val write_uint128 : Uint128.t -> Release.Buffer.t -> unit`

### The `Release.Config` module

This module provides an interface to help dealing with configuration files in
Release applications. A Release configuration file uses a simple `key = value`
format with support for sections, similar to `.ini` configuration files.

`Release.Config` values can be integers, floats, strings, booleans, regular
expressions, custom keywords or lists containing one of those types.
Configuration files are validated against a specification provided by the
application, which states the default value, if any, and a list of validations
for each configuration directive.

The `Release.Config.Default` module provides some helpers for setting default
values in configuration specifications:

* `Default.keyword`
* `Default.bool`
* `Default.int`
* `Default.float`
* `Default.string`
* `Default.regexp`
* `Default.keyword_list`
* `Default.bool_list`
* `Default.int_list`
* `Default.float_list`
* `Default.string_list`

The `Release.Config.Validation` module provides helpers for specifying
validation lists in a configuration:

* `keyword`: value must be the given keyword
* `keywords`: value must be one of the given keywords
* `bool`: the value is a boolean
* `int`: the value is an integer
* `float`: the value is a float
* `string`: the value is a string
* `regexp`: the value is a regular expression
* `bool_list`: the value is a list of booleans
* `int_list`: the value is a list of integers
* `float_list`: the value is a list of floats
* `string_list`: the value is a list of strings
* `int_in_range`: the value is an integer in the given inclusive range
* `int_greater_than`: the value is greater than the given integer
* `int_less_than`: the value is less than the given integer
* `float_in_range`: the value is a float in the given range
* `float_greater_than`: the value is greater than the given float
* `float_less_than`: the value is less than the given float
* `string_matching`: the value matches a regexp built from the given string
* `int_in`: the value is one of the integers in the given list
* `string_in`: the value is one of the strings in the given list
* `existing_file`: the value is an existing file
* `nonempty_file`: the value is a non-empty file
* `file_with_mode`: the value is a file with the given mode
* `file_with_owner`: the value is a file with the given owner
* `file_with_group`: the value is a file with the given group
* `existing_directory`: the value is an existing directory
* `existing_dirname`: the values's directory name of exists
* `block_device`: the value is a block device
* `character_device`: the value is a character device
* `symbolic_link`: the value is a symbolic link
* `named_pipe`: the value is a named pipe
* `unix_socket`: the value is a socket
* `existing_user`: the value is an existing user
* `unprivileged_user`: the value is a non-root user
* `existing_group`: the value is an existing group
* `list_of`: the value is a list of values passing the given validation

Please refer to the `ocamldoc` documentation for the types of the above helpers.

Configuration specifications are values of type `Release.Config.spec`,
constructed as below.

module Validation = struct
      type t = Value.t -> [`Valid | `Invalid of string]
    end

type key = string * Value.t option * Validation.t list

type section =
      [ `Global of key list
      | `Section of (string * key list)
      ]

type spec = section list

Below is an example of a configuration specification and its respective
configuration file.

open Release.Config.Value
    open Release.Config.Validation

let spec =
      [ `Global (* Settings which don't belong to any section *)
          [ "user", None (* required parameter *), [unprivileged_user]
          ; "privileged", Default.bool true, [bool]
          ; "read_timeout", Default.int 5, int_in_range (0, 10)
          ; "log_level", Default.keyword "info", [keywords ["debug"; "info"; "error"]]
          ]
      ; `Section ("some-section",
          [ "match_with", Default.regexp /^[a-z]+$/, [regexp]
          ; "tmp", Default.string "/tmp", one_of_strings ["/tmp"; "/var/tmp"]
          ])
      ; `Section ("another-section",
          [ "privileged_users", Default.string_list ["root"], [list_of existing_user]
          ])
      ]

With the specification above, every parameter can be ommited, with the exception
of the first global directive, which has no default value and therefore must
be present in the file.

Below is a possible configuration file that matches the above specification.

# Global settings
    user         = "foo"  # string
    privileged   = false  # boolean
    read_timeout = 1      # integer
    log_level    = debug  # log_level

[some-section]  # section declaration
    match_with  = /^.+$/  # regular expression
    tmp         = "/tmp"  # string

[another-section]  # another section declaration
    privileged_users = ["root", "admin"]  # list of strings

release

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README