Skip to main content

hpr_net/
thrustcurve.rs

1//! Motor records and thrust curves from [ThrustCurve.org](https://www.thrustcurve.org)'s API, and
2//! the join that gives a motor in stock its curve.
3//!
4//! ThrustCurve.org aims to hold every certified hobby motor's published figures and the simulator
5//! files (thrust curves) people have contributed for them. Its [API][api] answers two questions: a
6//! *search* ([`Search`], read by [`parse_search`]), which lists motor records, each with
7//! ThrustCurve's own id, its `motorId`; and a *download* ([`Download`], read by
8//! [`parse_download`]), which gives a motor's data files, each a RASP (`.eng`) or RockSim (`.rse`)
9//! file that [`DataFile::read`] hands to `hpr_motor`'s readers. The `fetch_` functions ask a
10//! [`Client`] for the answer, so it comes from the cache when it can, and offline from the cache
11//! only; an answer that doesn't parse is never cached. Motor records and curves change seldom, so
12//! a copy stays fresh for [`TTL_S`], a day. Show [`ATTRIBUTION`] (it is on every [`Fetched`])
13//! wherever the data is shown.
14//!
15//! [`join`] maps the motor finder's motors ([`crate::motor_finder`]) to ThrustCurve records. The
16//! finder carries no ThrustCurve id, but spells each designation as ThrustCurve does, so a motor
17//! maps when exactly one record has its manufacturer's full name and its designation, character
18//! for character. Anything else is a [`Miss`], with its reason, and [`Join::report`] lists them.
19//! [`fetch_finder_records`] fetches the records the join needs: one search per maker the finder
20//! reads.
21//!
22//! > **How far to trust it.** A value is the answer's, unchanged (`tests/thrustcurve.rs` reads every
23//! > field of every committed answer back: two downloads recorded on 2026-10-01, and three makers'
24//! > searches recorded on 2026-10-29, ThrustCurve's records used as published facts under
25//! > [ADR-287][adr-287]). A curve is the file a contributor uploaded, as ThrustCurve serves it,
26//! > read by the same readers as a file on disk. The join is by name only: it doesn't compare
27//! > impulse or diameter, so a finder motor whose designation ThrustCurve spells differently is a
28//! > miss, not a wrong match. On ThrustCurve's answers of 2026-10-01, and again on those of
29//! > 2026-10-29, 282 of the finder's 282 motors in stock mapped, each to one record.
30//!
31//! ```
32//! use hpr_net::thrustcurve;
33//!
34//! // AeroTech's J450DM curve as ThrustCurve.org served it on 2026-10-01.
35//! let body = include_bytes!("../tests/fixtures/replay/thrustcurve-download-J450DM.json");
36//! let answer = thrustcurve::parse_download(body)?;
37//! let curve = answer.results[0].read()?.thrust_curve()?;
38//! // The file's 36 points, after the curve's start at zero thrust.
39//! assert_eq!((curve.times_s().len(), curve.end_time_s()), (37, 2.311));
40//! # Ok::<(), Box<dyn std::error::Error>>(())
41//! ```
42//!
43//! [adr-287]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/decisions/0287-thrustcurve-orgs-motor-records-used-as-published-facts.md
44//! [api]: https://www.thrustcurve.org/info/api.html
45
46use std::collections::BTreeMap;
47use std::fmt::Write as _;
48
49use base64::Engine as _;
50use hpr_motor::text::Parsed;
51use hpr_motor::{MotorError, ThrustCurve, eng, rse};
52use serde::{Deserialize, Serialize};
53
54use crate::motor_finder::{self, MANUFACTURERS};
55use crate::{Client, Fetched, NetError, Source, Transport};
56
57/// The API's base URL, version 1 of its JSON endpoints.
58pub const BASE_URL: &str = "https://www.thrustcurve.org/api/v1";
59
60/// How long a cached answer counts as fresh, s: a day. Motor records and curves change seldom.
61pub const TTL_S: u64 = 86_400;
62
63/// The most records a search asks for. ThrustCurve's whole database held 1,156 motors on
64/// 2026-10-01; a search that matches more than it returns is refused by
65/// [`fetch_finder_records`].
66pub const MAX_RESULTS: u32 = 5_000;
67
68/// The credit for ThrustCurve.org's data.
69pub const ATTRIBUTION: &str = "Motor data and thrust curves courtesy of ThrustCurve.org, \
70                               https://www.thrustcurve.org/";
71
72/// A motor search. Every field set narrows it; the API joins them with "and". Start from
73/// [`Search::manufacturer`] or `Search::default()` and set the fields wanted: more may be added.
74#[non_exhaustive]
75#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
76pub struct Search {
77    /// The manufacturer's name or abbreviation (`AeroTech`, `Cesaroni Technology`, `Loki`).
78    pub manufacturer: Option<String>,
79    /// The manufacturer's designation (`J450DM`, `F27R/L`).
80    pub designation: Option<String>,
81    /// The common name (`J450`).
82    pub common_name: Option<String>,
83    /// The impulse class letter (`L`).
84    pub impulse_class: Option<String>,
85    /// The most records to return; the API's own default when `None`.
86    pub max_results: Option<u32>,
87}
88
89impl Search {
90    /// Every motor of one manufacturer, up to [`MAX_RESULTS`].
91    #[must_use]
92    pub fn manufacturer(name: &str) -> Self {
93        Self {
94            manufacturer: Some(name.to_owned()),
95            max_results: Some(MAX_RESULTS),
96            ..Self::default()
97        }
98    }
99
100    /// The search's URL under [`BASE_URL`]: its fields as query parameters, in the order of the
101    /// struct, each value percent-encoded; no query at all when no field is set.
102    #[must_use]
103    pub fn url(&self) -> String {
104        let max_results = self.max_results.map(|n| n.to_string());
105        let fields = [
106            ("manufacturer", self.manufacturer.as_deref()),
107            ("designation", self.designation.as_deref()),
108            ("commonName", self.common_name.as_deref()),
109            ("impulseClass", self.impulse_class.as_deref()),
110            ("maxResults", max_results.as_deref()),
111        ];
112        let query: Vec<String> = fields
113            .iter()
114            .filter_map(|(name, value)| Some(format!("{name}={}", encode(value.as_ref()?))))
115            .collect();
116        if query.is_empty() {
117            return format!("{BASE_URL}/search.json");
118        }
119        format!("{BASE_URL}/search.json?{}", query.join("&"))
120    }
121}
122
123/// A data file's format, as the API names it.
124#[non_exhaustive]
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
126pub enum Format {
127    /// RASP, a `.eng` file.
128    #[serde(rename = "RASP")]
129    Rasp,
130    /// RockSim, a `.rse` file.
131    #[serde(rename = "RockSim")]
132    RockSim,
133}
134
135impl Format {
136    /// The API's word for it.
137    #[must_use]
138    pub fn as_str(self) -> &'static str {
139        match self {
140            Self::Rasp => "RASP",
141            Self::RockSim => "RockSim",
142        }
143    }
144}
145
146/// A request for one motor's data files, in one format. Build it with [`Download::new`], which
147/// checks the motor id.
148#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
149pub struct Download {
150    motor_id: String,
151    format: Format,
152}
153
154impl Download {
155    /// A motor's data files in `format`, by its ThrustCurve id, in either case: it is kept in
156    /// lower case, as the API writes ids, so one motor has one URL and its answer matches.
157    ///
158    /// # Errors
159    /// [`ThrustCurveError::Request`] for an id that isn't 24 hexadecimal digits, the form the
160    /// API's ids take.
161    pub fn new(motor_id: &str, format: Format) -> Result<Self, ThrustCurveError> {
162        if !is_motor_id(motor_id) {
163            return Err(ThrustCurveError::Request {
164                what: "motor id",
165                value: motor_id.to_owned(),
166            });
167        }
168        Ok(Self {
169            motor_id: motor_id.to_ascii_lowercase(),
170            format,
171        })
172    }
173
174    /// The motor's ThrustCurve id, in lower case.
175    #[must_use]
176    pub fn motor_id(&self) -> &str {
177        &self.motor_id
178    }
179
180    /// The format asked for.
181    #[must_use]
182    pub fn format(&self) -> Format {
183        self.format
184    }
185
186    /// The request's URL under [`BASE_URL`], asking for the files themselves (`data=file`).
187    #[must_use]
188    pub fn url(&self) -> String {
189        format!(
190            "{BASE_URL}/download.json?motorId={}&format={}&data=file",
191            self.motor_id,
192            self.format.as_str()
193        )
194    }
195}
196
197/// The [`Source`] a [`Client`] caches every answer under: ThrustCurve.org, its [`ATTRIBUTION`],
198/// and [`TTL_S`].
199#[must_use]
200pub fn source() -> Source {
201    Source {
202        name: "ThrustCurve.org".to_owned(),
203        attribution: ATTRIBUTION.to_owned(),
204        ttl_s: TTL_S,
205    }
206}
207
208/// A search's answer.
209#[non_exhaustive]
210#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
211pub struct SearchAnswer {
212    /// Each criterion asked, with how many motors it matches alone.
213    pub criteria: Vec<Criterion>,
214    /// How many motors match every criterion: more than [`SearchAnswer::results`] holds when the
215    /// search's `maxResults` cut it short.
216    pub matches: u32,
217    /// The motors returned.
218    pub results: Vec<MotorRecord>,
219    /// The page of the site's own search.
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub source_url: Option<String>,
222}
223
224impl SearchAnswer {
225    /// Whether it holds every motor that matched.
226    #[must_use]
227    pub fn is_complete(&self) -> bool {
228        usize::try_from(self.matches).ok() == Some(self.results.len())
229    }
230}
231
232/// One search criterion, as the answer echoes it.
233#[non_exhaustive]
234#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
235pub struct Criterion {
236    /// Its name (`manufacturer`).
237    pub name: String,
238    /// Its value, as text.
239    pub value: String,
240    /// How many motors it matches alone.
241    pub matches: u32,
242}
243
244/// One motor's record. The API returns only the fields that have values, so all but the id,
245/// manufacturer and designation are optional. Units are the API's: newtons, newton-seconds,
246/// seconds, millimeters and grams.
247#[non_exhaustive]
248#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
249#[serde(rename_all = "camelCase")]
250pub struct MotorRecord {
251    /// ThrustCurve's id, 24 hexadecimal digits: what a [`Download`] names.
252    pub motor_id: String,
253    /// The manufacturer's full name (`Cesaroni Technology`).
254    pub manufacturer: String,
255    /// Its short name (`Cesaroni`).
256    #[serde(skip_serializing_if = "Option::is_none")]
257    pub manufacturer_abbrev: Option<String>,
258    /// The manufacturer's designation (`3683L851-P`).
259    pub designation: String,
260    /// The common name (`L851`).
261    #[serde(skip_serializing_if = "Option::is_none")]
262    pub common_name: Option<String>,
263    /// The impulse class letter.
264    #[serde(skip_serializing_if = "Option::is_none")]
265    pub impulse_class: Option<String>,
266    /// The certifying body's name.
267    #[serde(skip_serializing_if = "Option::is_none")]
268    pub cert_org: Option<String>,
269    /// Diameter, mm.
270    #[serde(rename = "diameter", skip_serializing_if = "Option::is_none")]
271    pub diameter_mm: Option<f64>,
272    /// Length, mm.
273    #[serde(rename = "length", skip_serializing_if = "Option::is_none")]
274    pub length_mm: Option<f64>,
275    /// `SU` (single use), `reload` or `hybrid`, as the API writes it.
276    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
277    pub motor_type: Option<String>,
278    /// Average thrust, N.
279    #[serde(rename = "avgThrustN", skip_serializing_if = "Option::is_none")]
280    pub avg_thrust_n: Option<f64>,
281    /// Peak thrust, N.
282    #[serde(rename = "maxThrustN", skip_serializing_if = "Option::is_none")]
283    pub max_thrust_n: Option<f64>,
284    /// Total impulse, N·s.
285    #[serde(rename = "totImpulseNs", skip_serializing_if = "Option::is_none")]
286    pub total_impulse_ns: Option<f64>,
287    /// Burn time, s.
288    #[serde(rename = "burnTimeS", skip_serializing_if = "Option::is_none")]
289    pub burn_time_s: Option<f64>,
290    /// How many data files (curves) it has.
291    #[serde(skip_serializing_if = "Option::is_none")]
292    pub data_files: Option<u32>,
293    /// The certification or manufacturer's page.
294    #[serde(skip_serializing_if = "Option::is_none")]
295    pub info_url: Option<String>,
296    /// Loaded weight, g.
297    #[serde(rename = "totalWeightG", skip_serializing_if = "Option::is_none")]
298    pub total_weight_g: Option<f64>,
299    /// Propellant weight, g.
300    #[serde(rename = "propWeightG", skip_serializing_if = "Option::is_none")]
301    pub propellant_weight_g: Option<f64>,
302    /// The delays offered, as the API writes them (`6,10,14`, `P` for a plugged motor).
303    #[serde(skip_serializing_if = "Option::is_none")]
304    pub delays: Option<String>,
305    /// Whether the delay is cut to length by the flier.
306    #[serde(skip_serializing_if = "Option::is_none")]
307    pub delay_adjustable: Option<bool>,
308    /// The reload's case (`RMS-54/852`).
309    #[serde(skip_serializing_if = "Option::is_none")]
310    pub case_info: Option<String>,
311    /// The propellant's name (`Dark Matter`).
312    #[serde(skip_serializing_if = "Option::is_none")]
313    pub prop_info: Option<String>,
314    /// Whether the exhaust throws sparks.
315    #[serde(skip_serializing_if = "Option::is_none")]
316    pub sparky: Option<bool>,
317    /// When the record last changed, `YYYY-MM-DD`.
318    #[serde(skip_serializing_if = "Option::is_none")]
319    pub updated_on: Option<String>,
320    /// `regular`, `occasional` or `OOP` (out of production), as the API writes it.
321    #[serde(skip_serializing_if = "Option::is_none")]
322    pub availability: Option<String>,
323    /// The motor's page on the site.
324    #[serde(rename = "source_url", skip_serializing_if = "Option::is_none")]
325    pub source_url: Option<String>,
326}
327
328/// A download's answer.
329#[non_exhaustive]
330#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
331pub struct DownloadAnswer {
332    /// The data files: none for a motor with none in the format asked, or an unknown id.
333    pub results: Vec<DataFile>,
334}
335
336/// One data file of a motor.
337#[non_exhaustive]
338#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
339#[serde(rename_all = "camelCase")]
340pub struct DataFile {
341    /// The motor's ThrustCurve id.
342    pub motor_id: String,
343    /// The file's own id.
344    pub simfile_id: String,
345    /// Its format.
346    pub format: Format,
347    /// Who measured it, as the API writes it: `cert` (a certification test), `mfr` (the
348    /// manufacturer) or `user`.
349    #[serde(skip_serializing_if = "Option::is_none")]
350    pub source: Option<String>,
351    /// Its license, as the API writes it: `PD` (public domain), `free` or `other`; `None` when the
352    /// contributor named none.
353    #[serde(skip_serializing_if = "Option::is_none")]
354    pub license: Option<String>,
355    /// The file, base64-encoded; [`DataFile::text`] decodes it.
356    pub data: String,
357    /// The file's page on the site, as a path (`/simfiles/{id}/`).
358    #[serde(skip_serializing_if = "Option::is_none")]
359    pub info_url: Option<String>,
360    /// Where the site serves the file itself, as a path.
361    #[serde(skip_serializing_if = "Option::is_none")]
362    pub data_url: Option<String>,
363    /// The file's page, as a full URL.
364    #[serde(rename = "source_url", skip_serializing_if = "Option::is_none")]
365    pub source_url: Option<String>,
366}
367
368/// A data file read by `hpr_motor`.
369#[non_exhaustive]
370#[derive(Debug, Clone, PartialEq)]
371pub enum Curve {
372    /// A RASP file, read by [`hpr_motor::eng::parse`].
373    Rasp(Parsed<eng::EngFile>),
374    /// A RockSim file, read by [`hpr_motor::rse::parse`].
375    RockSim(Parsed<rse::RseFile>),
376}
377
378impl Curve {
379    /// The first motor's thrust curve: a RASP file's first entry, a RockSim file's first engine.
380    ///
381    /// # Errors
382    /// [`MotorError`] when the curve breaks `hpr_motor`'s rules, or the file holds no motor.
383    pub fn thrust_curve(&self) -> Result<ThrustCurve, MotorError> {
384        let none = || MotorError::Inconsistent("the file holds no motor".to_owned());
385        match self {
386            Self::Rasp(parsed) => parsed
387                .value
388                .entries
389                .first()
390                .ok_or_else(none)?
391                .thrust_curve(),
392            Self::RockSim(parsed) => parsed
393                .value
394                .engines
395                .first()
396                .ok_or_else(none)?
397                .thrust_curve(),
398        }
399    }
400}
401
402impl Curve {
403    /// The first motor's propellant mass, kg, as the file's header gives it: a RASP entry's in
404    /// kilograms, a RockSim engine's `propWt` in grams; `None` when the file holds no motor.
405    #[must_use]
406    pub fn propellant_mass_kg(&self) -> Option<f64> {
407        match self {
408            Self::Rasp(parsed) => parsed
409                .value
410                .entries
411                .first()
412                .map(|entry| entry.propellant_mass_kg),
413            Self::RockSim(parsed) => parsed
414                .value
415                .engines
416                .first()
417                .map(|engine| engine.propellant_mass_g / 1000.0),
418        }
419    }
420}
421
422impl DataFile {
423    /// The file's text: its data decoded from base64, as UTF-8.
424    ///
425    /// # Errors
426    /// [`ThrustCurveError::Field`] when the file isn't UTF-8, or (only in a file not read by
427    /// [`parse_download`], which refuses that) its data isn't base64. One file that isn't UTF-8
428    /// doesn't refuse the answer: the motor's other files stay readable.
429    pub fn text(&self) -> Result<String, ThrustCurveError> {
430        let bytes = base64::engine::general_purpose::STANDARD
431            .decode(&self.data)
432            .map_err(|e| field(format!("{}.data", self.simfile_id), e))?;
433        String::from_utf8(bytes)
434            .map_err(|e| field(format!("{}.data", self.simfile_id), e.utf8_error()))
435    }
436
437    /// The file read by `hpr_motor`'s reader for its format.
438    ///
439    /// # Errors
440    /// As [`DataFile::text`], and [`ThrustCurveError::Motor`] when the reader refuses the file.
441    pub fn read(&self) -> Result<Curve, ThrustCurveError> {
442        let text = self.text()?;
443        Ok(match self.format {
444            Format::Rasp => Curve::Rasp(eng::parse(&text)?),
445            Format::RockSim => Curve::RockSim(rse::parse(&text)?),
446        })
447    }
448}
449
450/// Reads a search's answer.
451///
452/// # Errors
453/// [`ThrustCurveError::Json`] when the body is not JSON of this shape; [`ThrustCurveError::Api`]
454/// when the answer or one of its criteria carries the API's `error`; [`ThrustCurveError::Count`]
455/// when it returns more motors than it says match; [`ThrustCurveError::Field`] for a motor id
456/// that isn't 24 hexadecimal digits, or a diameter, length, thrust, impulse, burn time or weight
457/// below zero.
458pub fn parse_search(body: &[u8]) -> Result<SearchAnswer, ThrustCurveError> {
459    #[derive(Deserialize)]
460    struct Errors {
461        error: Option<String>,
462        #[serde(default)]
463        criteria: Vec<CriterionError>,
464    }
465    #[derive(Deserialize)]
466    struct CriterionError {
467        name: String,
468        error: Option<String>,
469    }
470    let errors: Errors = json(body)?;
471    if let Some(error) = errors.error {
472        return Err(ThrustCurveError::Api(error));
473    }
474    if let Some(c) = errors.criteria.into_iter().find(|c| c.error.is_some()) {
475        let error = c.error.unwrap_or_default();
476        return Err(ThrustCurveError::Api(format!("{}: {error}", c.name)));
477    }
478    let answer: SearchAnswer = json(body)?;
479    let found = answer.results.len();
480    if usize::try_from(answer.matches).map_or(true, |m| found > m) {
481        return Err(ThrustCurveError::Count {
482            matches: answer.matches,
483            found,
484        });
485    }
486    for (i, motor) in answer.results.iter().enumerate() {
487        check_record(motor, &format!("results[{i}]"))?;
488    }
489    Ok(answer)
490}
491
492/// Reads a download's answer.
493///
494/// # Errors
495/// [`ThrustCurveError::Json`] when the body is not JSON of this shape; [`ThrustCurveError::Api`]
496/// when it carries the API's `error`; [`ThrustCurveError::Field`] for a motor id that isn't 24
497/// hexadecimal digits, or a file's data that isn't base64. A file that decodes but isn't UTF-8
498/// text is kept: [`DataFile::text`] reports it, for that file alone.
499pub fn parse_download(body: &[u8]) -> Result<DownloadAnswer, ThrustCurveError> {
500    #[derive(Deserialize)]
501    struct Errors {
502        error: Option<String>,
503    }
504    if let Some(error) = json::<Errors>(body)?.error {
505        return Err(ThrustCurveError::Api(error));
506    }
507    let answer: DownloadAnswer = json(body)?;
508    for (i, file) in answer.results.iter().enumerate() {
509        if !is_motor_id(&file.motor_id) {
510            return Err(field(format!("results[{i}].motorId"), &file.motor_id));
511        }
512        base64::engine::general_purpose::STANDARD
513            .decode(&file.data)
514            .map_err(|e| field(format!("results[{i}].data"), e))?;
515    }
516    Ok(answer)
517}
518
519/// Runs a search through `client`.
520///
521/// The answer comes from the client's cache while fresh (see [`source`]); offline, from the cache
522/// only. The [`Fetched`] says which, carries [`ATTRIBUTION`] and holds the body. Only an answer
523/// that [`parse_search`] reads is cached ([`Client::fetch_checked`]): one that doesn't never takes
524/// a good copy's place, and online a stale good copy is returned instead, with the reason.
525///
526/// # Errors
527/// [`ThrustCurveError::Net`] when the fetch fails, or with [`NetError::Refused`] naming what the
528/// parser refused when the only answer there is doesn't parse.
529pub fn fetch_search<T: Transport>(
530    client: &Client<T>,
531    search: &Search,
532    now_s: u64,
533) -> Result<(SearchAnswer, Fetched), ThrustCurveError> {
534    fetch(client, &search.url(), now_s, parse_search)
535}
536
537/// Fetches a search through `client`, as [`fetch_search`] does, refusing an answer cut short by
538/// its `maxResults` ([`SearchAnswer::is_complete`]): it is never cached, so it can't take a whole
539/// answer's place, and online a stale whole copy is returned instead, with the reason.
540///
541/// # Errors
542/// As [`fetch_search`]; with [`NetError::Refused`] naming [`ThrustCurveError::Incomplete`] for a
543/// search cut short and no whole copy cached.
544pub fn fetch_whole_search<T: Transport>(
545    client: &Client<T>,
546    search: &Search,
547    now_s: u64,
548) -> Result<(SearchAnswer, Fetched), ThrustCurveError> {
549    let read = |body: &[u8]| {
550        let answer = parse_search(body)?;
551        if !answer.is_complete() {
552            return Err(ThrustCurveError::Incomplete {
553                matches: answer.matches,
554                found: answer.results.len(),
555            });
556        }
557        Ok(answer)
558    };
559    fetch(client, &search.url(), now_s, read)
560}
561
562/// Fetches a motor's data files through `client`, as [`fetch_search`] does. An answer holding
563/// another motor's file, or a file in another format, is refused and never cached.
564///
565/// # Errors
566/// As [`fetch_search`]; with [`NetError::Refused`] naming [`ThrustCurveError::OtherMotor`] for a
567/// file of another motor or format than asked.
568pub fn fetch_download<T: Transport>(
569    client: &Client<T>,
570    download: &Download,
571    now_s: u64,
572) -> Result<(DownloadAnswer, Fetched), ThrustCurveError> {
573    let read = |body: &[u8]| {
574        let answer = parse_download(body)?;
575        let other = answer.results.iter().find(|f| {
576            !f.motor_id.eq_ignore_ascii_case(&download.motor_id) || f.format != download.format
577        });
578        if let Some(file) = other {
579            return Err(ThrustCurveError::OtherMotor {
580                asked: format!("{} ({})", download.motor_id, download.format.as_str()),
581                found: format!("{} ({})", file.motor_id, file.format.as_str()),
582            });
583        }
584        Ok(answer)
585    };
586    fetch(client, &download.url(), now_s, read)
587}
588
589/// Fetches every record of the makers the motor finder reads ([`MANUFACTURERS`]), one complete
590/// search each, as [`fetch_search`] does: the records [`join`] needs. A search that matches more
591/// motors than it returns, or holds another maker's record, is refused and never cached, so a
592/// join never runs on part of a maker's records.
593///
594/// # Errors
595/// As [`fetch_search`]; with [`NetError::Refused`] naming [`ThrustCurveError::Incomplete`] for a
596/// search cut short, or [`ThrustCurveError::OtherManufacturer`] for another maker's record.
597pub fn fetch_finder_records<T: Transport>(
598    client: &Client<T>,
599    now_s: u64,
600) -> Result<(Vec<MotorRecord>, Vec<Fetched>), ThrustCurveError> {
601    let mut records = Vec::new();
602    let mut fetched = Vec::new();
603    for &(name, _) in MANUFACTURERS {
604        let read = |body: &[u8]| {
605            let answer = parse_search(body)?;
606            if !answer.is_complete() {
607                return Err(ThrustCurveError::Incomplete {
608                    matches: answer.matches,
609                    found: answer.results.len(),
610                });
611            }
612            if let Some(other) = answer.results.iter().find(|r| r.manufacturer != name) {
613                return Err(ThrustCurveError::OtherManufacturer {
614                    asked: name.to_owned(),
615                    found: other.manufacturer.clone(),
616                });
617            }
618            Ok(answer)
619        };
620        let (answer, f) = fetch(client, &Search::manufacturer(name).url(), now_s, read)?;
621        records.extend(answer.results);
622        fetched.push(f);
623    }
624    Ok((records, fetched))
625}
626
627/// The motor finder's motors matched to ThrustCurve records, with the misses.
628#[non_exhaustive]
629#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
630pub struct Join {
631    /// The motors that mapped, in the finder's order.
632    pub mapped: Vec<Mapped>,
633    /// The motors that didn't, in the finder's order.
634    pub misses: Vec<Miss>,
635}
636
637/// A finder motor and the one ThrustCurve record with its name.
638#[non_exhaustive]
639#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
640pub struct Mapped {
641    /// The manufacturer's full name.
642    pub manufacturer: String,
643    /// The designation.
644    pub designation: String,
645    /// Where the motor is in the list given to [`join`].
646    pub finder_index: usize,
647    /// The record: its `motor_id` is what a [`Download`] names.
648    pub record: MotorRecord,
649}
650
651/// A finder motor that didn't map, and why.
652#[non_exhaustive]
653#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
654pub struct Miss {
655    /// The manufacturer's full name.
656    pub manufacturer: String,
657    /// The designation.
658    pub designation: String,
659    /// Why it didn't map.
660    pub reason: MissReason,
661}
662
663/// Why a finder motor didn't map.
664#[non_exhaustive]
665#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
666pub enum MissReason {
667    /// No record has its manufacturer and designation.
668    NoRecord,
669    /// Several do; their ids.
670    SeveralRecords(Vec<String>),
671}
672
673impl Join {
674    /// How many motors mapped, and how many were joined.
675    #[must_use]
676    pub fn coverage(&self) -> (usize, usize) {
677        (self.mapped.len(), self.mapped.len() + self.misses.len())
678    }
679
680    /// The join as Markdown: counts by manufacturer, among them the mapped motors whose record
681    /// lists no data file (`dataFiles` 0, or left out, as the API leaves out a field with no
682    /// value), and every miss with its reason.
683    #[must_use]
684    pub fn report(&self) -> String {
685        let mut by_maker: BTreeMap<&str, (usize, usize, usize)> = BTreeMap::new();
686        for m in &self.mapped {
687            let row = by_maker.entry(&m.manufacturer).or_default();
688            row.0 += 1;
689            row.1 += 1;
690            if m.record.data_files.unwrap_or(0) == 0 {
691                row.2 += 1;
692            }
693        }
694        for m in &self.misses {
695            by_maker.entry(&m.manufacturer).or_default().1 += 1;
696        }
697        let (mapped, total) = self.coverage();
698        let mut out = String::new();
699        // Writing to a String can't fail.
700        let _ = writeln!(
701            out,
702            "{mapped} of {total} motors mapped to one record each.\n"
703        );
704        let _ = writeln!(
705            out,
706            "| Manufacturer | Motors | Mapped | Mapped, no data file listed | Missed |"
707        );
708        let _ = writeln!(out, "|---|---:|---:|---:|---:|");
709        for (maker, (mapped, total, no_file)) in &by_maker {
710            let missed = total - mapped;
711            let _ = writeln!(
712                out,
713                "| {maker} | {total} | {mapped} | {no_file} | {missed} |"
714            );
715        }
716        let _ = writeln!(out);
717        if self.misses.is_empty() {
718            let _ = writeln!(out, "No misses.");
719        } else {
720            let _ = writeln!(out, "| Manufacturer | Designation | Why |");
721            let _ = writeln!(out, "|---|---|---|");
722            for m in &self.misses {
723                let why = match &m.reason {
724                    MissReason::NoRecord => "no record of that name".to_owned(),
725                    MissReason::SeveralRecords(ids) => {
726                        format!("{} records of that name: {}", ids.len(), ids.join(", "))
727                    }
728                };
729                let _ = writeln!(out, "| {} | `{}` | {why} |", m.manufacturer, m.designation);
730            }
731        }
732        out
733    }
734}
735
736/// Maps each finder motor to the one ThrustCurve record whose manufacturer (its full name) and
737/// designation equal the motor's, character for character. A motor with no such record, or
738/// several, is a [`Miss`]. A record given twice (the same `motor_id`, as when two searches
739/// overlap) counts once: the first copy is kept.
740#[must_use]
741pub fn join(motors: &[motor_finder::Motor], records: &[MotorRecord]) -> Join {
742    let mut by_name: BTreeMap<(&str, &str), Vec<&MotorRecord>> = BTreeMap::new();
743    for r in records {
744        let same_name = by_name
745            .entry((&r.manufacturer, &r.designation))
746            .or_default();
747        if same_name
748            .iter()
749            .all(|kept| !kept.motor_id.eq_ignore_ascii_case(&r.motor_id))
750        {
751            same_name.push(r);
752        }
753    }
754    let mut join = Join {
755        mapped: Vec::new(),
756        misses: Vec::new(),
757    };
758    for (finder_index, m) in motors.iter().enumerate() {
759        let found = by_name
760            .get(&(m.manufacturer.as_str(), m.designation.as_str()))
761            .map_or(&[][..], Vec::as_slice);
762        let miss = |reason| Miss {
763            manufacturer: m.manufacturer.clone(),
764            designation: m.designation.clone(),
765            reason,
766        };
767        match found {
768            [record] => join.mapped.push(Mapped {
769                manufacturer: m.manufacturer.clone(),
770                designation: m.designation.clone(),
771                finder_index,
772                record: (*record).clone(),
773            }),
774            [] => join.misses.push(miss(MissReason::NoRecord)),
775            several => join.misses.push(miss(MissReason::SeveralRecords(
776                several.iter().map(|r| r.motor_id.clone()).collect(),
777            ))),
778        }
779    }
780    join
781}
782
783/// Fetches `url` through `client`, caching only an answer `read` reads.
784fn fetch<T: Transport, R>(
785    client: &Client<T>,
786    url: &str,
787    now_s: u64,
788    read: impl Fn(&[u8]) -> Result<R, ThrustCurveError>,
789) -> Result<(R, Fetched), ThrustCurveError> {
790    let check = |body: &[u8]| read(body).map(drop).map_err(|e| e.to_string());
791    let fetched = client.fetch_checked(&source(), url, now_s, check)?;
792    let value = read(&fetched.body)?;
793    Ok((value, fetched))
794}
795
796/// Whether `id` has the form of a ThrustCurve id: 24 hexadecimal digits.
797fn is_motor_id(id: &str) -> bool {
798    id.len() == 24 && id.bytes().all(|b| b.is_ascii_hexdigit())
799}
800
801/// Percent-encodes a query value: every byte but an ASCII letter, digit, `-`, `.`, `_` or `~`
802/// (RFC 3986's unreserved characters) is written `%XX`.
803fn encode(value: &str) -> String {
804    let mut out = String::with_capacity(value.len());
805    for b in value.bytes() {
806        if b.is_ascii_alphanumeric() || b"-._~".contains(&b) {
807            out.push(char::from(b));
808        } else {
809            let _ = write!(out, "%{b:02X}");
810        }
811    }
812    out
813}
814
815/// Checks a record: a motor id of the API's form, and no figure below zero.
816fn check_record(motor: &MotorRecord, at: &str) -> Result<(), ThrustCurveError> {
817    if !is_motor_id(&motor.motor_id) {
818        return Err(field(format!("{at}.motorId"), &motor.motor_id));
819    }
820    let figures = [
821        ("diameter", motor.diameter_mm),
822        ("length", motor.length_mm),
823        ("avgThrustN", motor.avg_thrust_n),
824        ("maxThrustN", motor.max_thrust_n),
825        ("totImpulseNs", motor.total_impulse_ns),
826        ("burnTimeS", motor.burn_time_s),
827        ("totalWeightG", motor.total_weight_g),
828        ("propWeightG", motor.propellant_weight_g),
829    ];
830    for (name, value) in figures {
831        if let Some(value) = value.filter(|v| *v < 0.0) {
832            return Err(field(format!("{at}.{name}"), value));
833        }
834    }
835    Ok(())
836}
837
838/// Deserializes `body`.
839fn json<'a, D: Deserialize<'a>>(body: &'a [u8]) -> Result<D, ThrustCurveError> {
840    serde_json::from_slice(body).map_err(|e| ThrustCurveError::Json(e.to_string()))
841}
842
843/// A [`ThrustCurveError::Field`].
844fn field(field: String, value: impl ToString) -> ThrustCurveError {
845    ThrustCurveError::Field {
846        field,
847        value: value.to_string(),
848    }
849}
850
851/// Why a ThrustCurve request or answer was refused.
852#[non_exhaustive]
853#[derive(Debug, thiserror::Error)]
854pub enum ThrustCurveError {
855    /// A request field is not one the API serves.
856    #[error("the ThrustCurve request's {what} is not one it serves: {value:?}")]
857    Request {
858        /// The field.
859        what: &'static str,
860        /// Its value.
861        value: String,
862    },
863    /// The fetch failed.
864    #[error(transparent)]
865    Net(#[from] NetError),
866    /// The body is not JSON of the expected shape: a field missing, or of the wrong type.
867    #[error("the ThrustCurve answer is not of the expected shape: {0}")]
868    Json(String),
869    /// The answer carries the API's `error`, or one of its criteria does.
870    #[error("ThrustCurve refused the request: {0}")]
871    Api(String),
872    /// A search returns more motors than it says match.
873    #[error("the ThrustCurve search says {matches} motors match but returns {found}")]
874    Count {
875        /// The `matches` stated.
876        matches: u32,
877        /// The motors returned.
878        found: usize,
879    },
880    /// A search returns fewer motors than match: its `maxResults` cut it short.
881    #[error("the ThrustCurve search matches {matches} motors but returns only {found}")]
882    Incomplete {
883        /// The `matches` stated.
884        matches: u32,
885        /// The motors returned.
886        found: usize,
887    },
888    /// A field breaks the API's rules.
889    #[error("the ThrustCurve answer's {field} is not usable: {value}")]
890    Field {
891        /// Where it is (`results[12].motorId`).
892        field: String,
893        /// Its value.
894        value: String,
895    },
896    /// A maker's search holds another maker's record.
897    #[error("asked ThrustCurve for {asked}'s motors, but the answer holds one of {found}'s")]
898    OtherManufacturer {
899        /// The maker asked for.
900        asked: String,
901        /// The maker found.
902        found: String,
903    },
904    /// A download holds a file of another motor or format than asked.
905    #[error("asked ThrustCurve for {asked}'s files, but the answer holds {found}'s")]
906    OtherMotor {
907        /// The motor id and format asked for.
908        asked: String,
909        /// The motor id and format found.
910        found: String,
911    },
912    /// `hpr_motor`'s reader refused a data file.
913    #[error(transparent)]
914    Motor(#[from] MotorError),
915}
916
917#[cfg(test)]
918mod tests {
919    use super::*;
920
921    #[test]
922    fn urls_follow_the_apis_names() {
923        assert_eq!(
924            Search::manufacturer("Cesaroni Technology").url(),
925            "https://www.thrustcurve.org/api/v1/search.json?manufacturer=Cesaroni%20Technology&maxResults=5000"
926        );
927        let search = Search {
928            designation: Some("F27R/L".to_owned()),
929            impulse_class: Some("F".to_owned()),
930            ..Search::default()
931        };
932        assert_eq!(
933            search.url(),
934            "https://www.thrustcurve.org/api/v1/search.json?designation=F27R%2FL&impulseClass=F"
935        );
936        assert_eq!(
937            Search::default().url(),
938            "https://www.thrustcurve.org/api/v1/search.json"
939        );
940        let download = Download::new("5f4294d2000231000000044f", Format::Rasp).unwrap();
941        assert_eq!(
942            download.url(),
943            "https://www.thrustcurve.org/api/v1/download.json?motorId=5f4294d2000231000000044f&format=RASP&data=file"
944        );
945    }
946
947    #[test]
948    fn a_motor_id_must_be_24_hex_digits() {
949        for bad in [
950            "",
951            "5f4294d2000231000000044",
952            "5f4294d2000231000000044f0",
953            "5f4294d2000231000000044g",
954            "5f4294d200023100000004&f",
955        ] {
956            let err = Download::new(bad, Format::Rasp).unwrap_err();
957            assert!(
958                matches!(&err, ThrustCurveError::Request { what: "motor id", value } if value == bad),
959                "{bad}: {err}"
960            );
961        }
962        let upper = Download::new("5F4294D2000231000000044F", Format::RockSim).unwrap();
963        assert_eq!(upper.motor_id(), "5f4294d2000231000000044f");
964        assert!(upper.url().contains("motorId=5f4294d2000231000000044f&"));
965    }
966
967    #[test]
968    fn query_values_are_percent_encoded() {
969        assert_eq!(encode("AZaz09-._~"), "AZaz09-._~");
970        assert_eq!(encode("a b/c&d=e?é"), "a%20b%2Fc%26d%3De%3F%C3%A9");
971    }
972}