nym-sdk-session 1.21.5-rc.3

Provisioning facade over nym-registration-client + nym-bandwidth-controller + the credential store: from a mnemonic it issues/persists zk-nym WireGuard ticketbooks, selects gateways, and registers them
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

// Copyright 2026 - Nym Technologies SA <contact@nymtech.net>
// SPDX-License-Identifier: Apache-2.0

use nym_validator_client::nym_api::error::NymAPIError;
use nym_validator_client::nyxd::error::NyxdError;
use std::net::SocketAddr;

/// Errors produced while provisioning a dVPN session.
#[derive(thiserror::Error, Debug)]
pub enum SessionError {
    /// Failed to construct or talk to the nyxd chain client.
    #[error("nyxd chain client error: {0}")]
    Nyxd(#[from] NyxdError),

    /// A nym-api request failed.
    #[error("nym-api error: {0}")]
    Api(#[from] NymAPIError),

    /// The configured network has no usable validator/API endpoint.
    #[error("network details contain no usable {which} endpoint")]
    MissingEndpoint { which: &'static str },

    /// A URL in the network details could not be parsed.
    #[error("invalid {which} url {url}: {source}")]
    InvalidUrl {
        which: &'static str,
        url: String,
        #[source]
        source: url::ParseError,
    },

    /// Credential storage could not be opened.
    #[error("credential storage error: {0}")]
    Storage(String),

    /// Ticketbook deposit / issuance failed.
    #[error("ticketbook issuance error: {0}")]
    Issuance(String),

    /// Provisioning did not complete within its overall budget — most likely the ecash
    /// signers / nym-apis are unresponsive. Any deposit already made is recorded in the
    /// fetcher's pending-request store and is recovered (without re-depositing) on a retry.
    #[error(
        "provisioning timed out after {after:?} — the ecash signers are likely unresponsive; \
         any deposit already made is recoverable from the pending-request store on retry"
    )]
    ProvisioningTimeout { after: std::time::Duration },

    /// No gateway matched the requested identity.
    #[error("no gateway found with identity {0}")]
    GatewayNotFound(String),

    /// No WireGuard-capable gateway is available for the requested role.
    #[error("no WireGuard-capable gateway available for the requested role")]
    NoWireguardGateway,

    /// No WireGuard-capable gateway matched the requested country code.
    #[error("no WireGuard-capable gateway found in country {0}")]
    NoCountryMatch(String),

    /// A QUIC-bridge entry gateway was required but none is available for the
    /// requested selection (directory unavailable, or no QUIC gateway matches).
    #[error("no QUIC-bridge gateway available for selection: {spec}")]
    NoQuicGateway { spec: String },

    #[error("entry and exit resolved to the same gateway ({0}); a two-hop tunnel needs distinct gateways")]
    SameGatewaySelected(String),

    /// A selected gateway advertised malformed LP data.
    #[error("gateway {identity} advertised malformed LP data: {reason}")]
    MalformedGateway { identity: String, reason: String },

    /// Gateway registration failed.
    #[error("registration with gateway at {address} failed: {source}")]
    Registration {
        address: SocketAddr,
        #[source]
        source: nym_registration_client::LpClientError,
    },

    /// The setup/issuance phase was cancelled via the CancellationToken.
    #[error("session setup was cancelled")]
    Cancelled,
}