pb_mapper/lib.rs
1//! Client SDK for a deployed pb-mapper relay.
2//!
3//! A [`Client`] holds a relay address and a credential. `register` publishes a
4//! local TCP or UDP service under a key, and `connect` makes that service
5//! reachable on a local port. Every connection tries a direct QUIC path first
6//! and falls back to the relay before any byte is sent; reconnection and
7//! recovery are handled inside the returned handles.
8//!
9//! ```ignore
10//! use std::time::Duration;
11//!
12//! use pb_mapper::{Client, ClientConfig, ConnectRequest, RegisterRequest, Transport};
13//!
14//! # async fn example() -> pb_mapper::Result<()> {
15//! let client = Client::new(ClientConfig {
16//! server: "relay.example.com:7666".into(),
17//! credential: std::env::var("MSG_HEADER_KEY").expect("MSG_HEADER_KEY"),
18//! keep_alive: true,
19//! namespace: None,
20//! })?;
21//!
22//! let registration = client
23//! .register(RegisterRequest {
24//! key: "echo".into(),
25//! local_addr: "127.0.0.1:8080".into(),
26//! transport: Transport::Tcp,
27//! codec: false,
28//! force_namespace: false,
29//! })
30//! .await?;
31//! registration.wait_ready().await?;
32//!
33//! let connection = client
34//! .connect(ConnectRequest {
35//! key: "echo".into(),
36//! local_addr: "127.0.0.1:9090".into(),
37//! transport: Transport::Tcp,
38//! })
39//! .await?;
40//! connection.wait_ready().await?;
41//!
42//! // Status changes as they happen, and what recovery did.
43//! let mut status = connection.subscribe();
44//! status.changed().await.ok();
45//! println!("{:?} {:?}", *status.borrow(), connection.diagnostics().events);
46//!
47//! // With the administrator key: a scoped, expiring credential for a workload.
48//! let issued = client
49//! .admin()?
50//! .issue_key(Duration::from_secs(3600), Some("agent".into()))
51//! .await?;
52//! client.admin()?.revoke_key(issued.key_id).await?;
53//!
54//! connection.stop().await?;
55//! registration.stop().await?;
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! Runnable examples for every capability are in `examples/`; start with
61//! `cargo run -p pb-mapper --example quickstart`, which needs no relay of your
62//! own. The CLI and relay binary are the `pb-mapper-cli` package
63//! (`cargo install pb-mapper-cli`).
64
65pub use pb_mapper_client::sdk::*;