Skip to main content

Crate vatsim_api

Crate vatsim_api 

Source
Expand description

Rust types, async client, and mock server for the VATSIM 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 - a JSON snapshot of every pilot, controller, and ATIS station currently connected to the network.
  • Slurper - a CSV endpoint returning a single user’s active connections.
  • Connect - VATSIM’s OAuth2 provider, covered by the types 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:

LayerFeatureDescription
types(always available)Shared enums (Facility, ControllerRating, etc.) and per-endpoint response structs (types::datafeed::DataFeed, types::slurper::UserConnection, types::connect::ConnectUser).
clientclientAsync HTTP client (VatsimClient) that fetches and caches live data.
mockmockEmbeddable mock server for integration testing.

§Feature flags

FeatureDefaultDescription
serdeyesSerialize/Deserialize derives on all types.
chronoyesTimestamps use chrono::DateTime<Utc> instead of raw strings.
clientnoEnables VatsimClient, an async HTTP client for the VATSIM APIs.
mocknoEnables the mock server, for integration testing without touching the live network.
mock-binnoBuilds vatsim-mock, a standalone binary of the mock server.
tracingnoEmits 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.

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());

§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.

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);

§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.

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));

§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.

Re-exports§

pub use error::ParseError;
pub use types::CertificateId;
pub use client::CachePolicy;client
pub use client::ClientConfig;client
pub use client::VatsimClient;client
pub use error::ClientError;client
pub use mock::MockServer;mock
pub use mock::MockServerBuilder;mock
pub use mock::MockServerHandle;mock
pub use chrono;chrono
pub use reqwest;client

Modules§

clientclient
Async HTTP client for the VATSIM APIs.
error
Error types shared across the crate.
mockmock
Embeddable mock server for integration testing and standalone deployment.
types
Core types shared across VATSIM APIs.