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}