configuration domain (general)

This is the runtime configuration for a casual domain.

The sections can be splitted in arbitrary ways, and aggregated to one configuration model casual uses. Same sections can be defined in different files, hence, give more or less unlimited configuration setup.

Most of the sections has a property note for the user to provide descriptions of the documentation. The examples further down uses this to make it easier to understand the examples by them self. But can of course be used as a mean to help document actual production configuration.

structures

General “structures” that other parts of the configuration refers to.

Duration : string

A string representation of a duration. SI units can be used. Example: 30ms, 1h, 3min, 40s. if no SI unit s is used

domain::service::Visibility : string

A string representation that defines the visibility of a service

value

description

discoverable

service is discoverable from other domains

undiscoverable

service is not discoverable from other domains

domain::service::timeout::Contract : string

A string representation that defines the timeout contract. Can be one of the following:

value

severity

description

linger

non-lethal

no action, let the server be

interrupt

non-lethal

send interrupt signal as a tap on the shoulder

kill

lethal

send kill signal

abort

lethal

send ‘abort’ signal

domain::service::Timeout (structure)

property

description

default

[duration : Duration]

timeout duration for a service.

no duration

[contract : Contract]

action to take if timeout is passed

linger

domain::environment::Variable (structure)

property

description

key : string

environment variable name

value : string

the value to associate with the environment variable

domain::Environment (structure)

property

description

[variables : [Variable]]

environment variables

[files : [string]]

paths to files that contains Environment

Note: a file referred from files must contain the structure.

environment:
  variables:
    - key: "SOME_VARIABLE"
      value: "foo"
  files:
    - "another-file.json"

And has corresponding extension as the format (my-environment.json, env.yaml and so on).

domain.global

Defines domain global configuration.

domain.global.service

domain global settings for services. This will effect services that are not otherwise configured explicitly,

property

description

[execution.timeout : Timeout]

global default timeout

domain.default

‘default’ configuration. Will be used as fallback within a configuration. Will not aggregate ‘between’ configurations. Only used to help user minimize common configuration.

domain.default.server

property

description

default

[instances : integer]

default number of instances.

1

[memberships : [string]]

default group memberships.

[environment : Environment]

default server environment

[restart : boolean]

default restart directive

false

domain.default.executable

property

description

default

[instances : integer]

default number of instances.

1

[memberships : [string]]

default group memberships.

[environment : Environment]

default server environment

[restart : boolean]

default restart directive

false

domain.default.service

property

description

default

[execution.timeout : Timeout]

default service timeout

domain.global.service.execution.timeout

[visibility : Visibility]

visibility from other domains

discoverable

domain.groups (list)

Defines the groups in the configuration. Groups are used define dependency order, which is used during boot and shutdown. Arbitrary number of groups and group hierarchies can be defined. Groups can be used to associate resources to servers/executables.

property

description

default

name : string

the name (unique key) of the group.

[dependencies : [string]]

name of groups this group has dependency to.

[resources : [string]]

names of resources this group is associated with

[enabled : boolean]

if the group is enabled or not see below

true

[enabled : boolean]

This property enables or disables the group. This could enable/disable entities that has membership to the group.

For an entity to be enabled: ALL explicit and implicit membership groups has enabled: true

For an entity to be disabled: ANY explicit and implicit membership groups has enabled: false

Entities effected:

  • domain.executables

  • domain.servers

  • queue.forward.groups

domain.servers (list)

Defines all servers of the configuration (and domain)

property

description

default

path : string

the path to the binary (if not absolute, PATH is used)

[alias : string]

the logical (unique) name of the server.

basename( path)

[arguments : [string]]

arguments to tpsvrinit during startup.

[instances : integer]

number of instances to start of the server.

domain.default.server.instances

[memberships : [string]]

groups that the server is member of

domain.default.server.memberships

[environment : Environment]

explicit environments for instances of this server

domain.default.server.environment

[restrictions : [regex]]

regex patterns, only services that matches are advertised.

[resources : [string]]

explicit resource associations (resource names)

[restart : boolean]

if the server should be restarted, if exit.

domain.default.server.restart

domain.executables (list)

Defines all ordinary executables of the configuration. Could be any executable with a main function

property

description

default

path : string

the path to the binary (if not absolute, PATH is used)

[alias : string]

the logical (unique) name of the executable.

basename( path)

[arguments : [string]]

arguments to main during startup.

[instances : integer]

number of instances to start of the server.

domain.default.executable.instances

[memberships : [string]]

groups that the executable is member of

domain.default.executable.memberships

[environment : Environment]

explicit environments for instances of this executable

domain.default.executable.environment

[restart : boolean]

if the executable should be restarted, if exit.

domain.default.executable.restart

domain.services (list)

Defines service related configuration.

Note: This configuration is tied to the service, regardless who has advertised the service.

property

description

default

name : string

name of the service

[routes : [string]]

names to use instead of name.

[execution.timeout : Timeout]

timeout of the service

domain.default.service.execution.timeout

[visibility : Visibility]

visibility from other domains

domain.default.service.visibility

Note: For service aliases, it’s important to include the original name in routes

examples

Below follows examples in yaml and json (casual can also handle ini and xml)

yaml

---
domain:
  name: "domain-name"
  global:
    note: "'domain global' config. Aggregates right to left"
    service:
      note: "Will be used for services that are not explicitly configured."
      execution:
        timeout:
          duration: "2h"
          contract: "linger"
  default:
    note: "'default', fallback, configuration. Will only affect 'local' configuration and will not aggregate 'between' configurations"
    server:
      instances: 1
      restart: true
      memberships:
        - "customer-group"
      environment:
        variables:
          - key: "SOME_VARIABLE"
            value: "foo"
    executable:
      instances: 1
      restart: false
    service:
      execution:
        timeout:
          duration: "20s"
      visibility: "discoverable"
  environment:
    variables:
      - key: "SOME_VARIABLE"
        value: "42"
      - key: "SOME_OTHER_VARIABLE"
        value: "some value"
  groups:
    - name: "common-group"
      note: "group that logically groups 'common' stuff"
    - name: "customer-group"
      note: "group that logically groups 'customer' stuff"
      resources:
        - "customer-db"
      dependencies:
        - "common-group"
    - name: "sales-group"
      note: "group that logically groups 'customer' stuff"
      resources:
        - "sales-db"
        - "event-queue"
      dependencies:
        - "customer-group"
  servers:
    - path: "/some/path/customer-server-1"
      memberships:
        - "customer-group"
    - path: "/some/path/customer-server-2"
      memberships:
        - "customer-group"
    - path: "/some/path/sales-server"
      alias: "sales-pre"
      note: "the only services that will be advertised are the ones who matches regex \"preSales.*\""
      instances: 10
      memberships:
        - "sales-group"
      restrictions:
        - "preSales.*"
    - path: "/some/path/sales-server"
      alias: "sales-post"
      note: "he only services that will be advertised are the ones who matches regex \"postSales.*\""
      memberships:
        - "sales-group"
      restrictions:
        - "postSales.*"
    - path: "/some/path/sales-broker"
      memberships:
        - "sales-group"
      environment:
        variables:
          - key: "SALES_BROKER_VARIABLE"
            value: "556"
      resources:
        - "event-queue"
  executables:
    - path: "/some/path/mq-server"
      arguments:
        - "--configuration"
        - "/path/to/configuration"
      memberships:
        - "common-group"
  services:
    - name: "a"
      execution:
        timeout:
          duration: "64ms"
          contract: "abort"
      routes:
        - "b"
        - "c"
      visibility: "undiscoverable"
...

json

{
    "domain": {
        "name": "domain-name",
        "global": {
            "note": "'domain global' config. Aggregates right to left",
            "service": {
                "note": "Will be used for services that are not explicitly configured.",
                "execution": {
                    "timeout": {
                        "duration": "2h",
                        "contract": "linger"
                    }
                }
            }
        },
        "default": {
            "note": "'default', fallback, configuration. Will only affect 'local' configuration and will not aggregate 'between' configurations",
            "server": {
                "instances": 1,
                "restart": true,
                "memberships": [
                    "customer-group"
                ],
                "environment": {
                    "variables": [
                        {
                            "key": "SOME_VARIABLE",
                            "value": "foo"
                        }
                    ]
                }
            },
            "executable": {
                "instances": 1,
                "restart": false
            },
            "service": {
                "execution": {
                    "timeout": {
                        "duration": "20s"
                    }
                },
                "visibility": "discoverable"
            }
        },
        "environment": {
            "variables": [
                {
                    "key": "SOME_VARIABLE",
                    "value": "42"
                },
                {
                    "key": "SOME_OTHER_VARIABLE",
                    "value": "some value"
                }
            ]
        },
        "groups": [
            {
                "name": "common-group",
                "note": "group that logically groups 'common' stuff"
            },
            {
                "name": "customer-group",
                "note": "group that logically groups 'customer' stuff",
                "resources": [
                    "customer-db"
                ],
                "dependencies": [
                    "common-group"
                ]
            },
            {
                "name": "sales-group",
                "note": "group that logically groups 'customer' stuff",
                "resources": [
                    "sales-db",
                    "event-queue"
                ],
                "dependencies": [
                    "customer-group"
                ]
            }
        ],
        "servers": [
            {
                "path": "/some/path/customer-server-1",
                "memberships": [
                    "customer-group"
                ]
            },
            {
                "path": "/some/path/customer-server-2",
                "memberships": [
                    "customer-group"
                ]
            },
            {
                "path": "/some/path/sales-server",
                "alias": "sales-pre",
                "note": "the only services that will be advertised are the ones who matches regex \"preSales.*\"",
                "instances": 10,
                "memberships": [
                    "sales-group"
                ],
                "restrictions": [
                    "preSales.*"
                ]
            },
            {
                "path": "/some/path/sales-server",
                "alias": "sales-post",
                "note": "he only services that will be advertised are the ones who matches regex \"postSales.*\"",
                "memberships": [
                    "sales-group"
                ],
                "restrictions": [
                    "postSales.*"
                ]
            },
            {
                "path": "/some/path/sales-broker",
                "memberships": [
                    "sales-group"
                ],
                "environment": {
                    "variables": [
                        {
                            "key": "SALES_BROKER_VARIABLE",
                            "value": "556"
                        }
                    ]
                },
                "resources": [
                    "event-queue"
                ]
            }
        ],
        "executables": [
            {
                "path": "/some/path/mq-server",
                "arguments": [
                    "--configuration",
                    "/path/to/configuration"
                ],
                "memberships": [
                    "common-group"
                ]
            }
        ],
        "services": [
            {
                "name": "a",
                "execution": {
                    "timeout": {
                        "duration": "64ms",
                        "contract": "abort"
                    }
                },
                "routes": [
                    "b",
                    "c"
                ],
                "visibility": "undiscoverable"
            }
        ]
    }
}