Crate spotlib 

Client for the Spot secure messaging network.

Spotlib enables secure, end-to-end encrypted communication between clients through the Spot network. It handles connection management, cryptographic identity, message routing, and provides both request-response and fire-and-forget messaging patterns.

This crate is a Rust port of the Go package github.com/KarpelesLab/spotlib. It is built on bottlers for cryptography, purecrypto for TLS, and rsurl for the platform REST API — pure Rust all the way down, no async runtime required (connections are handled by background threads).

Basic usage

Create a new client (with an ephemeral identity) and wait for it to come online:

use std::time::Duration;

let client = spotlib::Client::new()?;
client.wait_online(Duration::from_secs(30))?;

Sending messages

Send an encrypted query and wait for the response:

let response = client.query("k.targetID/endpoint", b"payload", Duration::from_secs(30))?;

Send a one-way encrypted message:

client.send_to("k.targetID/endpoint", b"payload", Duration::from_secs(30))?;

Receiving messages

Register a handler for incoming messages on an endpoint (decrypted automatically; the returned bytes are sent back as the response):

let client = spotlib::Client::builder()
    .handler("myendpoint", |msg| Ok(Some(msg.body.clone())))
    .build()?;

Identity and addressing

Each client has a cryptographic identity represented by an ID card. The client’s address (Client::target_id) is derived from the SHA-256 hash of its public key and has the format k.<base64url hash>. Messages to key-based addresses are automatically encrypted and signed; the recipient’s public key is retrieved and cached automatically. Use DiskStore to persist the identity key across runs.

wasm32 (browser)

spotlib also runs in the browser on wasm32-unknown-unknown. Because the browser event loop cannot block and has no threads, the network-facing API there is async and driven on the browser event loop: Client::query, Client::wait_online, Client::send_to, the get_*/store_blob/ fetch_blob/get_time methods, and PacketConn::recv become async fn. Client::new/build, close, target_id, subscribe_events, set_handler and the other non-networking methods keep their synchronous signatures. Connections use rsurl’s aio WebSocket/Fetch backend over the browser’s native APIs.

Building for wasm requires disabling the default native feature:

cargo build --no-default-features --target wasm32-unknown-unknown

Two integration requirements are the embedder’s responsibility:

• Randomness — purecrypto’s OsRng draws entropy through an imported host function purecrypto.random_get(ptr, len). Wire it to crypto.getRandomValues (browser) or crypto.randomFillSync (Node).
• Key persistence — DiskStore is native-only. On wasm, supply keys via ClientBuilder::key/ClientBuilder::keychain and persist them yourself (e.g. in localStorage).

Re-exports

pub use spotproto;

Structs

Client

A client connected to the Spot messaging network.

ClientBuilder

Builder for Client, allowing keys, metadata and handlers to be set before the client connects.

DiskStore

Disk-backed key storage (native only; not available on wasm32, where key persistence is the embedder’s responsibility). Stores client identity keys on disk.

Hub

A simple broadcast hub: every subscriber receives every event emitted after it subscribed. Disconnected subscribers are dropped automatically.

InstantMessage

A message with metadata, content and cryptographic information.

Message

An instant message exchanged between hosts (packet type 0x2).

PacketConn

A packet-oriented connection bound to an endpoint name. Messages sent to <target_id>/<name> are received here; outgoing packets are encrypted and signed automatically. Created via Client::listen_packet.

Enums

ClientEvent

Events emitted by the client.

Error

Errors returned by the spot client.

Functions

clone_private_key

Duplicates a private key by round-tripping its secret material. Supported variants: ECDSA P-256, Ed25519, RSA. Other key types cannot be duplicated with the current purecrypto API.

Type Aliases

MessageHandler

A message handler registered for an endpoint. Receives the (decrypted) message; returning Ok(Some(body)) sends a response, Ok(None) stays silent, and Err(text) sends an error response.

Result

Convenience result alias for spotlib operations.