Bridge¶

Synopsis¶

rsb bridge [OPTIONS] SIMPLE-FORWARDING-SPECIFICATION

Description¶

Forward events according to SIMPLE-FORWARDING-SPECIFICATION (See Simple Forwarding Specification).

Note

When written as part of a shell command, the forwarding specification may require protection from processing by the shell, usually by surrounding the form in single quotes (‘). For example:

$ rsb bridge 'socket:/foo/ <-> spread:/bar/'

The usual commandline options are accepted. Specialized commandline options:

--max-queued-events POSITIVE-INTEGER¶

Specify the maximum number of events that may be kept in a queue in case processing (i.e. forwarding) cannot keep up with the rate of incoming events.

This queue can smooth over bursts of events, but if the sustained rate of incoming events is above the maximum processing speed, it will overflow and an error will be signaled. The behavior in this case can be controlled via common --on-error.

Simple Forwarding Specification¶

Simple forwarding specifications describe from and to which buses / scopes events should be forwarded and can be constructed according to the following grammar:

bridge-specification                    ::=  forwarding-specification (";" forwarding-specification)*
forwarding-specification                ::=  (unidirectional-forwarding-specification
                                              | bidirectional-forwarding-specification)
unidirectional-forwarding-specification ::=  (input-specification)+
                                             "->"
                                             (filter)*
                                             transform?
                                             (output-specification)+
bidirectional-forwarding-specification  ::=  (input-specification)+
                                             "<->"
                                             (output-specification)+
filter                                  ::=  "|" FILTER-SPEC "|"
transform                               ::=  "/" TRANSFORM-SPEC "/"
input-specification                     ::=  URI
output-specification                    ::=  URI

Unidirectional forwarding, described by the unidirectional-forwarding-specification production, consists in forwarding events from bus / scope(s) described by the input-specifications on the left hand side of the -> to the bus / scope(s) described by the output-specifications on the right hand side.
Bidirectional forwarding, described by the bidirectional-forwarding-specification production, is like unidirectional forwarding but also forwards events from the right hand side to the left hand side. As a consequence, filters are not supported.

Forwarding Cycles¶

Forwarding specifications, in particular bidirectional ones, can describe cyclic forwarding of events. For example, the specification socket:/foo -> socket:/foo is obviously cyclic since forwarded events are published on scope /foo and would therefore immediately be picked up for forwarding again. Such a forwarding setup has to be prevented since it immediately degrades the affected system, usually making it completely unusable.

The bridge command has two mechanisms for dealing with the problem:

Forwarding specifications are analyzed ahead of time to determine whether they are cyclic. This analysis yields one of three results:
1. Definitely cyclic (above example). In this case, a continuable error is signaled.
2. Maybe cyclic (e.g. socket:/foo/bar -> socket:/foo). In this case, warning is signaled.
3. Definitely not cyclic (e.g. spread:/foo -> socket:/bar)
Cases 1. and 2. usually indicate configuration errors and should be avoided.
When a cyclic forwarding specification is used, forwarded events are tagged when leaving the bridge, recognized when they enter the bridge a second time and discarded.

Examples¶

```
$ rsb bridge 'spread:/from -> spread:/to'
```
In the above example, the bridge command is used to establish unidirectional forwarding from scope /from to scope /to within the bus designated by spread:.

Note

Note the use of single quotes (') to prevent the shell from breaking up the simple forwarding specification into multiple arguments because of the whitespace in it.
```
$ rsb bridge 'socket://remotehost/ <-> socket://localhost/'
```
In the above example, the bridge command is used to establish bidirectional forwarding affecting all events between remotehost and localhost.

Note

Note the use of single quotes (') to prevent the shell from breaking up the simple forwarding specification into multiple arguments because of the whitespace in it.

Implementations¶

Implementation Language	Project	Repository Link
Common Lisp	rsb-tools-cl	“1.0” branch of https://github.com/open-rsx/rsb-tools-cl