vatsim_api/lib.rs
1//! Rust types, async client, and mock server for the
2//! [VATSIM](https://vatsim.net/) network APIs.
3//!
4//! This crate provides strongly-typed bindings for the public VATSIM APIs used
5//! by the flight simulation community. It currently covers three of them:
6//!
7//! - **[Data feed](https://vatsim.dev/api/data-api/get-network-data)** - a JSON
8//! snapshot of every pilot, controller, and ATIS station currently connected
9//! to the network.
10//! - **[Slurper](https://vatsim.dev/api/slurper-api/get-user-info)** - a CSV
11//! endpoint returning a single user's active connections.
12//! - **[Connect](https://vatsim.dev/api/connect-api)** - VATSIM's OAuth2
13//! provider, covered by the [types](types::connect) and the [mock] server.
14//! The [client] does not implement the OAuth2 flow.
15//!
16//! The data feed and slurper are unauthenticated; Connect needs a registered
17//! OAuth2 client. Further APIs listed at <https://vatsim.dev/> may be added in
18//! future releases.
19//!
20//! # Crate layout
21//!
22//! The crate is organized in three layers, each behind its own feature flag:
23//!
24//! | Layer | Feature | Description |
25//! |-------|---------|-------------|
26//! | [`types`] | *(always available)* | Shared enums ([`Facility`](types::Facility), [`ControllerRating`](types::ControllerRating), etc.) and per-endpoint response structs ([`types::datafeed::DataFeed`], [`types::slurper::UserConnection`], [`types::connect::ConnectUser`]). |
27//! | [`client`] | `client` | Async HTTP client ([`VatsimClient`]) that fetches and caches live data. |
28//! | [`mock`] | `mock` | Embeddable mock server for integration testing. |
29//!
30//! # Feature flags
31//!
32//! | Feature | Default | Description |
33//! |---------|---------|-------------|
34//! | `serde` | **yes** | `Serialize`/`Deserialize` derives on all types. |
35//! | `chrono` | **yes** | Timestamps use `chrono::DateTime<Utc>` instead of raw strings. |
36//! | `client` | no | Enables [`VatsimClient`], an async HTTP client for the VATSIM APIs. |
37//! | `mock` | no | Enables the [`mock`] server, for integration testing without touching the live network. |
38//! | `mock-bin` | no | Builds `vatsim-mock`, a standalone binary of the mock server. |
39//! | `tracing` | no | Emits `tracing` spans and events from the mock server. |
40//!
41//! # Fetching live data
42//!
43//! [`VatsimClient`] discovers the data feed mirrors through the VATSIM status
44//! endpoint on first use, then caches both the mirror list and the feed itself.
45//! Use [`CachePolicy`] to decide whether a call may be served from that cache.
46//!
47//! ```rust,no_run
48//! # #[cfg(feature = "client")]
49//! # async fn example() -> Result<(), vatsim_api::ClientError> {
50//! use vatsim_api::{CachePolicy, VatsimClient};
51//!
52//! let client = VatsimClient::new();
53//!
54//! let feed = client.datafeed(CachePolicy::Cached).await?;
55//! for controller in &feed.controllers {
56//! println!("{} on {}", controller.callsign, controller.frequency);
57//! }
58//!
59//! // The slurper answers "is this user online right now", which the data feed
60//! // can only tell you by scanning every entry.
61//! let connections = client.user_connections(1_000_001.into()).await?;
62//! println!("{} active connection(s)", connections.len());
63//! # Ok(())
64//! # }
65//! ```
66//!
67//! # Testing against a mock network
68//!
69//! [`MockServer`] serves the same endpoints from in-memory state, so tests can
70//! put a controller online, take them offline, or walk a full OAuth2 login
71//! without touching VATSIM. The server shuts down when its handle is dropped.
72//!
73//! ```rust,no_run
74//! # #[cfg(all(feature = "mock", feature = "client"))]
75//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
76//! use vatsim_api::mock::MockServer;
77//! use vatsim_api::types::datafeed::Controller;
78//! use vatsim_api::{CachePolicy, CertificateId};
79//!
80//! let handle = MockServer::builder()
81//! .controllers(vec![Controller {
82//! cid: CertificateId::new(1_000_001),
83//! callsign: "LOWW_TWR".to_owned(),
84//! frequency: "121.500".to_owned(),
85//! ..Default::default()
86//! }])
87//! .spawn()
88//! .await?;
89//!
90//! let feed = handle.client().datafeed(CachePolicy::Refresh).await?;
91//! assert_eq!(feed.controllers.len(), 1);
92//! # Ok(())
93//! # }
94//! ```
95//!
96//! # Driving the mock at runtime
97//!
98//! Test code can reach the server's state directly through
99//! [`MockServerHandle::state`], which avoids a round trip and is the easiest way
100//! to simulate a controller connecting or disconnecting mid-test. The same
101//! operations are also available over HTTP under `/api/`, for test suites that
102//! are not written in Rust.
103//!
104//! ```rust,no_run
105//! # #[cfg(feature = "mock")]
106//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
107//! use vatsim_api::CertificateId;
108//! use vatsim_api::mock::MockServer;
109//!
110//! let handle = MockServer::builder().spawn().await?;
111//!
112//! // Take a controller offline part-way through a test.
113//! handle
114//! .state()
115//! .write()
116//! .await
117//! .remove_controller(CertificateId::new(1_000_001));
118//! # Ok(())
119//! # }
120//! ```
121//!
122//! # Public dependencies
123//!
124//! `chrono`, `serde`, `tokio` and `reqwest` appear in this crate's public API,
125//! so a major version bump of any of them is a breaking change here. `chrono`
126//! and `reqwest` are re-exported ([`chrono`], [`reqwest`]) so that consumers can
127//! depend on exactly the versions this crate was built against.
128
129#![warn(clippy::pedantic, missing_docs)]
130// VATSIM, OAuth2, CID and similar acronyms read fine in prose without backticks.
131#![allow(clippy::doc_markdown)]
132#![cfg_attr(docsrs, feature(doc_cfg))]
133// The crate-level docs link into the feature-gated `client` and `mock` modules.
134// docs.rs builds with all features so those links resolve there; in a
135// reduced-feature build the items genuinely do not exist, which is not a defect
136// worth failing the doc build over.
137#![cfg_attr(
138 not(all(feature = "client", feature = "mock")),
139 allow(rustdoc::broken_intra_doc_links)
140)]
141
142pub mod error;
143pub mod types;
144
145#[cfg(feature = "client")]
146#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
147pub mod client;
148
149#[cfg(feature = "mock")]
150#[cfg_attr(docsrs, doc(cfg(feature = "mock")))]
151pub mod mock;
152
153#[cfg(feature = "chrono")]
154#[cfg_attr(docsrs, doc(cfg(feature = "chrono")))]
155pub use chrono;
156
157#[cfg(feature = "client")]
158#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
159pub use reqwest;
160
161pub use error::ParseError;
162pub use types::CertificateId;
163
164#[cfg(feature = "client")]
165pub use client::{CachePolicy, ClientConfig, VatsimClient};
166
167#[cfg(feature = "client")]
168pub use error::ClientError;
169
170#[cfg(feature = "mock")]
171pub use mock::{MockServer, MockServerBuilder, MockServerHandle};