Commit 04e8ee7d authored by Kaiden Fey's avatar Kaiden Fey Committed by Katharina Fey

qrpc-sdk: adding utilities to read messages into types

parent 2ea4712d
@0x97aa1eae99a0bced; # this was generated by capnp id
struct Service {
# Names follow reverse FQD specification: net.qaul.example
name @0 :Text;
# Versions are up to services to interpret. A simple
# incrementing number is fine, but feel free to encode semver
# into this field.
version @1 :Int16;
# A description of the service shown to end-users. Make it something concise
description @2 :Text;
}
interface RpcBroker {
struct Service {
# Names follow reverse FQD specification: net.qaul.example
name @0 :Text;
# Versions are up to services to interpret. A simple
# incrementing number is fine, but feel free to encode semver
# into this field.
version @1 :Int16;
# A description of the service shown to end-users. Make it something concise
description @2 :Text;
}
# Register this service with the broker and return a unique
# hash-id that users can verify the authenticity of this service.
registerService @0 (s :Service) -> (hash_id :Text);
# Unregister this service from the broker
unregisterServire @1 (hash_id :Text) -> (success :Bool);
unregisterService @1 (hash_id :Text) -> (success :Bool);
# Upgrade this service in-place
upgradeService @2 (s :Service, hash_id :Text) -> (success :Bool);
......
//! An I/O abstraction module for the qrpc system
//!
//! The qrpc system heavily builds on capnproto as an exchange and RPC
//! format. Unfortunately the capnproto-rs interface is pretty shit
//! (this is rude, I know but it's just not great...). Having to
//! interact with it to write services for qaul.net might be a dealbreaker.
//!
//! And so... this module tries to abstract as much of the low-level
//! ugliness away. Instead, you pass it a buffer with a message, and
//! it parses it for you, with some simple type constraits that are
//! easy to enforce in your application. Additionally, it exposes
//! some more convenient builders as well (although the builder APIs
//! in the original crate are quite good).
use capnp::{
message::{Reader, ReaderOptions},
serialize::OwnedSegments,
serialize_packed as ser,
traits::FromPointerReader,
};
use std::marker::PhantomData;
/// A result-wrapper for capnproto related failures
pub type Result<T> = capnp::Result<T>;
/// A utility type to read capnproto message types
pub struct MsgReader<'s, T: FromPointerReader<'s>> {
r: Reader<OwnedSegments>,
_t: &'s PhantomData<T>,
}
impl<'s, T: FromPointerReader<'s>> MsgReader<'s, T> {
/// Parse a message buffer into a set of owned segments
pub fn new(buf: Vec<u8>) -> Result<Self> {
ser::read_message(buf.as_slice(), ReaderOptions::new()).map(|r| Self {
r,
_t: &PhantomData,
})
}
/// Get the root object from this reader, if it exists
///
/// This function returns a reference to the inner reader for you.
/// Because the way this trait is implemented, the parent can't go
/// out of scope.
///
/// To get access to the fields of a type, you need to type-cast
/// it as a `T::Reader`, so to read a `service` type (such as the
/// one provided by this sdk crate), you would cast it as
/// `service::Reader`.
///
/// ```
/// # use qrpc_sdk::io::Result;
/// use qrpc_sdk::{io::MsgReader, rpc::service};
///
/// # fn run_code() -> Result<()> {
/// # let buf = vec![];
/// let msg = MsgReader::new(buf)?;
/// let r: service::Reader = msg.get_root()?;
/// println!("DESC: {}", r.get_description()?);
/// # Ok(())
/// # }
/// ```
pub fn get_root(&'s self) -> Result<T> {
self.r.get_root()
}
}
//! # qaul rpc sdk
//!
//! This library provides the basic capabilities of interacting with a
//! qrpc-broker, and other qaul services. These docs outline API
//! usage and concrete types. For an overview of concepts, consult
......@@ -22,6 +20,8 @@
//!
//! If this is not a requirement for you, don't worry about it.
pub mod io;
use identity::Identity;
// FIXME: currently the protocols have to be in the root of the crate
......@@ -32,6 +32,13 @@ pub(crate) mod carrier_capnp {
include!(concat!(env!("OUT_DIR"), "/schema/carrier_capnp.rs"));
}
/// Contains concrete RPC types and APIs
pub mod rpc {
use crate::carrier_capnp::rpc_broker as rpc;
pub use rpc::service;
}
/// A service representation on the qrpc system
pub struct Service {
name: String,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment