ts_control/
lib.rs

1#![doc = include_str!("../README.md")]
2
3extern crate alloc;
4
5/// Package version of `ts_control` as reported by cargo.
6// TODO(npry): this is used to populate Hostinfo.ipn_version, which requests "long format":
7//  attach build info and whatever else that entails
8const PKG_VERSION: &str = if let Some(version) = option_env!("CARGO_PKG_VERSION") {
9    version
10} else {
11    ""
12};
13
14/// Client-side ACME (Let's Encrypt) DNS-01 cert issuance engine (`acme` feature, SaaS-only).
15#[cfg(feature = "acme")]
16pub mod acme;
17#[cfg(feature = "async_tokio")]
18mod cert;
19mod config;
20mod control_dialer;
21mod derp;
22mod dial_plan;
23mod dns;
24#[cfg_attr(not(feature = "async_tokio"), expect(dead_code))]
25mod map_request_builder;
26mod node;
27#[cfg(feature = "async_tokio")]
28mod serve;
29mod service;
30mod ssh_policy;
31mod tka;
32#[cfg(feature = "async_tokio")]
33mod tokio;
34#[cfg(feature = "identity-federation")]
35pub mod wif;
36
37use std::fmt;
38
39#[cfg(feature = "async_tokio")]
40pub use cert::{
41    CertError, MISSING_CERT_RPC, certified_key_from_pem, get_certificate, is_tailnet_name,
42};
43#[cfg(feature = "acme")]
44pub use cert::{PublishTxt, SetDnsPublisher, issue_certificate_via_setdns};
45#[doc(inline)]
46pub use config::{
47    Config, DEFAULT_CONTROL_SERVER, ExitProxyConfig, ExitProxyScheme, TransportMode, TunConfig,
48    services_hash,
49};
50pub use control_dialer::{ControlDialer, TcpDialer, complete_connection};
51pub use derp::{Map as DerpMap, Region as DerpRegion, convert_derp_map};
52pub use dial_plan::{DialCandidate, DialMode, DialPlan};
53pub use dns::{DnsConfig, ExtraRecord, Resolver as DnsResolver, ResolverTransport};
54pub use node::{
55    ExitNodeSelector, Id as NodeId, Node, NodeCapMap, StableId as StableNodeId, TailnetAddress,
56    UserProfile, is_tailscale_ip, validate_service_name,
57};
58#[cfg(feature = "async_tokio")]
59pub use serve::{
60    FunnelError, FunnelOptions, MISSING_FUNNEL_RELAY, ServeConfig, ServeState, ServeTarget,
61    accept_tls, funnel_access, listen_funnel, listen_tls, tls_acceptor,
62};
63pub use service::{ServiceError, ServiceMode, resolve_service_listen};
64pub use ssh_policy::{
65    SshAccept, SshAction, SshConnIdentity, SshDecision, SshDenyReason, SshPolicy, SshPrincipal,
66    SshRule,
67};
68pub use tka::TkaStatus;
69pub use ts_control_serde::{Endpoint, EndpointType, UserId};
70#[cfg(feature = "identity-federation")]
71pub use wif::{WifConfig, WifError, resolve_auth_key};
72
73/// Re-exported TLS types from the `tokio-rustls`/`ring` stack used by `cert`/`serve`, so
74/// embedders can name [`get_certificate`]/[`listen_tls`] return types without taking their own
75/// direct `tokio-rustls` dependency (and risking a second, mismatched crypto provider).
76#[cfg(feature = "async_tokio")]
77pub mod tls {
78    pub use tokio_rustls::{TlsAcceptor, rustls::sign::CertifiedKey, server::TlsStream};
79}
80
81#[cfg(feature = "async_tokio")]
82pub use crate::tokio::{
83    AsyncControlClient, FilterUpdate, IdTokenError, LogoutError, LogoutInternalErrorKind,
84    PeerUpdate, StateUpdate, fetch_id_token, logout,
85};
86
87/// An error which occurred while connecting to the control server or control plane.
88#[derive(Debug, thiserror::Error, Clone, Eq, PartialEq)]
89pub enum Error {
90    /// A machine was not authorized by control to join tailnet; authorize via the supplied URL.
91    #[error("machine was not authorized by control to join tailnet, authorize at {0}")]
92    MachineNotAuthorized(url::Url),
93
94    /// The user supplied an invalid URL.
95    #[error("invalid URL: {0}")]
96    InvalidUrl(url::Url),
97
98    /// Control rejected registration with a specific reason (e.g. a bad/expired/unknown auth key).
99    /// The string is control's verbatim `RegisterResponse.Error` message.
100    #[error("control rejected registration: {0}")]
101    Registration(String),
102
103    /// Some kind of networking error.
104    ///
105    /// These might be addressed by retrying, or might be an unresolvable error.
106    ///
107    /// [`Operation`] is intended to be informational, rather then inspected during handling.
108    #[error("a networking error occurred in {0}")]
109    NetworkError(Operation),
110
111    /// An internal error that users of the library are not expected to handle.
112    ///
113    /// [`InternalErrorKind`] and [`Operation`] are intended to be informational, rather then
114    /// inspected during handling.
115    #[error("{0} error in {1}")]
116    Internal(InternalErrorKind, Operation),
117}
118
119impl Error {
120    fn io_error(err: std::io::Error, op: Operation) -> Self {
121        if crate::is_network_error(&err) {
122            Error::NetworkError(op)
123        } else {
124            Error::Internal(InternalErrorKind::Io, op)
125        }
126    }
127}
128
129/// What kind of internal error has occurred.
130///
131/// This is intended to be useful for reporting a crash to an end user, rather than being handled.
132#[non_exhaustive]
133#[derive(Debug, Clone, Copy, Eq, PartialEq)]
134pub enum InternalErrorKind {
135    /// An error in URL parsing.
136    Url,
137    /// An unsuccessful HTTP request or upgrade.
138    Http,
139    /// An error in serialization or deserialization.
140    SerDe,
141    /// An error in I/O.
142    Io,
143    /// An invalid message format.
144    MessageFormat,
145    /// An error parsing a string as UTF8.
146    Utf8,
147    /// Noise framework handshake.
148    NoiseHandshake,
149    /// Tailscale challenge packet.
150    Challenge,
151    /// The user's machine was not authorized to register with a Tailnet and there is no URL for
152    /// the user to authorize at.
153    MachineAuthorization,
154}
155
156impl fmt::Display for InternalErrorKind {
157    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
158        match self {
159            InternalErrorKind::Url => write!(f, "URL parsing error"),
160            InternalErrorKind::Http => write!(f, "unsuccessful HTTP request or upgrade"),
161            InternalErrorKind::SerDe => write!(f, "serialization/deserialization error"),
162            InternalErrorKind::Io => write!(f, "I/O error"),
163            InternalErrorKind::MessageFormat => write!(f, "message format error"),
164            InternalErrorKind::Utf8 => write!(f, "invalid UTF8"),
165            InternalErrorKind::NoiseHandshake => write!(f, "error in Noise handshake"),
166            InternalErrorKind::Challenge => write!(f, "error with Tailscale challenge packet"),
167            InternalErrorKind::MachineAuthorization => {
168                write!(f, "machine not authorized to register with Tailnet")
169            }
170        }
171    }
172}
173
174/// The phase of connecting the control plane to a Tailnet in which an error occurs.
175#[derive(Debug, Clone, Copy, Eq, PartialEq)]
176pub enum Operation {
177    /// Requesting a net map.
178    MapRequest,
179    /// Connecting to a control server.
180    ConnectToControlServer,
181    /// Registering the user's device with a Tailnet.
182    Registration,
183}
184
185impl fmt::Display for Operation {
186    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
187        match self {
188            Operation::MapRequest => write!(f, "net map request"),
189            Operation::ConnectToControlServer => write!(f, "connection to control server"),
190            Operation::Registration => write!(f, "registration"),
191        }
192    }
193}
194
195impl From<ts_http_util::Error> for Error {
196    fn from(error: ts_http_util::Error) -> Self {
197        tracing::error!(%error, "http error");
198
199        if http_error_is_recoverable(error) {
200            Error::NetworkError(Operation::ConnectToControlServer)
201        } else {
202            Error::Internal(InternalErrorKind::Http, Operation::ConnectToControlServer)
203        }
204    }
205}
206
207/// Returns true if the input io error should be classed as a network error.
208fn is_network_error(err: &std::io::Error) -> bool {
209    use std::io::ErrorKind::*;
210    matches!(
211        err.kind(),
212        ConnectionRefused
213            | ConnectionReset
214            | HostUnreachable
215            | NetworkUnreachable
216            | ConnectionAborted
217            | NotConnected
218            | TimedOut
219            | AddrNotAvailable
220            | Interrupted
221            | NetworkDown
222    )
223}
224
225/// Returns true if the error is likely to be a transient network error.
226fn http_error_is_recoverable(error: ts_http_util::Error) -> bool {
227    match error {
228        ts_http_util::Error::Io => true,
229        ts_http_util::Error::InvalidInput
230        // A TCP timeout (recoverable) should get classed as an IO error, so any other kind of
231        // timeout is probably not.
232        | ts_http_util::Error::Timeout
233        | ts_http_util::Error::InvalidResponse => false,
234        // In the future, this might be recoverable with a reset.
235        ts_http_util::Error::ConnectionClosed => false,
236    }
237}
ts_control/lib.rs

ts_control/
lib.rs
