Skip to content
SiderustPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

siderust-archive

Crates.io docs.rs CI Update Time Data License: BSD-3-Clause

Scientific dataset manifests, provenance, checksums, and Rust accessors for the Siderust ecosystem.

siderust-archive is the small Rust crate and repository layout used to keep Siderust scientific data out of downstream application code. It stores dataset metadata in TOML, keeps raw payloads in their native formats, and exposes only the Rust bindings needed to parse, verify, fetch, or bundle those datasets.

Pre-1.0 archive: manifest shape and feature-gated APIs may still change. Release v0.2.0 includes compact embedded planetary and lunar ephemerides. See the crate on crates.io, the API documentation, and the changelog.

Scope

  • TOML archive and family manifests.
  • SHA-256 checksum helpers and provenance records.
  • IERS/USNO time-data parsing, runtime fetch, and bundled offline snapshots.
  • Build-time generated accessors for committed coefficient tables.
  • Dataset-family manifests for VSOP87, ELP2000, nutation, JPL kernels, Lagrange kernels, gravity, atmosphere, frames, constants, and Pluto.

Non-goals

  • Hiding upstream data provenance.
  • Fetching large or mutable datasets from downstream build scripts.
  • Silently replacing version-pinned datasets.
  • Re-implementing Siderust scientific algorithms in the archive crate.

Installation

[dependencies]
siderust-archive = "0.2.0"

For no_std + alloc (manifest, checksum, provenance, and scientific tables):

[dependencies]
siderust-archive = { version = "0.2.0", default-features = false }

IERS time-data parsers and the bundled offline snapshot:

[dependencies]
siderust-archive = { version = "0.2.0", features = ["time"] }

Runtime download/cache support for current IERS/USNO time data and JPL kernel metadata (fetch requires std):

[dependencies]
siderust-archive = { version = "0.2.0", features = ["fetch"] }

Planetary and geophysical tables are opt-in and work with or without std:

[dependencies]
siderust-archive = { version = "0.2.0", default-features = false, features = ["vsop", "elp", "nutation"] }

The crate declares its own [workspace], so it is not absorbed into a parent workspace when used through a local path dependency.

Feature Flags

Feature Description
default Enables std.
std Standard library support (filesystem, network, env, OS I/O errors). Absent ⇒ no_std + alloc.
time IERS UTC-TAI, Delta T, and EOP types/parsers; includes bundled-time.
bundled-time Compiled UTC-TAI and Delta T fallback snapshot.
fetch Runtime network download/cache support; requires std; implies time and jpl.
jpl JPL DE440/DE441 ephemeris metadata; download/cache needs fetch.
vsop Full VSOP87A/E planetary theory tables.
vsop-compact Compact VSOP87E positions for the Sun and eight planets, 2020–2050.
elp Full ELP2000-82B lunar theory tables.
elp-compact Compact Earth-centered lunar position, 2020–2050.
nutation IAU 2000A/2000B nutation coefficient tables.
gravity Low-degree EGM2008 geopotential coefficients.
atmosphere NRLMSISE-00 lite atmosphere-density table.
frames SPICE-style frame definitions placeholder.
constants SPICE-style body constants placeholder.
lagrange Sun-Earth Lagrange Chebyshev kernel references.
pluto Meeus 1998 abbreviated Pluto series.

Compact embedded planetary positions

siderust-archive = { version = "0.2.0", default-features = false, features = ["vsop-compact"] }

siderust_archive::vsop_compact provides a checked function per body, such as try_mars(jd_tdb). It returns CompactEphemerisError for non-finite dates or dates outside [FIRST_JD_TDB, END_JD_TDB) (2020-01-01 through 2050-12-31 TDB). The direct functions, such as mars(jd_tdb), evaluate unchecked.

On success, the position is a geometric barycentric [X, Y, Z] in AU in the native VSOP87 dynamical ecliptic and equinox of J2000.0. Subtract the Earth vector at the same epoch for an Earth-relative vector. The compiled coefficients require no runtime I/O or allocation.

The validation report includes accuracy, linked size, performance, source checksums, and reproduction commands.

Compact embedded lunar position

siderust-archive = { version = "0.2.0", default-features = false, features = ["elp-compact"] }

elp_compact::try_moon_geocentric(jd_tdb) returns a geometric Cartesian Earth-to-Moon vector in kilometers in the native ELP2000-82B mean dynamical ecliptic and inertial equinox of J2000.0. The checked API accepts finite TDB Julian dates from 2020-01-01 through 2050-12-31. Subtract the observer's vector in the same frame to include geometric lunar parallax. Enable vsop-compact alongside it for planetary positions.

The lunar validation report documents distance and pointing errors, the native frame, and firmware measurements.

Archive Layout

archive/
├── CHANGELOG.md
├── Cargo.toml
├── LICENSE
├── MANIFEST.toml                # top-level dataset registry
├── README.md
├── schema/                      # manifest and binary-format specs
├── src/                         # crate sources and committed datasets
├── tools/validate/              # structural manifest validator
└── reports/validation/          # validation output, when present

Start with MANIFEST.toml. Each [[family]] entry points to a src/<family>/manifest.toml file that records source, generator, validity, units, references, payload files, byte counts, and SHA-256 checksums.

Manifest Conventions

  • Metadata is TOML. JSON is not used for archive manifests or provenance.
  • Payload files keep their authoritative upstream format where practical.
  • Generated Rust tables are build artifacts under Cargo OUT_DIR; do not commit them.
  • Dataset generators must record source, generator version, generated time, references, byte counts, and checksums.

Validate the registry and all referenced family manifests:

cargo run -p archive-validate -- MANIFEST.toml

Adding Data

  1. Put upstream payloads under src/<family>/raw/ or the family-specific payload directory.
  2. Update src/<family>/manifest.toml.
  3. Register new families in MANIFEST.toml.
  4. Run cargo run -p archive-validate -- MANIFEST.toml.
  5. Build with the relevant feature enabled, for example cargo check --features nutation.

Large mutable datasets need a reviewed process before they become automated.

Time-Data Maintenance

Update Time Data runs Mondays at 05:23 UTC and can also be dispatched from main. It refreshes UTC-TAI.history, deltat.data, deltat.preds, and finals2000A.all under src/time/eop/raw/. Other dataset families use their reviewed, version-pinned maintenance procedures.

The updater stages all four downloads, checks parsing and coverage against the committed data, and ignores whitespace-only changes that preserve field values and fixed-width columns. A changed snapshot carries the fetch time and SHA-256 hashes in time_data.provenance.toml. It also updates the checksum and byte-count entries in src/time/eop/manifest.toml and regenerates src/time/bundled/snapshot.rs. Identical payloads retain the committed provenance and generated files. The workflow validates the manifest and runs the all-features tests before it can commit a refresh.

Transient download failures get up to three attempts per source, each limited to 60 seconds, with 2- and 4-second backoff. Transport failures, invalid payloads, and regressed coverage fail the refresh and preserve the committed snapshot. The job summaries report the changed datasets, validation, and publication status. Runtime fetch remains available with the fetch feature.

Releases

Prepare and tag a release

  1. Review and merge a PR that sets the intended SemVer in Cargo.toml and the root package entry in Cargo.lock, and adds nonempty notes under ## [VERSION] in CHANGELOG.md. Wait for CI to pass on the reviewed release commit on main.

  2. Fetch main and confirm that the commit you intend to tag has the version and notes you reviewed. Set version to the version from that commit:

    git switch main
    git pull --ff-only origin main
    python3 scripts/archive-release.py check-metadata
    version=MAJOR.MINOR.PATCH
    git tag -a "v${version}" -m "Release v${version}"
    git push origin "refs/tags/v${version}"
  3. Open the Publish workflow. It validates the exact annotated tag on main history, tests the crate and datasets, and builds the package and its all-features docs. It creates the GitHub Release from the changelog after verifying the indexed crate's checksum, version, and embedded commit. Use the job summary to compare the tag, commit, crate version, and GitHub Release notes. Check the corresponding docs.rs build once it becomes available.

Automatic patch releases

Update Time Data runs Mondays at 05:23 UTC and can be dispatched on main. It checks out the latest main, downloads and checks all four IERS/USNO datasets in staging, and regenerates the bundled snapshot, manifest, and provenance together. Identical payloads retain the committed provenance. Whitespace-only changes also retain it, with fixed-width scientific columns preserved.

A changed payload requires a stable version with a verified crate and published GitHub Release at its annotated tag. Every intervening commit must touch only the tracked time-data paths, including changes later reverted. If maintenance finds unrelated work, include the data in a reviewed normal release. Failed downloads or scientific validation stop the run before Git pushes.

Maintenance increments PATCH, commits the datasets and release metadata together, and validates the committed package. It pushes the commit and new annotated tag atomically, with a lease on the original main commit. It passes the exact tag and commit to the shared workflow in the same run, so the automatic release works with GitHub's workflow token. An unchanged refresh finishes without a new commit, version, or tag.

Repository configuration

  • Configure CARGO_REGISTRY_TOKEN with permission to publish siderust-archive. Set it as a secret in the crates.io Actions environment or as a repository Actions secret.
  • Allow main and v* deployments in that environment. Required reviewers, if configured, also approve scheduled releases. Unattended weekly releases require an environment that permits those runs without manual approval.
  • Allow the workflow's built-in GITHUB_TOKEN to create GitHub Releases and make the scheduled atomic push to main and a new version tag. Restrict release tag creation to maintainers and authorized automation, and protect existing tags from changes and deletion. If branch rules require PRs for all pushes, use a reviewed data and version PR and tag the merged commit.
  • Both callers share a concurrency queue. The queue can hold up to 100 pending runs. Use an explicit recovery dispatch if a run is dropped, interrupted, or fails.

Recover and diagnose a release

If the version tag exists, rerun the failed workflow or dispatch Publish on main with the existing bare version:

gh workflow run publish.yml --repo Siderust/archive --ref main -f version=0.2.0

Recovery validates that exact tag even if main has advanced. Once crates.io indexes a matching crate, recovery skips the upload and creates or synchronizes the GitHub Release. A tag/Cargo mismatch, divergent tag, registry checksum or source mismatch, yanked crate, or draft release needs maintainer investigation. Preserve existing release tags and versions.

If maintenance fails before the atomic push, rerun Update Time Data to refresh against current main. If Cargo reports an upload error or times out waiting for indexing, check the registry and rerun Publish for the same tag. The workflow polls for the indexed crate before making GitHub Release changes. Inspect the preceding Cargo or dataset logs to diagnose errors and use the job summary links to check synchronization.

Investigating docs.rs builds

Open the failed build log on the crate's docs.rs Builds page and identify its nightly revision. CI runs bash scripts/check-packaged-docs.sh from a clean checkout with stable and nightly Rust installed. The script unpacks the Cargo package and runs offline rustdoc with DOCS_RS=1, --cfg docsrs, and all features enabled, so missing inputs to the scientific table generators fail before release. Use the matching nightly when investigating a toolchain-specific failure. The 0.1.5 log shows that Rust removed doc_auto_cfg and folded it into doc_cfg.

License

BSD-3-Clause — see LICENSE.

Each upstream dataset keeps the license and attribution declared by its original source. Check the relevant family manifest before redistributing data payloads outside this repository.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages