Module Ketrew.Configuration

module Configuration: sig .. end

type t 

The contents of a configuration.

type plugin = [ `Compiled of string | `OCamlfind of string ] 

The 2 kinds of dynamically loaded “plugins” accepted by Ketrew:

• `Compiled path: path to a `.cma` or `.cmxs` compiled file.
• `OCamlfind package: name of a Findlib package.

type explorer_defaults 

Configuration of the Explorer text-user-interface. These configuration values can be changed at runtime within the explorer; but they are not persistent in that case.

val default_explorer_defaults : explorer_defaults

The default values of the Explorer configuration.

val explorer : ?request_targets_ids:[ `All | `Younger_than of [ `Days of float ] ] ->
       ?targets_per_page:int ->
       ?targets_to_prefetch:int -> unit -> explorer_defaults

Create a configuration of the Explorer:

• request_targets_ids: is used to restrict how many targets are visible to the Explorer. The default value is `Younger_than (`Days 1.5).
• targets_per_page: how many targets to display in a given “page” (default 6).
• targets_to_prefetch: how many additional targets the Explorer should prefetch to speed-up navigation (default 6).

type ui 

General configuration of the text-based user interface.

val ui : ?with_color:bool ->
       ?explorer:explorer_defaults ->
       ?with_cbreak:bool -> unit -> ui

Create a configuration of the UI:

• with_color: ask Ketrew to use ANSI colors (default: true).
• explorer: the configuration of The Explorer (cf. Ketrew.Configuration.explorer).
• with_cbreak: should the UI use “cbreak” or not. When false, it reads from stdin classically (i.e. it waits for the return key to be pressed); when true, it gets the key-presses directly (it's the default but requires a compliant terminal).

type engine 

The configuration of the engine, the component that orchestrates the run of the targets (used both for the server mode).

val engine : ?turn_unix_ssh_failure_into_target_failure:bool ->
       ?host_timeout_upper_bound:float ->
       ?maximum_successive_attempts:int ->
       ?concurrent_automaton_steps:int ->
       ?engine_step_batch_size:int ->
       ?orphan_killing_wait:float ->
       database_parameters:string -> unit -> engine

Build an engine configuration:

• database_parameters: the URI used to connect to the database (e.g. "postgresql://example.com/db1").
• turn_unix_ssh_failure_into_target_failure: when an SSH or system call fails it may not mean that the command in your workflow is wrong (could be an SSH configuration or tunneling problem). By default (i.e. false), Ketrew tries to be clever and does not make targets fail. To change this behavior set the option to true.
• host_timeout_upper_bound: every connection/command timeout will be “≤ upper-bound” (in seconds, default is 60.).
• maximum_successive_attempts: number of successive non-fatal failures allowed before declaring a target dead (default is 10).
• concurrent_automaton_steps: maximum number of steps in the state machine that engine will try to run concurrently (default is 4).
• engine_step_batch_size: the maximal amount of nodes that the engine will process in a single “step” (default: 400 nodes).
• orphan_killing_wait: the minimal amount of time between 2 attempts at killing all “orphan nodes” (i.e. unreachable because all dependees are finished).

type authorized_tokens 

This type is a container for one more authentication-tokens, used by the server's HTTP API

Tokens have a name and a value; the value is the one checked against the "token" argument of the HTTP queries.

A token's value must consist only of "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_=".

val authorized_token : name:string -> string -> authorized_tokens

Create an “inline” authentication token, i.e. provide a name and a value directly.

val authorized_tokens_path : string -> authorized_tokens

Ask the server to load tokens from a file at the given path.

The file uses the SSH authorized_keys format. I.e. whitespace-separated lines of the form:

      <name> <token> <optional comments ...>
     

type server 

The configuration of the server.

val server : ?ui:ui ->
       ?authorized_tokens:authorized_tokens list ->
       ?return_error_messages:bool ->
       ?command_pipe:string ->
       ?log_path:string ->
       ?max_blocking_time:float ->
       ?read_only_mode:bool ->
       engine:engine ->
       [ `Tcp of int | `Tls of string * string * int ] ->
       [> `Server of server ]

Create a server configuration (to pass as optional argument to the Ketrew.Configuration.create function).

• authorized_tokens: cf. Ketrew.Configuration.authorized_token and Ketrew.Configuration.authorized_tokens_path.
• return_error_messages: whether the server should return explicit error messages to clients (default false).
• command_pipe: path to a named-piped for the server to listen to commands (this is optional but highly recommended).
• log_path: path to the server's log directory; if present (highly recommended), the server will dump JSON files containing the logs periodically. Moreover, the server redirect debug-style logs to a "debug.txt" file in that directory (if not set, debug info goes to "/dev/null" or stdout if available).
• max_blocking_time: upper bound on the request for blocking in the protocol (seconds, default 300.).
• read_only_mode: run the server in read-only mode (default false).
• `Tcp port: configure the server the unsercurely listen on port.
• `Tls ("certificate.pem", "privatekey.pem", port): configure the OpenSSL server to listen on port.

type client 

Configuration of the client (as in HTTP client).

val client : ?ui:ui ->
       token:string -> string -> [> `Client of client ]

Create a client configuration:

• ui: the configuration of the user-interface, cf. Ketrew.Configuration.ui.
• token: the authentication token to use to connect to the server (the argument is optional but nothing interesting can happen without it).
• the last argument is the connection URI, e.g. "https://example.com:8443".

type mode = [ `Client of client
       | `Server of server ] 

Union of the possible configuration “modes.”

val create : ?debug_level:int ->
       ?plugins:plugin list ->
       ?tmp_dir:string -> mode -> t

Create a complete configuration:

• debug_level: integer specifying the amount of verbosity (current useful values: 0 for quiet, 1 for verbose, 2 for extremely verbose —- ~debug_level:2 will slow down the engine noticeably).
• plugins: cf. Ketrew.Configuration.plugin.
• mode: cf. Ketrew.Configuration.client, and Ketrew.Configuration.server.
• tmp_dir: Temporary directory to use (the default is Filename.get_temp_dir_name ()).

type profile 

A profile is a name associated with a configuration.

val profile : string -> t -> profile

Create a profile value.

val output : profile list -> unit

Output a configuration file containing a list of profiles to stdout.

val to_json : profile list -> string

Create the contents of a configuration file containing a list of profiles.

val default_configuration_directory_path : string

Default path to the configuration directory ("~/.ketrew/").

val database_parameters : engine -> string

Get the database parameters.

val is_unix_ssh_failure_fatal : engine -> bool

Should we kill targets on ssh/unix errors.

val maximum_successive_attempts : engine -> int

Get the maximum number of successive non-fatal failures.

val concurrent_automaton_steps : engine -> int

Get the maximum number of concurrent automaton steps.

val host_timeout_upper_bound : engine -> float option

Get the upper bound for the timeout of SSH calls, if any.

val engine_step_batch_size : engine -> int

Get the amount of workflow-nodes treated by the engine in one automaton step.

val orphan_killing_wait : engine -> float

Get the minimal time between 2 “orphan-node killing sprees.”

val plugins : t -> plugin list

Get the configured list of plugins.

val mode : t -> mode

val server_engine : server -> engine

val server_configuration : t -> server option

Get the potentiel server configuration.

val authorized_tokens : server ->
       [ `Inline of string * string | `Path of string ] list

The path to the authorized_tokens file.

val listen_to : server ->
       [ `Tcp of int | `Tls of string * string * int ]

Get the OpenSSL-or-not server configuration.

val return_error_messages : server -> bool

Get the value of return_error_messages.

val command_pipe : server -> string option

Get the path to the “command” named pipe.

val log_path : server -> string option

Get the path to the server's log directory.

val log : t -> Ketrew_pure.Internal_pervasives.Log.t

Get a display-friendly list of configuration items.

val connection : client -> string

val token : client -> string

val with_color : t -> bool

val request_targets_ids : t -> [ `All | `Younger_than of [ `Days of float ] ]

val targets_per_page : t -> int

val targets_to_prefetch : t -> int

val max_blocking_time : server -> float

val read_only_mode : server -> bool

val use_cbreak : unit -> bool

See the documentation of with_cbreak.

val load_exn : ?and_apply:bool ->
       ?profile:string ->
       [ `From_path of string
       | `Guess
       | `In_directory of string
       | `Override of t ] -> t

Load a configuration.

If and_apply is true (the default), then global settings are applied and plugins are loaded.

When the configuration comes from a file, the argument profile allows to load a given profile. If None then the loading process will try the "KETREW_PROFILE" environment variable, or use the name "default".

The last argument tells the functions how to load the configuration:

• `Override c: use c as configuration
• `From_path path: parse the file path
• `In_directory root: look for configuration files in the root directory
• `Guess: use environment variables and/or default values to find the configuration file.