Crate pb_mapper

Expand description

Client SDK for a deployed pb-mapper relay.

A Client holds a relay address and a credential. register publishes a local TCP or UDP service under a key, and connect makes that service reachable on a local port. Every connection tries a direct QUIC path first and falls back to the relay before any byte is sent; reconnection and recovery are handled inside the returned handles.

use std::time::Duration;

use pb_mapper::{Client, ClientConfig, ConnectRequest, RegisterRequest, Transport};

let client = Client::new(ClientConfig {
    server: "relay.example.com:7666".into(),
    credential: std::env::var("MSG_HEADER_KEY").expect("MSG_HEADER_KEY"),
    keep_alive: true,
    namespace: None,
})?;

let registration = client
    .register(RegisterRequest {
        key: "echo".into(),
        local_addr: "127.0.0.1:8080".into(),
        transport: Transport::Tcp,
        codec: false,
        force_namespace: false,
    })
    .await?;
registration.wait_ready().await?;

let connection = client
    .connect(ConnectRequest {
        key: "echo".into(),
        local_addr: "127.0.0.1:9090".into(),
        transport: Transport::Tcp,
    })
    .await?;
connection.wait_ready().await?;

// Status changes as they happen, and what recovery did.
let mut status = connection.subscribe();
status.changed().await.ok();
println!("{:?} {:?}", *status.borrow(), connection.diagnostics().events);

// With the administrator key: a scoped, expiring credential for a workload.
let issued = client
    .admin()?
    .issue_key(Duration::from_secs(3600), Some("agent".into()))
    .await?;
client.admin()?.revoke_key(issued.key_id).await?;

connection.stop().await?;
registration.stop().await?;

Runnable examples for every capability are in examples/; start with cargo run -p pb-mapper --example quickstart, which needs no relay of your own. The CLI and relay binary are the pb-mapper-cli package (cargo install pb-mapper-cli).

Structs§

Admin: Administrator RPCs. Constructed via super::Client::admin.
AuthStatusInfo: Relay-side snapshot of the credential subsystem.
Client: Session against one deployed relay.
ClientConfig: Configuration for a Client session.
ConnectOptions
ConnectRequest: Subscribe to a registered service and listen locally.
Connection: A live connect tunnel: a local listener forwarding to a registered service.
ConnectionInfo: One control connection the relay holds for a registered service.
ConnectionPage: One page of live service connections.
DirectAttempt: The direct attempt a tunnel is making right now.
EventsLagged: A TunnelEvents subscriber fell behind and missed skipped events.
IssuedKey: A temporary credential, with the secret the relay just minted.
KeyListPage: One page of temporary credentials.
KeyMetadata: A temporary credential without its secret.
ObservedReport
PathDiagnostics
PortMappingDiagnostics: A tunnel’s port mapping: where it stands, and what it took to get there.
PortMappingStatus: A gateway mapping as it stands after its latest change. Credential-free; what the gateway said about a failure is cut to 256 characters.
QuicConnectionDiagnostics: Cumulative Quinn counters for one live connection; sampled only on request.
RegisterOptions
RegisterRequest: Register a local TCP/UDP service with the relay.
Registration: A live register tunnel: a local service published on the relay.
RelayDiagnostics: The relay carrier as this client’s pool sees it, sampled on request.
RemoteId: Relay mapping dump from status remote-id.
ServiceConnection: One control connection the relay is holding for a service key.
ServiceInfo: A registered service as the relay sees it.
ServicePage: One page of registered services.
SessionObservation
TunnelDiagnostics: A point-in-time view of this tunnel and its process-shared relay budget. Non-exhaustive: fields are added as the SDK observes more.
TunnelEvent: One event of a tunnel. In TunnelDiagnostics::events, oldest first, consecutive repeats fold into one entry, so a long outage cannot push out what came before it; TunnelEvents delivers every occurrence.
TunnelEvents: A tunnel’s events as they happen, after the history it has kept: from subscribe_events on a Registration or a Connection.

Enums§

DirectStage: Where a direct attempt stands. Every stage before Self::Committing can still fall back to the relay; a fallback names the stage it left.
Error: Errors returned by the client SDK.
LegacyProtocol: Legacy framing policy, matching pb-mapper admin legacy-protocol.
PathPolicy: Per-connect path policy.
PortMapping: Whether a tunnel asks this network’s router (PCP, NAT-PMP or UPnP) to map its direct endpoint’s UDP port, so that a peer’s first packet gets in where the NAT drops what it has not seen. A mapping never holds up a session, is renewed while the tunnel runs and released when it stops, and is ignored while the tunnel keeps to the relay; TunnelDiagnostics::port_mapping says where it stands.
PortMappingProtocol: How a gateway is asked for a mapping.
PortMappingStage: Where a gateway mapping stands. A lease outlives some stages: whether one is usable right now is PortMappingStatus::active.
RecoveryFailure: Why a recovery attempt failed, without credentials or application data.
RecoveryPhase: The phase most recently entered by a tunnel worker.
RelayTransport
SessionPath
SessionState
Transport: Transport used by a registered service or a local subscriber.
TunnelEventKind: What happened, in a TunnelEvent.
TunnelStatus: Observed lifecycle of a super::Registration or super::Connection.

Constants§

QUIC_UNAVAILABLE: The refusal code for a relay that offers no QUIC: one started without a QUIC listener, or one from before QUIC, which cannot read the question. Final, since retrying the same relay cannot change it, and so a tunnel asked to use QUIC there fails rather than retrying forever.
SDK_VERSION: The SDK version compiled into this process.

Type Aliases§

Result

Crate pb_mapper

Crate pb_mapper Copy item path

Structs§

Enums§

Constants§

Type Aliases§

Crate pb_mapper