pleiades_backend/
lib.rs

1//! Backend contracts, metadata, and adapter helpers for ephemeris providers.
2//!
3//! This crate defines the shared request/response shape used by all backend
4//! families. Concrete backends live in their own `pleiades-*` crates and
5//! implement [`EphemerisBackend`].
6//!
7//! Enable the optional `serde` feature to serialize the shared request,
8//! result, metadata, and error types used by backend implementations.
9//!
10//! The current time-scale, observer, apparentness, and frame policy is
11//! documented in `docs/time-observer-policy.md` so the direct backend contract
12//! and the façade-level request helpers stay in sync. Direct batch callers
13//! should pair that policy with `validate_requests_against_metadata()` so the
14//! same explicit contract is checked before a slice of requests is dispatched.
15//!
16//! # Examples
17//!
18//! ```
19//! use pleiades_backend::{EphemerisBackend, EphemerisRequest, BackendMetadata, BackendId, BackendFamily,
20//!     BackendProvenance, BackendCapabilities, AccuracyClass, TimeRange, EphemerisResult, EphemerisError,
21//!     EphemerisErrorKind, Apparentness, QualityAnnotation, BodyClaim};
22//! use pleiades_types::{CelestialBody, CoordinateFrame, Instant, JulianDay, Latitude,
23//!     Longitude, TimeScale, ZodiacMode};
24//!
25//! struct ToyBackend;
26//!
27//! impl EphemerisBackend for ToyBackend {
28//!     fn metadata(&self) -> BackendMetadata {
29//!         BackendMetadata {
30//!             id: BackendId::new("toy"),
31//!             version: "0.1.0".to_string(),
32//!             family: BackendFamily::Algorithmic,
33//!             provenance: BackendProvenance { summary: "example backend".to_string(), data_sources: vec![] },
34//!             nominal_range: TimeRange::new(None, None),
35//!             supported_time_scales: vec![TimeScale::Tt],
36//!             body_claims: vec![BodyClaim::from(CelestialBody::Sun)],
37//!             supported_frames: vec![CoordinateFrame::Ecliptic],
38//!             capabilities: BackendCapabilities::default(),
39//!             accuracy: AccuracyClass::Approximate,
40//!             deterministic: true,
41//!             offline: true,
42//!         }
43//!     }
44//!
45//!     fn supports_body(&self, body: CelestialBody) -> bool {
46//!         body == CelestialBody::Sun
47//!     }
48//!
49//!     fn position(&self, request: &EphemerisRequest) -> Result<EphemerisResult, EphemerisError> {
50//!         if request.body != CelestialBody::Sun {
51//!             return Err(EphemerisError::new(EphemerisErrorKind::UnsupportedBody, "only the Sun is supported"));
52//!         }
53//!
54//!         Ok(EphemerisResult::new(
55//!             BackendId::new("toy"),
56//!             request.body.clone(),
57//!             request.instant,
58//!             request.frame,
59//!             request.zodiac_mode.clone(),
60//!             request.apparent,
61//!         ))
62//!     }
63//! }
64//! ```
65
66#![forbid(unsafe_code)]
67#![deny(missing_docs)]
68
69mod capabilities;
70mod claims;
71mod errors;
72mod identity;
73mod metadata;
74mod policy;
75mod release_posture;
76mod request;
77mod result;
78mod traits;
79mod validation;
80
81#[cfg(test)]
82pub(crate) mod test_support;
83
84#[cfg(any(test, feature = "test-backend"))]
85pub mod test_backend;
86
87pub use pleiades_types::{
88    Angle, Apparentness, Ayanamsa, CelestialBody, CelestialBodyClass, CoordinateFrame,
89    CoordinateValidationError, CustomAyanamsa, CustomBodyId, CustomDefinitionValidationError,
90    CustomHouseSystem, EclipticCoordinates, EquatorialCoordinates, HouseSystem, Instant, JulianDay,
91    Latitude, Longitude, Motion, MotionValidationError, ObserverLocation, TimeRange,
92    TimeRangeValidationError, TimeScale, TimeScaleConversion, TimeScaleConversionError, ZodiacMode,
93};
94
95pub use capabilities::{BackendCapabilities, BackendCapabilitiesValidationError};
96pub use claims::{BodyClaim, BodyClaimTier, ClaimEvidence};
97pub use errors::{EphemerisError, EphemerisErrorKind};
98pub use identity::{AccuracyClass, BackendFamily, BackendFamilyPosture, BackendId};
99pub use metadata::{
100    merge_body_claims, BackendMetadata, BackendMetadataValidationError, BackendProvenance,
101    BackendProvenanceValidationError,
102};
103pub use policy::current::{
104    validate_observer_policy, validate_request_against_metadata, validate_request_policy,
105    validate_requests_against_metadata, validate_zodiac_policy,
106};
107pub use policy::{FrameTreatmentSummary, FrameTreatmentSummaryValidationError};
108pub use release_posture::ReleasePosture;
109pub use request::EphemerisRequest;
110pub use result::{EphemerisResult, EphemerisResultValidationError, QualityAnnotation};
111pub use traits::{CompositeBackend, EphemerisBackend, RoutingBackend};
pleiades_backend/lib.rs

pleiades_backend/
lib.rs
