Crate pleiades_backend

Expand description

Backend contracts, metadata, and adapter helpers for ephemeris providers.

This crate defines the shared request/response shape used by all backend families. Concrete backends live in their own pleiades-* crates and implement EphemerisBackend.

Enable the optional serde feature to serialize the shared request, result, metadata, and error types used by backend implementations.

The current time-scale, observer, apparentness, and frame policy is documented in docs/time-observer-policy.md so the direct backend contract and the façade-level request helpers stay in sync. Direct batch callers should pair that policy with validate_requests_against_metadata() so the same explicit contract is checked before a slice of requests is dispatched.

§Examples

use pleiades_backend::{EphemerisBackend, EphemerisRequest, BackendMetadata, BackendId, BackendFamily,
    BackendProvenance, BackendCapabilities, AccuracyClass, TimeRange, EphemerisResult, EphemerisError,
    EphemerisErrorKind, Apparentness, QualityAnnotation, BodyClaim};
use pleiades_types::{CelestialBody, CoordinateFrame, Instant, JulianDay, Latitude,
    Longitude, TimeScale, ZodiacMode};

struct ToyBackend;

impl EphemerisBackend for ToyBackend {
    fn metadata(&self) -> BackendMetadata {
        BackendMetadata {
            id: BackendId::new("toy"),
            version: "0.1.0".to_string(),
            family: BackendFamily::Algorithmic,
            provenance: BackendProvenance { summary: "example backend".to_string(), data_sources: vec![] },
            nominal_range: TimeRange::new(None, None),
            supported_time_scales: vec![TimeScale::Tt],
            body_claims: vec![BodyClaim::from(CelestialBody::Sun)],
            supported_frames: vec![CoordinateFrame::Ecliptic],
            capabilities: BackendCapabilities::default(),
            accuracy: AccuracyClass::Approximate,
            deterministic: true,
            offline: true,
        }
    }

    fn supports_body(&self, body: CelestialBody) -> bool {
        body == CelestialBody::Sun
    }

    fn position(&self, request: &EphemerisRequest) -> Result<EphemerisResult, EphemerisError> {
        if request.body != CelestialBody::Sun {
            return Err(EphemerisError::new(EphemerisErrorKind::UnsupportedBody, "only the Sun is supported"));
        }

        Ok(EphemerisResult::new(
            BackendId::new("toy"),
            request.body.clone(),
            request.instant,
            request.frame,
            request.zodiac_mode.clone(),
            request.apparent,
        ))
    }
}

Modules§

test_backend: Deterministic analytic Sun/Moon backend for downstream tests. NOT for production: circular-orbit longitudes, fixed distances.

Structs§

Angle: An angular quantity measured in degrees.
BackendCapabilities: Capability flags for a backend.
BackendId: Stable identifier for a backend implementation.
BackendMetadata: Nominal backend metadata.
BackendProvenance: Provenance summary for a backend.
BodyClaim: A single backend’s claim about a single body.
CompositeBackend: A simple composite backend that routes requests to one of two providers.
CustomAyanamsa: A structured custom ayanamsa definition.
CustomBodyId: A structured identifier for a custom body.
CustomHouseSystem: A structured custom house-system definition.
EclipticCoordinates: Ecliptic position data.
EphemerisError: A structured backend error.
EphemerisRequest: A backend request.
EphemerisResult: A backend result containing the requested coordinates where available.
EquatorialCoordinates: Equatorial position data.
FrameTreatmentSummary: Compact summary of a backend’s frame-treatment posture.
Instant: A Julian day tagged with a time scale.
JulianDay: A Julian day expressed as a floating-point day count.
Latitude: A signed latitude-like angle measured in degrees, north-positive.
Longitude: A canonical ecliptic or longitude-like angle normalized into [0, 360).
Motion: Apparent motion data for a position sample.
ObserverLocation: A geographic observer location.
ReleasePosture: A derived, cross-backend view of body claims for release reporting.
RoutingBackend: A routing backend that can chain any number of providers.
TimeRange: A Julian-day interval.
TimeScaleConversion: A caller-supplied time-scale conversion policy.

Enums§

AccuracyClass: A rough accuracy class for a backend.
Apparentness: Whether a backend should prefer apparent or mean values where both exist.
Ayanamsa: A built-in or custom ayanamsa selection.
BackendCapabilitiesValidationError: Errors returned when the declared backend capabilities cannot describe a usable request shape.
BackendFamily: The high-level backend family.
BackendFamilyPosture: A coarse posture label for how a backend family is typically categorized in release summaries.
BackendMetadataValidationError: Errors returned when backend metadata fails the shared consistency checks.
BackendProvenanceValidationError: Errors returned when backend provenance metadata fails the shared consistency checks.
BodyClaimTier: The release-claim status of a single body for a single backend.
CelestialBody: The built-in and custom body identifiers recognized by the shared API.
CelestialBodyClass: A coarse classification for a celestial body.
ClaimEvidence: The evidence backing a body claim.
CoordinateFrame: The coordinate frame requested from a backend.
CoordinateValidationError: Validation errors for shared coordinate samples.
CustomDefinitionValidationError: Validation failure for a custom body, house system, or ayanamsa definition.
EphemerisErrorKind: Error categories for backend queries.
EphemerisResultValidationError: Errors returned when a backend result record no longer matches its stored data.
FrameTreatmentSummaryValidationError: Validation error for a frame-treatment summary that drifted away from a compact release-facing line.
HouseSystem: A built-in or custom house system selection.
MotionValidationError: Errors returned when motion samples contain non-finite values.
QualityAnnotation: Quality annotation for a backend result.
TimeRangeValidationError: Shared validation errors for TimeRange.
TimeScale: A supported astronomical time scale.
TimeScaleConversionError: Error returned when a caller-provided time-scale conversion fails.
ZodiacMode: Whether coordinates should be interpreted in tropical or sidereal mode.

Traits§

EphemerisBackend: The shared backend contract.

Functions§

merge_body_claims: Merges two claim lists, keeping the stronger-ranked tier on body collisions.
validate_observer_policy: Validates the observer policy shared by the current first-party backends.
validate_request_against_metadata: Validates a direct backend request against the published backend metadata.
validate_request_policy: Validates the request-shape policy shared by the current first-party backends.
validate_requests_against_metadata: Validates a batch of direct backend requests against backend metadata.
validate_zodiac_policy: Validates the zodiac-mode policy shared by the current first-party backends.