Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/golemfactory/ya-service-bus


https://github.com/golemfactory/ya-service-bus

golem

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

        
# 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`](crates/proto/protos/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](https://github.com/golemfactory/ya-service-bus/blob/3b8ff9cd49fb040cdfeee127f42b28e962a0a9f4/crates/proto/protos/gsb_api.proto#L32-L51) 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.