Skip to content
On this page

Bridge Relay

Generally speaking an edge router is a router located at a network boundary or on-premises (office, home) that enables an internal network to connect to external networks.

Description

A Bondy Edge router (edge or edge node) is an operational mode that enables Bondy to act as an edge router i.e. it connects to a Bondy remote cluster not as another cluster node but as an edge node, a special mode which allows it to extend the capabilities of Bondy routing to a subset of realms.

Synchronization

Edge connection establishing requires the synchronization of realm state between edge and remote.

Edge will synchronize:

  • Realm configuration state
    • Realm private keys should not be replicated.
      • So we would replicate only the realm's public signing (EC) and encryption (RSA) public keys.
    • The realm's prototype (if it is used by the edge's realm)
      • We need to copy the realm and its prototype which will have most of the group, source and grant definitions.
    • User data
      • User passwords should NOT be replicated (only authorized_keys i.e. cryptosign public keys)
    • Group data
    • Source data
    • Grant data
  • Realm registry state
    • Registrations
    • Subscriptions

The api described below is to be able to configure the proper Bondy Edge router.

Types

input_data()

A Bridge Relay object configuration has the following properties:

namestringREQUIREDIMMUTABLE
The name to be use as unique identifier for the bridge.
enabledbooleanREQUIRED
Whether the bridge is enabled.
endpointrequiredREQUIRED
The IP Address or Hostname and port e.g myhost:9075
transportstringREQUIREDIMMUTABLE
The connection transport. The allowed values are: tls and tcp.
Default: tcp
tls_optsobjectREQUIREDIMMUTABLE
Client certificate.
socket_optsobjectREQUIREDIMMUTABLE
Socket options.
parallelismintegerREQUIREDIMMUTABLE
Parallelism.
Default: 1
restartstringREQUIREDIMMUTABLE
Defines when a terminated bridge must be restarted. The allowed values are: permanent and transient. A permanent bridge is always restarted, even after recovering from a Bondy node crash or when the node is manually stopped and re-started. Bondy persists the configuration of permanent bridges in the database and reads them during startup. A transient bridge is restarted only if it terminated abnormally. In case of a node crash or manually stopped and re-started they will not be restarted.
Default: transient
idle_timeoutinteger | infinityREQUIREDIMMUTABLE
Time in milliseconds that Bondy will allow for a connection with no activity to be kept alive. Bondy will close the connection after this time. Default is 24 hours.
Default: 86400000
hibernatestringREQUIREDIMMUTABLE
Allowed values: never, idle and always.
Default: idle
connect_timeoutinteger | infinityREQUIREDIMMUTABLE
TCP connection timeout in milliseconds.
Default: 5000
network_timeoutinteger | infinityREQUIREDIMMUTABLE
Network connection timeout in milliseconds, waiing for network connected event.
Default: 30000
max_frame_sizeinteger | infinityREQUIREDIMMUTABLE
The maximum frame size in bytes.
Default: infinity
reconnectobjectREQUIREDIMMUTABLE
Enables or disables the reconnect feature. Once a connection is established but fails due to an unknown error or by the connecting being aborted by the remote with an error that is recoverable, we might want to ask Bondy to retry the connection e.g. when connecting with realm A the remote aborts the connection with reason `no_such_realm', in this case maybe the realm has not yet been provisioned, so we want the connection to retry indefinitely.
pingobjectREQUIREDIMMUTABLE
realmsarray[object]REQUIREDIMMUTABLE
The list of realm bridging configuration

Procedures

The following wamp api is used to configure and manage the proper Edge:

NameURI
Add a bridgebondy.router.bridge.add
Remove a bridgebondy.router.bridge.remove
Start a bridgebondy.router.bridge.start
Stop a bridgebondy.router.bridge.stop
Retrieve a bridgebondy.router.bridge.get
List all bridgesbondy.router.bridge.list
Check status of a bridgebondy.router.bridge.status
Check spec of a bridgebondy.router.bridge.check_spec

Add a bridge

bondy.router.bridge.add(input_data()) -> bridge()

Adds a Bridge Relay specification and optionally starts the bridge.

Call

Positional Args
0object
The bridge relay configuration data
Keyword Args
autostartboolean
If true immediately starts the bridge, otherwise the bridge should be started using bondy.router.bridge.start procedure.

Result

Positional Results
0object
The bridge relay object.
Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.add \
'{
    "name": "edge_test",
    "endpoint": "127.0.0.1:18093",
    "transport": "tls",
    "realms": [
        {
            "uri": "com.leapsight.test",
            "authid": "device1",
            "cryptosign": {
                "pubkey": "1766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd",
                "privkey": "4ffddd896a530ce5ee8c86b83b0d31835490a97a9cd718cb2f09c9fd31c4a7d71766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd"
            }
        }
    ],
    "reconnect": {"enabled":true},
    "ping": {"enabled":true}
}' --kwarg autostart=true | jq
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
  • Response:
json
{
  "connect_timeout": 5000,
  "enabled": false,
  "endpoint": "127.0.0.1:18093",
  "idle_timeout": 86400000,
  "max_frame_size": "infinity",
  "name": "edge_test",
  "parallelism": 1,
  "ping": {
    "enabled": true,
    "idle_timeout": 20000,
    "max_attemps": 2,
    "timeout": 10000
  },
  "realms": [
    {
      "authid": "device1",
      "cryptosign": {
        "privkey": "4ffddd896a530ce5ee8c86b83b0d31835490a97a9cd718cb2f09c9fd31c4a7d71766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd",
        "pubkey": "1766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd"
      },
      "procedures": [],
      "topics": [],
      "uri": "com.leapsight.test"
    }
  ],
  "reconnect": {
    "backoff_max": 60000,
    "backoff_min": 5000,
    "backoff_type": "jitter",
    "enabled": true,
    "max_retries": 100
  },
  "restart": "transient",
  "socket_opts": {
    "keepalive": true,
    "nodelay": true
  },
  "tls_opts": {
    "verify": "verify_none"
  },
  "transport": "tls",
  "type": "bridge_relay",
  "version": "1.0"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Remove a bridge

bondy.router.bridge.remove()

Removes the definition of a bridge from the bridge manager.

Returns an error if undefined or if the bridge is running, but no errors if the bridge doesn't exist or it is removed successfully.

Call

Positional Args
0stringREQUIRED
The name of the bridge.
Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.remove "edge_test"
1
2
3

Start a bridge

bondy.router.bridge.start(name())

Starts a bridge which has already been defined using bondy.router.bridge.add.

Call

Positional Args
0stringREQUIRED
The name of the bridge.
Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.start "edge_test"
1
2
3

Stop a bridge

bondy.router.bridge.stop(name())

Stops an existing running bridge.

Returns an error if the bridge is not running or undefined.

Call

Positional Args
0stringREQUIRED
The name of the bridge.
Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.stop "edge_test"
1
2
3

Retrieve a bridge

bondy.router.bridge.get(name()) -> bridge()

Retrieves a Bridge Object specification by name

Call

Positional Args
0stringREQUIRED
The name of the bridge.
Keyword Args

None.

Result

Positional Results
0object
The bridge relay object.
Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.get "edge_test" | jq
1
2
3
  • Response:
json
{
  "connect_timeout": 5000,
  "enabled": false,
  "endpoint": "127.0.0.1:18093",
  "hibernate": "idle",
  "idle_timeout": 86400000,
  "max_frame_size": "infinity",
  "name": "edge_test",
  "network_timeout": 30000,
  "parallelism": 1,
  "ping": {
    "enabled": true,
    "idle_timeout": 20000,
    "max_attempts": 2,
    "timeout": 10000
  },
  "realms": [
    {
      "authid": "device1",
      "cryptosign": {
        "privkey": "4ffddd896a530ce5ee8c86b83b0d31835490a97a9cd718cb2f09c9fd31c4a7d71766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd",
        "pubkey": "1766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd"
      },
      "procedures": [],
      "topics": [],
      "uri": "com.leapsight.test"
    }
  ],
  "reconnect": {
    "backoff_max": 60000,
    "backoff_min": 5000,
    "backoff_type": "jitter",
    "enabled": true,
    "max_retries": 100
  },
  "restart": "transient",
  "socket_opts": {
    "keepalive": true,
    "nodelay": true
  },
  "tls_opts": {
    "verify": "verify_none"
  },
  "transport": "tls",
  "type": "bridge_relay",
  "version": "1.0"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

List all bridges

bondy.router.bridge.list() -> [bridge()]

Returns a list of all installed bridges in the system.

Call

Positional Args

None.

Keyword Args

None.

Result

Positional Results
0array[object]
The all bridges you want to retrieve.
Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.list | jq
1
2
3
  • Response:
json
[
    {
        "connect_timeout": 5000,
        "enabled": false,
        "endpoint": "127.0.0.1:18093",
        "hibernate": "idle",
        "idle_timeout": 86400000,
        "max_frame_size": "infinity",
        "name": "edge_test",
        "network_timeout": 30000,
        "parallelism": 1,
        "ping": {
            "enabled": true,
            "idle_timeout": 20000,
            "max_attempts": 2,
            "timeout": 10000
        },
        "realms": [
            {
                "authid": "device1",
                "cryptosign": {
                    "privkey": "4ffddd896a530ce5ee8c86b83b0d31835490a97a9cd718cb2f09c9fd31c4a7d71766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd",
                    "pubkey": "1766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd"
                },
                "procedures": [],
                "topics": [],
                "uri": "com.leapsight.test"
            }
        ],
        "reconnect": {
            "backoff_max": 60000,
            "backoff_min": 5000,
            "backoff_type": "jitter",
            "enabled": true,
            "max_retries": 100
        },
        "restart": "transient",
        "socket_opts": {
            "keepalive": true,
            "nodelay": true
        },
        "tls_opts": {
            "verify": "verify_none"
        },
        "transport": "tls",
        "type": "bridge_relay",
        "version": "1.0"
    }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

Check status of a bridge

bondy.router.bridge.status() -> bridgeStatus()

Returns an object where the key is an installed bridge name and the value is the bridge status object.

The status object has the following properties:

  • status — The status of the bridge it can be:
    • not_started: The bridge was added but never started since the Bondy node started
    • stopped: The bridge was stopped
    • restarting: The bridge crashes and the supervisor is restarting it
    • running: The bridge is running

Call

Positional Args

None.

Keyword Args

None.

Result

Positional Results
statusstringREQUIREDIMMUTABLE
The status of the bridge.
Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.status | jq
1
2
3
  • Response:
json
{
    "edge_test": {
        "status": "not_started"
    }
}
1
2
3
4
5

Check spec of a bridge

bondy.router.bridge.check_spec(input()) -> bridge()

Checks the validity of a Bridge Relay Object.

Call

Positional Args
0object
The bridge relay configuration data
Keyword Args

None.

Result

Positional Results
0object
The bridge relay object.
Keyword Results

None.

Errors

Examples

Success Call
  • Request
bash
./wick --url ws://localhost:19080/ws \
--realm com.leapsight.bondy \
call bondy.router.bridge.check_spec \
'{
    "name": "edge_test",
    "endpoint": "127.0.0.1:18093",
    "realms": [
        {
            "uri": "com.leapsight.test",
            "authid": "device1",
            "cryptosign": {
                "pubkey": "1766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd",
                "privkey": "4ffddd896a530ce5ee8c86b83b0d31835490a97a9cd718cb2f09c9fd31c4a7d71766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd"
            }
        }
    ]
}' | jq
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
  • Response:
json
{
  "connect_timeout": 5000,
  "enabled": false,
  "endpoint": "127.0.0.1:18093",
  "idle_timeout": 86400000,
  "max_frame_size": "infinity",
  "name": "edge_test",
  "parallelism": 1,
  "ping": {},
  "realms": [
    {
      "authid": "device1",
      "cryptosign": {
        "privkey": "4ffddd896a530ce5ee8c86b83b0d31835490a97a9cd718cb2f09c9fd31c4a7d71766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd",
        "pubkey": "1766c9e6ec7d7b354fd7a2e4542753a23cae0b901228305621e5b8713299ccdd"
      },
      "procedures": [],
      "topics": [],
      "uri": "com.leapsight.test"
    }
  ],
  "reconnect": {},
  "restart": "transient",
  "socket_opts": {
    "keepalive": true,
    "nodelay": true
  },
  "tls_opts": {
    "verify": "verify_none"
  },
  "transport": "tcp",
  "type": "bridge_relay",
  "version": "1.0"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-ShareAlike (CC-BY-SA) 4.0 International license.
Bondy and Leapsight are registered trademarks.