2 releases
0.1.1 | Mar 2, 2021 |
---|---|
0.1.0 | Oct 10, 2020 |
#49 in #endpoint
Used in 4 crates
33KB
455 lines
qrpc-sdk
The qrpc protocol connections an rpc-broker with different service endpoints. Each service endpoint provides a set of callable functions, and type serialisation data.
Your app logic Serialise types Pass data along
+--------------+ +--------------+ +--------------+
| Your service | - | qrpc-sdk | - | qrpc-broker |
+--------------+ +--------------+ +--------------+
|
+--------------+ +--------------+ +--------------+
| Your UI app | - | qrpc-sdk | - | libqaul |
+--------------+ +--------------+ +--------------+
Your app UI Deserialise types Main db/ router
You can find more information in the contributors manual.
lib.rs
:
A toolkit for writing clients on the qrpc message bus. This bus
is the backbone of the qaul.net service
ecosystem. With it you can create applications (called
"services") that interact with a libqaul
instance, and other
services on the same message broker.
These crate docs describe the API and basic usage. For an overview of the core concepts of this ecosystem, consult the contributors manual.
Additionally, you can access documentation of the internal
utilities by passing "--features internals
" to your cargo
invocation. These components are exposed via the API either way,
but only documented on demand to not clutter the main
documentation.
Using this sdk
In order to interact with a running qrpc-broker
instance your
service needs to register itself and it's capabilities.
First your service needs a place to save some state, composing different parts of this sdk together to create an app.
You create a Service
and RpcSocket
and connect to the
rpc-broker socket. The first thing you do with this connection is
call register(...)
on the Service
. This establishes the
connection, the broker saves your service in it's address lookup
table, and you get assigned a hash-id to identify you in future
interactions.
use qrpc_sdk::{Service, RpcSocket, default_socket_path};
let mut serv = Service::new("com.example.myapp", 1, "A simple app");
let (addr, port) = default_socket_path();
let sock = RpcSocket::connect(addr, port).await?;
serv.register(sock).await?;
println!("Service registered! ID: {}", serv.hash_id().unwrap());
Next you need to include the client-lib of the component you want
to use, and call connect(...)
on your service with the component
initialiser.
// serv.connect(libqaul_rpc::Init).await?;
This will establish a connection with the libqaul
component and
verifies it's capability set. This mechanism is provided by the
ServiceConnector
. Your service will also have to implement
this mechanism to be usable by other services on the qrpc bus.
After that you can call functions on the public API type of the component. You can get a copy of it via your service handle.
// net.qaul.libqaul is exposed as libqaul_rpc.COMP_ID
// let users = serv.component("net.qaul.libqaul").list_users().await?;
// println!("Available users: {:?}", users);
If you want to see a minimal example of the smallest functional
service, see the ping
crate.
Dependencies
~7–20MB
~250K SLoC