Skip to main content

hpr_net/
lib.rs

1//! Optional online data sources with an on-disk cache and an explicit offline mode: weather,
2//! soundings, elevation, ThrustCurve and motor stock.
3//!
4//! [Online data and the cache][guide-page] says what works today and what is planned.
5//!
6//! [guide-page]: https://hpr.fusionspace.co/online-data.html
7//! [weather]: https://hpr.fusionspace.co/weather.html
8//! [soundings]: https://hpr.fusionspace.co/soundings.html
9//! [nomads]: https://hpr.fusionspace.co/nomads.html
10//! [elevation]: https://hpr.fusionspace.co/elevation.html
11//! [motor-stock]: https://hpr.fusionspace.co/motor-stock.html
12//!
13//! Status: pre-alpha, with six data sources:
14//!
15//! - [`open_meteo`]: a launch site's weather as a sounding, the first of the weather sources. The
16//!   [weather page][weather] explains it.
17//! - [`wyoming`]: weather-balloon soundings from the University of Wyoming's archive (the
18//!   [soundings page][soundings]).
19//! - [`nomads`]: NOAA's GFS and RAP forecasts as GRIB2 cuts from NOMADS (the [NOAA forecasts
20//!   page][nomads]).
21//! - [`elevation`]: a site's ground height from Open-Meteo (the [elevation page][elevation]).
22//! - [`motor_finder`]: motor stock and prices from motor.fusionspace.co (the [motor stock
23//!   page][motor-stock]).
24//! - [`thrustcurve`]: motor records and thrust curves from ThrustCurve.org, matched to the motors
25//!   in stock (the same page). [`on_demand`] finds one motor there by name, for a simulator that
26//!   lacks its curve.
27//!
28//! This crate does network and file I/O, so it's never a dependency of the pure core. A
29//! [`Client`] asks a [`Transport`] for a URL's bytes only when it's [`Mode::Online`] and its
30//! [`Cache`] holds no fresh copy. In [`Mode::Offline`] it never calls the transport. It answers
31//! from the cache, stale or not, and says which. The `http` feature adds `Http`, the transport
32//! over HTTP and HTTPS (rustls, no OpenSSL). [`Cache::platform_dir`] names the platform's usual
33//! cache folder.
34//!
35//! ```
36//! use hpr_net::{Cache, Client, Freshness, Mode, NetError, Source, Transport};
37//!
38//! /// A transport that answers every URL with the same bytes.
39//! struct Canned;
40//! impl Transport for Canned {
41//!     fn get(&self, _url: &str) -> Result<Vec<u8>, String> {
42//!         Ok(b"42".to_vec())
43//!     }
44//! }
45//!
46//! let dir = std::env::temp_dir().join(format!("hpr-net-doc-{}", std::process::id()));
47//! let source = Source {
48//!     name: "Example".into(),
49//!     attribution: "Example data".into(),
50//!     ttl_s: 3600,
51//! };
52//! let url = "https://example.test/x";
53//! let online = Client::new(Canned, Cache::new(&dir), Mode::Online);
54//! assert_eq!(online.fetch(&source, url, 1_000)?.freshness, Freshness::Fetched);
55//!
56//! let offline = Client::new(Canned, Cache::new(&dir), Mode::Offline);
57//! let later = offline.fetch(&source, url, 1_000 + 7_200)?;
58//! assert_eq!((later.freshness, later.body.as_slice()), (Freshness::Stale, &b"42"[..]));
59//! # std::fs::remove_dir_all(&dir).ok();
60//! # Ok::<(), NetError>(())
61//! ```
62
63// Outside bytes reach casts here. An `as` cast of a length or count truncates silently where
64// `usize` is 32 bits (wasm32), and one from a float saturates: each cast is checked with
65// `try_from`, or its `allow` says why it is exact or meant.
66#![warn(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
67#![cfg_attr(
68    test,
69    allow(
70        clippy::cast_possible_truncation,
71        clippy::cast_sign_loss,
72        clippy::panic_in_result_fn,
73        reason = "a test builds its own inputs and fails by panicking"
74    )
75)]
76#![allow(
77    clippy::disallowed_methods,
78    clippy::disallowed_types,
79    reason = "the online layer does network and cache I/O; it is not part of the pure core"
80)]
81
82mod cache;
83pub mod catalog_update;
84mod civil;
85mod client;
86mod coordinate;
87pub mod elevation;
88#[cfg(feature = "http")]
89mod http;
90pub mod motor_finder;
91pub mod nomads;
92pub mod on_demand;
93pub mod open_meteo;
94pub mod thrustcurve;
95pub mod wyoming;
96
97pub use cache::{Cache, CacheEntry};
98pub use client::{Client, Fetched, Freshness, Mode, Replay, Source, Transport};
99#[cfg(feature = "http")]
100pub use http::{Http, HttpConfig, SOCKS_REFUSED};
101
102/// Why a fetch failed.
103#[non_exhaustive]
104#[derive(Debug, thiserror::Error)]
105pub enum NetError {
106    /// Offline, and the cache holds no copy of the URL.
107    #[error("offline and {url} is not in the cache")]
108    NotCached {
109        /// The URL asked for.
110        url: String,
111    },
112    /// The transport failed (no connection, an HTTP error status, a timeout).
113    #[error("fetching {url} failed: {reason}")]
114    Transport {
115        /// The URL asked for.
116        url: String,
117        /// What the transport said.
118        reason: String,
119    },
120    /// A body was fetched or cached, but the data source's check refused it
121    /// ([`Client::fetch_checked`]); nothing was cached.
122    #[error("the answer for {url} was refused: {reason}")]
123    Refused {
124        /// The URL asked for.
125        url: String,
126        /// Why the check refused it.
127        reason: String,
128    },
129    /// Reading or writing the cache failed.
130    #[error("cache I/O at {path}: {source}")]
131    Cache {
132        /// The file involved.
133        path: std::path::PathBuf,
134        /// The underlying error.
135        source: std::io::Error,
136    },
137    /// A cache entry's metadata did not parse.
138    #[error("cache entry {path} is corrupt: {reason}")]
139    CorruptEntry {
140        /// The metadata file.
141        path: std::path::PathBuf,
142        /// What was wrong.
143        reason: String,
144    },
145}