diff --git a/mullvad-types/src/account.rs b/mullvad-types/src/account.rs index a725db13eebe..67fb6ce2d0b3 100644 --- a/mullvad-types/src/account.rs +++ b/mullvad-types/src/account.rs @@ -3,8 +3,10 @@ use chrono::{offset::Utc, DateTime}; use jnix::IntoJava; use serde::{Deserialize, Serialize}; +/// Identifier used to authenticate or identify a Mullvad account. pub type AccountToken = String; +/// Account expiration info returned by the API via `/v1/me`. #[derive(Debug, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -13,8 +15,8 @@ pub struct AccountData { pub expiry: DateTime, } -/// Data-structure that's returned from successfuly invocation of the mullvad API's -/// `submit_voucher(account, voucher)` RPC +/// Data structure that's returned from successful invocation of the mullvad API's +/// `/v1/submit-voucher` RPC. #[derive(serde::Deserialize, serde::Serialize, Debug)] pub struct VoucherSubmission { /// Amount of time added to the account @@ -23,7 +25,8 @@ pub struct VoucherSubmission { pub new_expiry: DateTime, } -/// Mapping of mullvad-api errors +/// Mapping of mullvad-api errors to enum variants. Used by frontends to explain why a voucher +/// was rejected by the `/v1/submit-voucher` RPC. #[derive(err_derive::Error, Debug)] pub enum VoucherError { /// Error code -400 diff --git a/mullvad-types/src/auth_failed.rs b/mullvad-types/src/auth_failed.rs index 4fcfe664638e..fd8ff2b7b52f 100644 --- a/mullvad-types/src/auth_failed.rs +++ b/mullvad-types/src/auth_failed.rs @@ -2,6 +2,9 @@ use lazy_static::lazy_static; use regex::Regex; use std::fmt; +/// Used by frontends to parse [`talpid_types::tunnel::ErrorStateCause::AuthFailed`], which may be +/// returned in [`talpid_types::tunnel::ErrorStateCause`] when there is a failure to authenticate +/// with a remote server. #[derive(Debug)] pub struct AuthFailed { reason: AuthFailedInner, diff --git a/mullvad-types/src/location.rs b/mullvad-types/src/location.rs index 07a0c0079502..243c0768e814 100644 --- a/mullvad-types/src/location.rs +++ b/mullvad-types/src/location.rs @@ -7,6 +7,7 @@ pub type CountryCode = String; pub type CityCode = String; pub type Hostname = String; +/// Describes the physical location of a [`crate::relay_list::Relay`] as returned by the API. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Location { pub country: String, diff --git a/mullvad-types/src/relay_constraints.rs b/mullvad-types/src/relay_constraints.rs index bc99c6f862dd..fcf81daedef5 100644 --- a/mullvad-types/src/relay_constraints.rs +++ b/mullvad-types/src/relay_constraints.rs @@ -17,6 +17,7 @@ pub trait Match { fn matches(&self, other: &T) -> bool; } +/// Limits the set of [`crate::relay_list::Relay`]s that a `RelaySelector` may select. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] #[cfg_attr(target_os = "android", derive(FromJava, IntoJava))] @@ -66,6 +67,8 @@ impl Match for Constraint { } } +/// Specifies a specific endpoint or [`RelayConstraints`] to use when `mullvad-daemon` selects a +/// relay. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] #[cfg_attr(target_os = "android", derive(IntoJava))] @@ -127,6 +130,7 @@ impl RelaySettings { } } +/// Limits the set of [`crate::relay_list::Relay`]s that a `RelaySelector` may select. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[cfg_attr(not(target_os = "android"), derive(Default))] #[cfg_attr(target_os = "android", derive(IntoJava))] @@ -199,6 +203,8 @@ impl fmt::Display for RelayConstraints { } +/// Limits the set of [`crate::relay_list::Relay`]s used by a `RelaySelector` based on +/// location. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] #[cfg_attr(target_os = "android", derive(FromJava, IntoJava))] @@ -224,6 +230,7 @@ impl fmt::Display for LocationConstraint { } } +/// Used in [`RelayConstraints`] to limit relay selection based on protocol. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] pub enum TunnelProtocol { #[serde(rename = "wireguard")] @@ -241,6 +248,7 @@ impl fmt::Display for TunnelProtocol { } } +/// Deprecated. Contains protocol-specific constraints for relay selection. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] pub enum TunnelConstraints { #[serde(rename = "openvpn")] @@ -282,6 +290,7 @@ impl Match for TunnelConstraints { } } +/// [`Constraint`]s applicable to OpenVPN relay servers. #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Deserialize, Serialize)] pub struct OpenVpnConstraints { pub port: Constraint, @@ -308,6 +317,7 @@ impl Match for OpenVpnConstraints { } } +/// [`Constraint`]s applicable to WireGuard relay servers. #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Deserialize, Serialize)] pub struct WireguardConstraints { pub port: Constraint, @@ -335,6 +345,8 @@ impl Match for WireguardConstraints { } +/// Specifies a specific endpoint or [`BridgeConstraints`] to use when `mullvad-daemon` selects a +/// bridge server. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] pub enum BridgeSettings { @@ -344,6 +356,7 @@ pub enum BridgeSettings { } +/// Limits the set of bridge servers to use in `mullvad-daemon`. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] pub struct BridgeConstraints { @@ -359,6 +372,7 @@ impl fmt::Display for BridgeConstraints { } } +/// Setting indicating whether to connect to a bridge server, or to handle it automatically. #[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] pub enum BridgeState { @@ -387,6 +401,7 @@ pub struct InternalBridgeConstraints { pub transport_protocol: Constraint, } +/// Used to update the [`RelaySettings`] used in `mullvad-daemon`. #[derive(Debug, Deserialize, Serialize)] #[cfg_attr(target_os = "android", derive(FromJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -422,6 +437,7 @@ impl RelaySettingsUpdate { } } +/// Used in [`RelaySettings`] to change relay constraints in the daemon. #[derive(Debug, Default, Deserialize, Serialize)] #[cfg_attr(target_os = "android", derive(FromJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] diff --git a/mullvad-types/src/relay_list.rs b/mullvad-types/src/relay_list.rs index 7277b922cae1..c3bbc33b6fd3 100644 --- a/mullvad-types/src/relay_list.rs +++ b/mullvad-types/src/relay_list.rs @@ -15,6 +15,8 @@ use talpid_types::net::{ }; +/// Stores a list of relays for each country obtained from the API using +/// `mullvad_rpc::RelayListProxy`. This can also be passed to frontends. #[derive(Debug, Clone, Deserialize, Serialize)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -30,6 +32,7 @@ impl RelayList { } } +/// A list of [`RelayListCity`]s within a country. Used by [`RelayList`]. #[derive(Debug, Clone, Deserialize, Serialize)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -39,6 +42,7 @@ pub struct RelayListCountry { pub cities: Vec, } +/// A list of [`Relay`]s within a city. Used by [`RelayListCountry`]. #[derive(Debug, Clone, Deserialize, Serialize)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -52,6 +56,8 @@ pub struct RelayListCity { pub relays: Vec, } +/// Stores information for a relay returned by the API at `v1/relays` using +/// `mullvad_rpc::RelayListProxy`. #[derive(Debug, Clone, Deserialize, Serialize)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -79,6 +85,7 @@ pub struct Relay { pub location: Option, } +/// Provides protocol-specific information about a [`Relay`]. #[derive(Debug, Default, Clone, Deserialize, Serialize)] #[serde(default)] #[cfg_attr(target_os = "android", derive(IntoJava))] @@ -100,6 +107,7 @@ impl RelayTunnels { } } +/// Data needed to connect to an OpenVPN endpoint at a [`Relay`]. #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct OpenVpnEndpointData { pub port: u16, @@ -118,6 +126,7 @@ impl fmt::Display for OpenVpnEndpointData { } } +/// Data needed to connect to a WireGuard endpoint at a [`Relay`]. #[derive(Clone, Eq, PartialEq, Hash, Deserialize, Serialize, Debug)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr(target_os = "android", jnix(package = "net.mullvad.mullvadvpn.model"))] @@ -149,6 +158,7 @@ impl fmt::Display for WireguardEndpointData { } } +/// Used by `mullvad_rpc::RelayListProxy` to store bridge servers for a [`Relay`]. #[derive(Debug, Default, Clone, Deserialize, Serialize)] #[serde(default)] pub struct RelayBridges { @@ -165,6 +175,7 @@ impl RelayBridges { } } +/// Data needed to connect to a Shadowsocks endpoint at a [`Relay`]. #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct ShadowsocksEndpointData { pub port: u16, diff --git a/talpid-types/src/lib.rs b/talpid-types/src/lib.rs index d333ecca91b1..d5b71fd46d89 100644 --- a/talpid-types/src/lib.rs +++ b/talpid-types/src/lib.rs @@ -8,6 +8,7 @@ pub mod net; pub mod tunnel; +/// Used to generate string representations of error chains. pub trait ErrorExt { /// Creates a string representation of the entire error chain. fn display_chain(&self) -> String; diff --git a/talpid-types/src/net/mod.rs b/talpid-types/src/net/mod.rs index bcfec414ae22..97292fd381e6 100644 --- a/talpid-types/src/net/mod.rs +++ b/talpid-types/src/net/mod.rs @@ -57,7 +57,7 @@ impl From for TunnelParameters { } } -/// Type of the tunnel +/// The tunnel protocol used by a [`TunnelEndpoint`]. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename = "tunnel_type")] pub enum TunnelType { @@ -85,7 +85,6 @@ impl fmt::Display for TunnelType { pub struct TunnelEndpoint { #[serde(flatten)] pub endpoint: Endpoint, - /// Type of the tunnel #[cfg_attr(target_os = "android", jnix(skip))] pub tunnel_type: TunnelType, #[cfg_attr(target_os = "android", jnix(skip))] @@ -167,6 +166,9 @@ impl fmt::Display for TransportProtocol { } } + +/// Returned when `TransportProtocol::from_str` fails to convert a string into a +/// [`TransportProtocol`] object. #[derive(Debug, Clone, PartialEq, Eq)] pub struct TransportProtocolParseError; @@ -184,7 +186,9 @@ pub struct GenericTunnelOptions { pub enable_ipv6: bool, } -/// Returns a vector of IP networks representing all of the internet. +/// Returns a vector of IP networks representing all of the internet, 0.0.0.0/0. +/// This may be used in [`crate::net::wireguard::PeerConfig`] to route all traffic +/// to the tunnel interface. pub fn all_of_the_internet() -> Vec { vec![ "0.0.0.0/0".parse().expect("Failed to parse ipv6 network"), diff --git a/talpid-types/src/net/openvpn.rs b/talpid-types/src/net/openvpn.rs index d9c31ed92b4d..c7beed655992 100644 --- a/talpid-types/src/net/openvpn.rs +++ b/talpid-types/src/net/openvpn.rs @@ -5,6 +5,8 @@ use crate::net::{ use serde::{Deserialize, Serialize}; use std::net::SocketAddr; +/// Information needed by `OpenVpnMonitor` to establish a tunnel connection. +/// See [`crate::net::TunnelParameters`]. #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct TunnelParameters { pub config: ConnectionConfig, @@ -13,6 +15,7 @@ pub struct TunnelParameters { pub proxy: Option, } +/// Connection configuration used by [`TunnelParameters`]. #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct ConnectionConfig { pub endpoint: Endpoint, @@ -30,9 +33,10 @@ impl ConnectionConfig { } } -/// TunnelOptions contains options for an openvpn tunnel that should be applied +/// `TunnelOptions` contains options for an OpenVPN tunnel that should be applied /// irrespective of the relay parameters - i.e. have nothing to do with the particular /// OpenVPN server, but do affect the connection. +/// Stored in [`TunnelParameters`]. #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, Default)] pub struct TunnelOptions { /// Optional argument for openvpn to try and limit TCP packet size, @@ -40,14 +44,12 @@ pub struct TunnelOptions { pub mssfix: Option, } +/// Proxy server options to be used by `OpenVpnMonitor` when starting a tunnel. #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] pub enum ProxySettings { - /// Generic proxy running independently on localhost. Local(LocalProxySettings), - /// Generic proxy running on remote host. Remote(RemoteProxySettings), - /// Bundled Shadowsocks proxy. Shadowsocks(ShadowsocksProxySettings), } @@ -71,6 +73,7 @@ impl ProxySettings { } } +/// Options for a generic proxy running on localhost. #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct LocalProxySettings { pub port: u16, @@ -86,6 +89,7 @@ impl LocalProxySettings { } } +/// Options for a generic proxy running on remote host. #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct RemoteProxySettings { pub address: SocketAddr, @@ -107,6 +111,7 @@ pub struct ProxyAuth { pub password: String, } +/// Options for a bundled Shadowsocks proxy. #[derive(Debug, Clone, Eq, PartialEq, Hash, Deserialize, Serialize)] pub struct ShadowsocksProxySettings { pub peer: SocketAddr, @@ -124,6 +129,8 @@ impl ShadowsocksProxySettings { } } +/// List of ciphers usable by a Shadowsocks proxy. +/// Cf. [`ShadowsocksProxySettings::cipher`]. pub static SHADOWSOCKS_CIPHERS: &[&str] = &[ // Stream ciphers. "aes-128-cfb", @@ -148,6 +155,7 @@ pub static SHADOWSOCKS_CIPHERS: &[&str] = &[ "aes-256-pmac-siv", ]; +/// Checks whether the proxy settings to be used by `OpenVpnMonitor` are valid. pub fn validate_proxy_settings(proxy: &ProxySettings) -> Result<(), String> { match proxy { ProxySettings::Local(local) => { diff --git a/talpid-types/src/net/proxy.rs b/talpid-types/src/net/proxy.rs index d2960932c6e2..73e87915c4f7 100644 --- a/talpid-types/src/net/proxy.rs +++ b/talpid-types/src/net/proxy.rs @@ -6,9 +6,7 @@ use std::fmt; #[serde(rename_all = "snake_case")] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] pub enum ProxyType { - /// Shadowsocks Shadowsocks, - /// Custom bridge Custom, } @@ -23,7 +21,7 @@ impl fmt::Display for ProxyType { } -/// Bridge endpoint, broadcast as part of TunnelEndpoint +/// Bridge endpoint, broadcast as part of a [`crate::net::TunnelEndpoint`]. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct ProxyEndpoint { #[serde(flatten)] diff --git a/talpid-types/src/net/wireguard.rs b/talpid-types/src/net/wireguard.rs index 9e6e6290bd29..49ff4640fb50 100644 --- a/talpid-types/src/net/wireguard.rs +++ b/talpid-types/src/net/wireguard.rs @@ -11,18 +11,21 @@ use std::{ }; +/// Tunnel parameters required to start a `WireguardMonitor`. +/// See [`crate::net::TunnelParameters`]. #[derive(Clone, Eq, PartialEq, Deserialize, Serialize, Debug)] -/// Wireguard tunnel parameters pub struct TunnelParameters { pub connection: ConnectionConfig, pub options: TunnelOptions, pub generic_options: GenericTunnelOptions, } +/// Connection-specific configuration in [`TunnelParameters`]. #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)] pub struct ConnectionConfig { pub tunnel: TunnelConfig, pub peer: PeerConfig, + /// Gateway used by the tunnel (a private address). pub ipv4_gateway: Ipv4Addr, pub ipv6_gateway: Option, } @@ -38,18 +41,22 @@ impl ConnectionConfig { #[derive(Clone, Eq, PartialEq, Deserialize, Serialize, Debug, Hash)] pub struct PeerConfig { + /// Public key corresponding to the private key in [`TunnelConfig`]. pub public_key: PublicKey, + /// Addresses that may be routed to the peer. Use `0.0.0.0/0` to route everything. pub allowed_ips: Vec, + /// IP of the WireGuard server. pub endpoint: SocketAddr, } #[derive(Clone, Eq, PartialEq, Deserialize, Serialize, Debug)] pub struct TunnelConfig { pub private_key: PrivateKey, + /// Local IP addresses associated with a key pair. pub addresses: Vec, } -/// Wireguard tunnel options +/// Options in [`TunnelParameters`] that apply to any WireGuard connection. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[cfg_attr(target_os = "android", derive(IntoJava))] #[cfg_attr( diff --git a/talpid-types/src/tunnel.rs b/talpid-types/src/tunnel.rs index a921d1ba0cc1..dda152d3f151 100644 --- a/talpid-types/src/tunnel.rs +++ b/talpid-types/src/tunnel.rs @@ -4,7 +4,8 @@ use jnix::IntoJava; use serde::{Deserialize, Serialize}; use std::fmt; -/// Event resulting from a transition to a new tunnel state. +/// Event emitted from the states in `talpid_core::tunnel_state_machine` when the tunnel state +/// machine enters a new state. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] #[serde(tag = "state", content = "details")] @@ -17,7 +18,7 @@ pub enum TunnelStateTransition { Connected(TunnelEndpoint), /// Disconnecting tunnel. Disconnecting(ActionAfterDisconnect), - /// Tunnel is disconnected but secured by blocking all connections. + /// Tunnel is disconnected but usually secured by blocking all connections. Error(ErrorState), } @@ -32,7 +33,7 @@ pub enum ActionAfterDisconnect { Reconnect, } -/// Error state +/// Represents the tunnel state machine entering an error state during a [`TunnelStateTransition`]. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] #[cfg_attr(target_os = "android", derive(IntoJava))] @@ -62,7 +63,7 @@ impl ErrorState { } -/// Reason for entering the blocked state. +/// Reason for the tunnel state machine entering an [`ErrorState`]. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] #[serde(tag = "reason", content = "details")]