Golem Service Bus (a.k.a. GSB)

GSB is a message bus allowing Yagna services to communicate with one another. It consist of two software components: router (ya-sb-router) and client crate (ya-service-bus). GSB router is a socket-based message dispatcher. The client crate provides a high-level API for connecting to the router and allows local (i.e. within-process, in-memory) routing. GSB supports two distinct ways of communication: service calls (one-to-one, bidirectional) and broadcasts (one-to-many, unidirectional).

How to compile your own central net

It is useful for internal development of Golem components or if you want to create your own separated subnet of Golem Network.

YA-SERVICE-BUS - your local repository path

Compile steps:

1. In terminal go to YA-SERVICE-BUS/crates/router
2. Run: cargo build --bin ya-sb-router --features bin --release
3. You should find binary in YA-SERVICE-BUS/target/release

alternatively you can build from YA-SERVICE-BUS using more complicated command:

1. cargo build --bin ya-sb-router --features ya-sb-router/bin --release --package ya-sb-router
2. You should find binary in YA-SERVICE-BUS/target/release

Note that ya-sb-router crate can be used as library or binary depending on usage, thus requiring --bin switch to compile correctly

Low-level router API

Message format

GSB messages are encoded with protobuf. Message types could be found in gsb_api.proto file. Each message is prepended with a 64-bit header. First 4 bytes of the header are interpreted as big-endian singed integer encoding message type (for mapping see Packet enum). Next 4 bytes of the header are interpreted as big-endian unsigned integer representing message length.

Operations

Register

Register a service on the bus. Accepts service name as a parameter. Registered service can be called by its name by other processes connected to GSB. Service name is treated as a prefix, e.g. a service registered under foo will also receive calls to foo/bar and foo/baz.

Unregister

Unregister a service from the bus. No longer receive calls.

ServiceCall

Call a service registered on the bus and wait for the reply. Every service call has an ID, called service's address (name), and call data. Reply from the service will be returned in one or more CallReply messages containing call request ID.

Subscribe

Subscribe to a broadcast topic in order to receive all messages published for this topic.

Unsubscribe

Unsubscribe from a broadcast topic. No longer receive messages.

Broadcast

Broadcast a message to all subscribers of a given topic.

Pings and disconnections

Every 60 seconds router checks for idle connections. If a client has not sent any message for 60 seconds it is pinged. If a client has not sent any message for 120 seconds it is disconnected. The timeout is configurable via GSB_PING_TIMEOUT environment variable. When a client is disconnected all registered services and broadcast subscriptions are removed. All pending calls to a service that got disconnected are answered with ServiceFailure reply.