Crate libqaul[][src]

This library sits at the core of qaul, providing user identities, peer trust management, message sending abstractions, and high-level peer discovery mechanisms.

Its API (in documentation also called the “service API”) enables applications to run on decentralised networks, without relying on servers to facilitate data exchange.

You can use the libqaul API in two ways:

  1. Require the libqaul crate as a dependency, and use the Rust API natively. This will result in your application running a decentralised router (See ratman crate).

  2. Include the libqaul-sdk crate as a dependency, which exposes the same API as libqaul, but connects to a running daemon via the QRPC protocol.

The second method is recommended for most users, as it will allow many different applications to use the same routing daemon for their tasks.

Basic architecture

In qaul we make the distinction between a client (a user-facing entity with some kind of UI), and a service (a micro-application, exposing an API to clients, and other services).

Following is a short overview of a full qaul application stack. You can find a more detailed description in the developer manual.

ComponentDescription
End-user ApplicationA UI for users to interact with (either graphical, or textual)
ServicesMicro-applications providing very specificy and re-usable functionality to other services and applications
RPC System(Optional) The QRPC broker and SDK system to connect to an external qaul daemon
libqaulCore identity, data, and peer management library
RatmanA decentralised, delay-tolerant, userspace router
Network driversPlatform-specific network driver plugins for Ratman

When initialising an instance of libqaul, components need to be initialised in reverse-order (network drivers first, user application state last).

Example

Following is a short example of how to use libqaul directly. For examples on how to use the SDK, check out the libqaul-sdk documentation!

use libqaul::Qaul;
let q = Qaul::new(router);

// Create an anonymous user with a password
let alice = q.users().create("password alice secret keeps").await?;

// Alice decides she wants to publish her handle
let update = UserUpdate { handle: ItemDiff::set("@alice"), ..Default::default() };
q.users().update(alice, update).await?;

// libqaul will now advertise Alice as `@alice` along side with
// her cryptographic public key!

Functionality

libqaul handles user registration, sign-in, authentication, binary payload messaging, peer discovery, and management. Some concepts are not implemented in libqaul directly (such as message groups, or text-payload messages), but instead require a service.

For an overview of services written by the qaul project, check this page in the developer manual!

Modules

api

A set of function specific API scopes in libqaul

contacts

Network user contact metadata and utilities

error

Error and Result handling

helpers

A set of API helpers

messages

Network message types and utilities

rpc

libqaul RPC compatibility adapter

services

Service inteface utilities

users

Local user and session types

Structs

Identity

A generic object identifier

Qaul

Primary context structure for libqaul

Type Definitions

QaulRef

An atomic reference counted pointer to a running libqaul instance