# configuration gateway
[//]: # (Attention! this is a generated markdown from casual-configuration-documentation - do not edit this file!)
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.
## domain.gateway
Defines configuration for communication with other `casual` domains.
### domain.gateway.inbound
Defines all inbound related configuration (from remote domains -> local domain)
#### Limit _(structure)_
property | description
-------------------------|------------------------------------------
[size : `integer`] | max size in bytes
[messages : `integer`] | max number of messages in flight
#### domain.gateway.inbound.default
Will be used as default values for all groups.
property | description | default
-------------------------------------------|---------------------------------------------------|--------
[limit : `Limit`] | default value for limit |
[connection.discovery.forward : `boolean`] | if a discovery is allowed to propagate downstream | `false`
##### domain.gateway.inbound.groups.Connection _(structure)_
Defines a connection that this _inbound group_ should listen to
property | description | default
--------------------------------|---------------------------------------------------|---------
address : `string` | the address to listen on, `host:port` |
[discovery.forward : `boolean`] | if a discovery is allowed to propagate downstream | `domain.gateway.inbound.default.connection.discovery.forward`
#### domain.gateway.inbound.groups _(list)_
Defines a list of all inbound groups
property | description | default
-------------------------------|---------------------------------------|------------
[alias : `string`] | an _identity_ for this group instance | _generated unique name_
[limit : `Limit`] | upper limits of inflight messages | `domain.gateway.inbound.default.limit`
[connections : `[Connection]`] | all the connections for this group |
### domain.gateway.outbound
Defines all outbound related configuration (from local domain -> remote domains)
##### domain.gateway.outbound.groups.Connection _(structure)_
Defines a connection that this _outbound group_ should try to connect to.
property | description
-------------------------|----------------------------------------------------
address : `string` | the address to connect to, `host:port`
[services : `[string]`] | services we're expecting to find on the other side
[queues : `[string]`] | queues we're expecting to find on the other side
`services` and `queues` is used as an _optimization_ to do a _build_ discovery during startup. `casual`
will find these services later lazily otherwise. It can also be used to do some rudimentary load balancing
to make sure lower prioritized connections are used for `services` and `queues` that could be discovered in
higher prioritized connections.
#### domain.gateway.outbound.groups _(list)_
Each group gets an _order_ in the order they are defined. Groups defined lower down will only be used if the higher
ups does not provide the wanted _service_ or _queue_. Hence, the lower downs can be used as _fallback_.
property | description | default
-------------------------------|---------------------------------------|------------
[alias : `string`] | an _identity_ for this group instance | _generated unique name_
[connections : `[Connection]`] | all the connections for this group
All connections within a group ar treated equal, and service calls will be load balanced with _round robin_. Although,
`casual` will try to _route_ the same transaction to the previous _associated_ connection with the specific transaction.
This is only done to minimize the amount of _resources_ involved within the prepare and commit/rollback stage.
### domain.gateway.reverse
This section defines _reverse_ `inbound` and `outbound`. The connection phase is reversed.
* `outbound` connection listen to it's' configured address.
* `inbound` connections tries to connect to it's configured address.
Otherwise, the semantics and configuration are exactly the same.
### domain.gateway.reverse.inbound
Exactly the same as [domain.gateway.inbound](#domaingatewayinbound)
### domain.gateway.reverse.outbound
Exactly the same as [domain.gateway.outbound](#domaingatewayoutbound)
## examples
Below follows examples in `yaml` and `json` _(casual can also handle `ini` and `xml`)_
### yaml
```` yaml
---
domain:
gateway:
inbound:
default:
note: "discovery forward is disabled default."
connection:
discovery:
forward: false
groups:
- alias: "unique-inbound-alias"
note: "if threshold of 2MB of total payload 'in flight' is reach inbound will stop consume from socket until we're below"
limit:
size: 2097152
connections:
- address: "localhost:7778"
note: "can be several listening host:port per inbound instance"
- address: "some.host.org:7779"
discovery:
forward: true
note: "discovery will be forward to 'all' outbounds"
- note: "(generated alias) listeners - threshold of either 10 messages OR 10MB - the first that is reach, inbound will stop consume"
limit:
size: 10485760
messages: 10
connections:
- address: "some.host.org:7780"
- address: "some.host.org:4242"
- note: "(generated alias) listeners - no limits"
connections:
- address: "some.host.org:4242"
outbound:
groups:
- alias: "primary"
note: "casual will 'round-robin' between connections within a group for the same service/queue"
connections:
- address: "a45.domain.host.org:7779"
note: "connection to domain 'a45' - we expect to find service 's1' and 's2' there."
services:
- "s1"
- "s2"
- address: "a46.domain.host.org:7779"
note: "we expect to find queues 'q1' and 'q2' and service 's1'"
services:
- "s1"
queues:
- "q1"
- "q2"
- alias: "fallback"
connections:
- address: "a99.domain.host.org:7780"
note: "will be chosen if _resources_ are not found at connections in the 'primary' outbound"
reverse:
inbound:
groups:
- alias: "unique-alias-name"
note: "connect to other reverse outbound that is listening on this port - then treat it as a regular inbound"
limit:
messages: 42
connections:
- address: "localhost:7780"
note: "one of possible many addresses to connect to"
outbound:
groups:
- alias: "primary"
note: "listen for connection from reverse inbound - then treat it as a regular outbound"
connections:
- address: "localhost:7780"
note: "one of possible many listining addresses."
- alias: "secondary"
note: "onther instance (proces) that handles (multiplexed) traffic on it's own"
connections:
- address: "localhost:7781"
note: "one of possible many listining addresses."
...
````
### json
```` json
{
"domain": {
"gateway": {
"inbound": {
"default": {
"note": "discovery forward is disabled default.",
"connection": {
"discovery": {
"forward": false
}
}
},
"groups": [
{
"alias": "unique-inbound-alias",
"note": "if threshold of 2MB of total payload 'in flight' is reach inbound will stop consume from socket until we're below",
"limit": {
"size": 2097152
},
"connections": [
{
"address": "localhost:7778",
"note": "can be several listening host:port per inbound instance"
},
{
"address": "some.host.org:7779",
"discovery": {
"forward": true
},
"note": "discovery will be forward to 'all' outbounds"
}
]
},
{
"note": "(generated alias) listeners - threshold of either 10 messages OR 10MB - the first that is reach, inbound will stop consume",
"limit": {
"size": 10485760,
"messages": 10
},
"connections": [
{
"address": "some.host.org:7780"
},
{
"address": "some.host.org:4242"
}
]
},
{
"note": "(generated alias) listeners - no limits",
"connections": [
{
"address": "some.host.org:4242"
}
]
}
]
},
"outbound": {
"groups": [
{
"alias": "primary",
"note": "casual will 'round-robin' between connections within a group for the same service/queue",
"connections": [
{
"address": "a45.domain.host.org:7779",
"note": "connection to domain 'a45' - we expect to find service 's1' and 's2' there.",
"services": [
"s1",
"s2"
]
},
{
"address": "a46.domain.host.org:7779",
"note": "we expect to find queues 'q1' and 'q2' and service 's1'",
"services": [
"s1"
],
"queues": [
"q1",
"q2"
]
}
]
},
{
"alias": "fallback",
"connections": [
{
"address": "a99.domain.host.org:7780",
"note": "will be chosen if _resources_ are not found at connections in the 'primary' outbound"
}
]
}
]
},
"reverse": {
"inbound": {
"groups": [
{
"alias": "unique-alias-name",
"note": "connect to other reverse outbound that is listening on this port - then treat it as a regular inbound",
"limit": {
"messages": 42
},
"connections": [
{
"address": "localhost:7780",
"note": "one of possible many addresses to connect to"
}
]
}
]
},
"outbound": {
"groups": [
{
"alias": "primary",
"note": "listen for connection from reverse inbound - then treat it as a regular outbound",
"connections": [
{
"address": "localhost:7780",
"note": "one of possible many listining addresses."
}
]
},
{
"alias": "secondary",
"note": "onther instance (proces) that handles (multiplexed) traffic on it's own",
"connections": [
{
"address": "localhost:7781",
"note": "one of possible many listining addresses."
}
]
}
]
}
}
}
}
}
````