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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
//! Rust types, async client, and mock server for the
//! [VATSIM](https://vatsim.net/) network APIs.
//!
//! This crate provides strongly-typed bindings for the public VATSIM APIs used
//! by the flight simulation community. It currently covers three of them:
//!
//! - **[Data feed](https://vatsim.dev/api/data-api/get-network-data)** - a JSON
//! snapshot of every pilot, controller, and ATIS station currently connected
//! to the network.
//! - **[Slurper](https://vatsim.dev/api/slurper-api/get-user-info)** - a CSV
//! endpoint returning a single user's active connections.
//! - **[Connect](https://vatsim.dev/api/connect-api)** - VATSIM's OAuth2
//! provider, covered by the [types](types::connect) and the [mock] server.
//! The [client] does not implement the OAuth2 flow.
//!
//! The data feed and slurper are unauthenticated; Connect needs a registered
//! OAuth2 client. Further APIs listed at <https://vatsim.dev/> may be added in
//! future releases.
//!
//! # Crate layout
//!
//! The crate is organized in three layers, each behind its own feature flag:
//!
//! | Layer | Feature | Description |
//! |-------|---------|-------------|
//! | [`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`]). |
//! | [`client`] | `client` | Async HTTP client ([`VatsimClient`]) that fetches and caches live data. |
//! | [`mock`] | `mock` | Embeddable mock server for integration testing. |
//!
//! # Feature flags
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | `serde` | **yes** | `Serialize`/`Deserialize` derives on all types. |
//! | `chrono` | **yes** | Timestamps use `chrono::DateTime<Utc>` instead of raw strings. |
//! | `client` | no | Enables [`VatsimClient`], an async HTTP client for the VATSIM APIs. |
//! | `mock` | no | Enables the [`mock`] server, for integration testing without touching the live network. |
//! | `mock-bin` | no | Builds `vatsim-mock`, a standalone binary of the mock server. |
//! | `tracing` | no | Emits `tracing` spans and events from the mock server. |
//!
//! # Fetching live data
//!
//! [`VatsimClient`] discovers the data feed mirrors through the VATSIM status
//! endpoint on first use, then caches both the mirror list and the feed itself.
//! Use [`CachePolicy`] to decide whether a call may be served from that cache.
//!
//! ```rust,no_run
//! # #[cfg(feature = "client")]
//! # async fn example() -> Result<(), vatsim_api::ClientError> {
//! use vatsim_api::{CachePolicy, VatsimClient};
//!
//! let client = VatsimClient::new();
//!
//! let feed = client.datafeed(CachePolicy::Cached).await?;
//! for controller in &feed.controllers {
//! println!("{} on {}", controller.callsign, controller.frequency);
//! }
//!
//! // The slurper answers "is this user online right now", which the data feed
//! // can only tell you by scanning every entry.
//! let connections = client.user_connections(1_000_001.into()).await?;
//! println!("{} active connection(s)", connections.len());
//! # Ok(())
//! # }
//! ```
//!
//! # Testing against a mock network
//!
//! [`MockServer`] serves the same endpoints from in-memory state, so tests can
//! put a controller online, take them offline, or walk a full OAuth2 login
//! without touching VATSIM. The server shuts down when its handle is dropped.
//!
//! ```rust,no_run
//! # #[cfg(all(feature = "mock", feature = "client"))]
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! use vatsim_api::mock::MockServer;
//! use vatsim_api::types::datafeed::Controller;
//! use vatsim_api::{CachePolicy, CertificateId};
//!
//! let handle = MockServer::builder()
//! .controllers(vec![Controller {
//! cid: CertificateId::new(1_000_001),
//! callsign: "LOWW_TWR".to_owned(),
//! frequency: "121.500".to_owned(),
//! ..Default::default()
//! }])
//! .spawn()
//! .await?;
//!
//! let feed = handle.client().datafeed(CachePolicy::Refresh).await?;
//! assert_eq!(feed.controllers.len(), 1);
//! # Ok(())
//! # }
//! ```
//!
//! # Driving the mock at runtime
//!
//! Test code can reach the server's state directly through
//! [`MockServerHandle::state`], which avoids a round trip and is the easiest way
//! to simulate a controller connecting or disconnecting mid-test. The same
//! operations are also available over HTTP under `/api/`, for test suites that
//! are not written in Rust.
//!
//! ```rust,no_run
//! # #[cfg(feature = "mock")]
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! use vatsim_api::CertificateId;
//! use vatsim_api::mock::MockServer;
//!
//! let handle = MockServer::builder().spawn().await?;
//!
//! // Take a controller offline part-way through a test.
//! handle
//! .state()
//! .write()
//! .await
//! .remove_controller(CertificateId::new(1_000_001));
//! # Ok(())
//! # }
//! ```
//!
//! # Public dependencies
//!
//! `chrono`, `serde`, `tokio` and `reqwest` appear in this crate's public API,
//! so a major version bump of any of them is a breaking change here. `chrono`
//! and `reqwest` are re-exported ([`chrono`], [`reqwest`]) so that consumers can
//! depend on exactly the versions this crate was built against.
// VATSIM, OAuth2, CID and similar acronyms read fine in prose without backticks.
// The crate-level docs link into the feature-gated `client` and `mock` modules.
// docs.rs builds with all features so those links resolve there; in a
// reduced-feature build the items genuinely do not exist, which is not a defect
// worth failing the doc build over.
pub use chrono;
pub use reqwest;
pub use ParseError;
pub use CertificateId;
pub use ;
pub use ClientError;
pub use ;