class

Kozai::Catalog::Store

Inherits Reference < Object

A collection of satellites, loaded from files and optionally refreshed from the network.

The offline contract

This is a daemon for a station that may have no internet at all, so the rules are:

  • A source that fails never removes what is already loaded.
  • A cached copy that is past its expiry is still used if the download fails. Stale elements degrade gracefully and their age is reported; no elements is a broken service.
  • Nothing is fetched unless the cache has actually expired.

NOTE: the default expiry is 24 hours and should not be shortened. Element sets are regenerated once or twice a day, so polling faster gains nothing, and CelesTrak explicitly asks clients to cache rather than poll. Being a good citizen of someone else's bandwidth is part of shipping this.

Constructors

from_config(config : Config) : Store

Builds a store from configuration.

Source
new(files : Array(String) = [] of String, urls : Array(String) = [] of String, cache_directory : String = "./cache", cache_ttl : Time::Span = 24.hours, offline : Bool = false)
Source

Instance methods

bundled?

Whether what is loaded came from Bundled rather than from a configured source. Reported through the API so that the interface can say so: elements nobody asked for should never be mistaken for elements somebody configured.

Source
cache_directory

Where downloads are cached.

Source
cache_path_for(url : String) : String

A stable, filesystem-safe cache name for a URL.

Source
cache_ttl

How long a cached download stays fresh.

Source
empty?

Whether anything is loaded.

Source
files

Local files to load.

Source
find(catalog_number : Int32) : SGP4::Satellite | Nil

The satellite with this catalog number, or nil.

Source
freshest_age(at : Time = Time.utc) : Time::Span | Nil

Age of the newest element set, or nil if nothing is loaded.

Source
loaded_at

When #refresh last completed.

Source
offline?

Whether to skip the network entirely.

Source
refresh(force : Bool = false) : Nil

Reloads every source.

force re-downloads remote sources even if their cache is still fresh; it is what the API's manual refresh endpoint uses.

Never raises for a source that fails: the failure is recorded in #sources and whatever else loaded is kept.

Source
replace(elements : Enumerable(TLE::Elements)) : Nil

Loads element sets directly, bypassing files and the network.

Used by the tests, and by anything embedding this library that already has elements in hand.

Source
satellites

The satellites currently loaded.

Source
search(fragment : String) : Array(SGP4::Satellite)

Satellites whose name contains fragment, case-insensitively.

Source
size

How many satellites are loaded.

Source
sources

Per-source outcome of the last refresh.

Source
stalest_age(at : Time = Time.utc) : Time::Span | Nil

Age of the oldest element set, or nil if nothing is loaded.

Source
urls

Remote sources to fetch.

Source