219 lines
12 KiB
Rust
219 lines
12 KiB
Rust
// file: crates/ksp-offchain-transport-lib/src/lib.rs
|
|
// version: 12
|
|
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
//! KSP-owned off-chain transport foundation.
|
|
//!
|
|
//! `0.2.11` delivers the complete SOL/USD V1 surface over eight providers. The crate owns exact decimal normalization, provider adapters, hardened
|
|
//! HTTP, non-blocking rate-limit/cooldown handling, provider-neutral registry/availability and individual/multiple/all refresh operations. Provider-specific
|
|
//! setup remains confined to composition while runtime consumers can operate on opaque provider identifiers, registry projections and normalized outcomes.
|
|
//! Config integration is implemented externally by `ksp-config-lib`; this crate remains independent from Config and never reads KSP environment variables
|
|
//! directly.
|
|
|
|
mod constants;
|
|
mod error;
|
|
mod http_admission;
|
|
mod http_client;
|
|
mod http_settings;
|
|
mod market_price_adapter;
|
|
mod market_price_api_key;
|
|
mod market_price_birdeye;
|
|
mod market_price_coinbase_exchange;
|
|
mod market_price_coingecko;
|
|
mod market_price_coinmarketcap;
|
|
mod market_price_coinpaprika;
|
|
mod market_price_decimal;
|
|
mod market_price_dexscreener;
|
|
mod market_price_jupiter;
|
|
mod market_price_kraken;
|
|
mod market_price_observation;
|
|
mod market_price_provider;
|
|
mod market_price_registry;
|
|
mod market_price_service;
|
|
mod market_price_settings;
|
|
|
|
/// Stable error code for HTTP access denial.
|
|
pub use self::error::ERROR_CODE_HTTP_ACCESS_DENIED;
|
|
/// Stable error code for local HTTP request deferral.
|
|
pub use self::error::ERROR_CODE_HTTP_ADMISSION_DEFERRED;
|
|
/// Stable error code for hardened HTTP client initialization failure.
|
|
pub use self::error::ERROR_CODE_HTTP_CLIENT_BUILD_FAILED;
|
|
/// Stable error code for an off-chain HTTP connection failure.
|
|
pub use self::error::ERROR_CODE_HTTP_CONNECTION_FAILED;
|
|
/// Stable error code for a syntactically invalid JSON response.
|
|
pub use self::error::ERROR_CODE_HTTP_INVALID_JSON;
|
|
/// Stable error code for an invalid local HTTP rate-limit policy.
|
|
pub use self::error::ERROR_CODE_HTTP_RATE_LIMIT_INVALID;
|
|
/// Stable error code for HTTP 429 rate limiting.
|
|
pub use self::error::ERROR_CODE_HTTP_RATE_LIMITED;
|
|
/// Stable error code for a generic unsuccessful HTTP request.
|
|
pub use self::error::ERROR_CODE_HTTP_REQUEST_FAILED;
|
|
/// Stable error code for an invalid crate-owned HTTP request definition.
|
|
pub use self::error::ERROR_CODE_HTTP_REQUEST_INVALID;
|
|
/// Stable error code for an oversized HTTP response body.
|
|
pub use self::error::ERROR_CODE_HTTP_RESPONSE_TOO_LARGE;
|
|
/// Stable error code for invalid crate-wide HTTP runtime settings.
|
|
pub use self::error::ERROR_CODE_HTTP_SETTINGS_INVALID;
|
|
/// Stable error code for temporary HTTP provider failures.
|
|
pub use self::error::ERROR_CODE_HTTP_TEMPORARY_FAILURE;
|
|
/// Stable error code for end-to-end HTTP timeout.
|
|
pub use self::error::ERROR_CODE_HTTP_TIMEOUT;
|
|
/// Stable error code for an invalid exact decimal price.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_DECIMAL_INVALID;
|
|
/// Stable error code for an invalid provider-neutral observation.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_OBSERVATION_INVALID;
|
|
/// Stable error code for an invalid provider descriptor.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_PROVIDER_DESCRIPTOR_INVALID;
|
|
/// Stable error code returned when a disabled provider is invoked directly.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_PROVIDER_DISABLED;
|
|
/// Stable error code for an invalid provider identifier.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_PROVIDER_ID_INVALID;
|
|
/// Stable error code when a generic refresh targets an unconfigured provider.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_PROVIDER_NOT_FOUND;
|
|
/// Stable error code for a provider response that violates its adapter contract.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_PROVIDER_RESPONSE_INVALID;
|
|
/// Stable error code for invalid common provider settings.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_PROVIDER_SETTINGS_INVALID;
|
|
/// Stable error code for an invalid generic refresh request.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_REFRESH_INVALID;
|
|
/// Stable error code for an invalid provider registry.
|
|
pub use self::error::ERROR_CODE_MARKET_PRICE_REGISTRY_INVALID;
|
|
/// Birdeye Standard SOL/USD provider adapter.
|
|
pub use self::market_price_birdeye::MarketPriceBirdeyeProvider;
|
|
/// Birdeye Standard runtime settings.
|
|
pub use self::market_price_birdeye::MarketPriceBirdeyeSettings;
|
|
/// Coinbase Exchange SOL/USD provider adapter.
|
|
pub use self::market_price_coinbase_exchange::MarketPriceCoinbaseExchangeProvider;
|
|
/// Coinbase Exchange runtime settings.
|
|
pub use self::market_price_coinbase_exchange::MarketPriceCoinbaseExchangeSettings;
|
|
/// CoinGecko V1 access mode.
|
|
pub use self::market_price_coingecko::MarketPriceCoinGeckoAccessMode;
|
|
/// CoinGecko SOL/USD provider adapter.
|
|
pub use self::market_price_coingecko::MarketPriceCoinGeckoProvider;
|
|
/// CoinGecko runtime settings.
|
|
pub use self::market_price_coingecko::MarketPriceCoinGeckoSettings;
|
|
/// CoinMarketCap V1 access mode.
|
|
pub use self::market_price_coinmarketcap::MarketPriceCoinMarketCapAccessMode;
|
|
/// CoinMarketCap SOL/USD provider adapter.
|
|
pub use self::market_price_coinmarketcap::MarketPriceCoinMarketCapProvider;
|
|
/// CoinMarketCap runtime settings.
|
|
pub use self::market_price_coinmarketcap::MarketPriceCoinMarketCapSettings;
|
|
/// CoinPaprika SOL/USD provider adapter.
|
|
pub use self::market_price_coinpaprika::MarketPriceCoinPaprikaProvider;
|
|
/// CoinPaprika runtime settings.
|
|
pub use self::market_price_coinpaprika::MarketPriceCoinPaprikaSettings;
|
|
/// Maximum accepted byte length for one textual decimal input.
|
|
pub use self::market_price_decimal::MARKET_PRICE_DECIMAL_MAX_INPUT_BYTES;
|
|
/// Maximum decimal scale retained by the canonical SOL/USD price representation.
|
|
pub use self::market_price_decimal::MARKET_PRICE_DECIMAL_MAX_SCALE;
|
|
/// Exact positive decimal value used by the public market-price contract.
|
|
pub use self::market_price_decimal::MarketPriceDecimal;
|
|
/// DexScreener SOL/USD provider adapter bound to one configured Solana pair.
|
|
pub use self::market_price_dexscreener::MarketPriceDexScreenerProvider;
|
|
/// DexScreener runtime settings carrying the explicit Solana pair address.
|
|
pub use self::market_price_dexscreener::MarketPriceDexScreenerSettings;
|
|
/// Jupiter Developer Platform access mode.
|
|
pub use self::market_price_jupiter::MarketPriceJupiterAccessMode;
|
|
/// Jupiter Price V3 SOL/USD provider adapter.
|
|
pub use self::market_price_jupiter::MarketPriceJupiterProvider;
|
|
/// Jupiter Price V3 runtime settings.
|
|
pub use self::market_price_jupiter::MarketPriceJupiterSettings;
|
|
/// Kraken Spot SOL/USD provider adapter.
|
|
pub use self::market_price_kraken::MarketPriceKrakenProvider;
|
|
/// Kraken Spot runtime settings.
|
|
pub use self::market_price_kraken::MarketPriceKrakenSettings;
|
|
/// Maximum safe provenance length attached to one normalized observation.
|
|
pub use self::market_price_observation::MARKET_PRICE_PROVENANCE_MAX_BYTES;
|
|
/// Public V1 SOL/USD observation normalized by Off-chain Transport.
|
|
pub use self::market_price_observation::MarketPriceObservation;
|
|
/// Safe bounded provenance supplied by one provider adapter.
|
|
pub use self::market_price_observation::MarketPriceProvenance;
|
|
/// Millisecond UTC timestamp used for request, receipt, provider and cooldown projections.
|
|
pub use self::market_price_observation::MarketPriceTimestamp;
|
|
/// Maximum provider display-name length accepted by descriptors.
|
|
pub use self::market_price_provider::MARKET_PRICE_PROVIDER_DISPLAY_NAME_MAX_BYTES;
|
|
/// Maximum opaque provider identifier length accepted by the public contract.
|
|
pub use self::market_price_provider::MARKET_PRICE_PROVIDER_ID_MAX_BYTES;
|
|
/// Only price pair exposed by the `0.2.11` V1 public contract.
|
|
pub use self::market_price_provider::MarketPricePair;
|
|
/// Generic authentication capability exposed by a configured provider descriptor.
|
|
pub use self::market_price_provider::MarketPriceProviderAuthMode;
|
|
/// Generic runtime availability state exposed without provider-specific error parsing.
|
|
pub use self::market_price_provider::MarketPriceProviderAvailability;
|
|
/// Provider capability and presentation descriptor consumed by provider-agnostic callers.
|
|
pub use self::market_price_provider::MarketPriceProviderDescriptor;
|
|
/// Opaque validated provider identifier owned by Off-chain Transport.
|
|
pub use self::market_price_provider::MarketPriceProviderId;
|
|
/// Long-term provider quota descriptor that is informational rather than an authoritative local counter.
|
|
pub use self::market_price_provider::MarketPriceProviderLongTermQuota;
|
|
/// Period used by a documented long-term provider quota.
|
|
pub use self::market_price_provider::MarketPriceProviderQuotaPeriod;
|
|
/// Unit used by a documented long-term provider quota.
|
|
pub use self::market_price_provider::MarketPriceProviderQuotaUnit;
|
|
/// Generic provider request-limit capability.
|
|
pub use self::market_price_provider::MarketPriceProviderRateLimit;
|
|
/// Shape of one generic provider request-limit capability.
|
|
pub use self::market_price_provider::MarketPriceProviderRateLimitKind;
|
|
/// Scope to which a provider documents one request limit.
|
|
pub use self::market_price_provider::MarketPriceProviderRateLimitScope;
|
|
/// Informational cost of one normalized SOL/USD request in a provider-defined quota unit.
|
|
pub use self::market_price_provider::MarketPriceProviderRequestCost;
|
|
/// Current provider-neutral runtime state projection.
|
|
pub use self::market_price_provider::MarketPriceProviderState;
|
|
/// Market-price semantics retained so consumers never assume all providers report equivalent market values.
|
|
pub use self::market_price_provider::MarketPriceSemantics;
|
|
/// Deterministically ordered registry of configured market-price providers.
|
|
pub use self::market_price_registry::MarketPriceProviderRegistry;
|
|
/// Immutable descriptor-plus-state entry exposed by the configured provider registry.
|
|
pub use self::market_price_registry::MarketPriceProviderRegistryEntry;
|
|
/// Provider-specific setup accepted once by the generic market-price service.
|
|
pub use self::market_price_service::MarketPriceProviderSetup;
|
|
/// Generic result of one market-price refresh.
|
|
pub use self::market_price_service::MarketPriceRefreshOutcome;
|
|
/// Provider-agnostic market-price refresh service.
|
|
pub use self::market_price_service::MarketPriceService;
|
|
/// Common provider settings shared by provider-specific runtime settings.
|
|
pub use self::market_price_settings::MarketPriceProviderCommonSettings;
|
|
|
|
/// Owning tracing target for events emitted by Off-chain Transport.
|
|
pub(crate) use self::constants::TRACING_TARGET;
|
|
/// Maximum provider-directed cooldown accepted from a server `Retry-After` value.
|
|
pub(crate) use self::http_admission::HTTP_MAX_RETRY_AFTER;
|
|
/// Crate-internal non-blocking request-admission controller.
|
|
pub(crate) use self::http_admission::HttpAdmissionController;
|
|
/// Crate-internal result of one immediate request-admission attempt.
|
|
pub(crate) use self::http_admission::HttpAdmissionDecision;
|
|
/// Crate-internal provider-neutral local request-admission policy.
|
|
pub(crate) use self::http_admission::HttpAdmissionPolicy;
|
|
/// Crate-internal fixed-origin GET request with redacted diagnostics.
|
|
pub(crate) use self::http_client::HttpGetRequest;
|
|
/// Crate-internal bounded syntactically valid JSON response document.
|
|
pub(crate) use self::http_client::HttpJsonDocument;
|
|
/// Crate-internal hardened REST client shared by capability adapters.
|
|
pub(crate) use self::http_client::HttpRestClient;
|
|
/// Crate-internal bounded HTTP runtime settings.
|
|
pub(crate) use self::http_settings::HttpClientSettings;
|
|
/// Applies one market-price request admission decision.
|
|
pub(crate) use self::market_price_adapter::admit_request;
|
|
/// Captures the current market-price wall-clock timestamp.
|
|
pub(crate) use self::market_price_adapter::current_timestamp;
|
|
/// Executes one market-price HTTP GET with rate-limit feedback.
|
|
pub(crate) use self::market_price_adapter::get_json;
|
|
/// Builds one safe invalid-provider-response error.
|
|
pub(crate) use self::market_price_adapter::invalid_provider_response;
|
|
/// Builds one safe invalid-provider-response error with parser source.
|
|
pub(crate) use self::market_price_adapter::invalid_provider_response_with_source;
|
|
/// Parses one RFC 3339 provider market-price timestamp.
|
|
pub(crate) use self::market_price_adapter::market_price_timestamp_from_rfc3339;
|
|
/// Converts whole Unix seconds into a market-price timestamp.
|
|
pub(crate) use self::market_price_adapter::market_price_timestamp_from_unix_seconds;
|
|
/// Builds the disabled-provider error used by direct adapters.
|
|
pub(crate) use self::market_price_adapter::provider_disabled_error;
|
|
/// Builds common HTTP runtime primitives for one market-price provider.
|
|
pub(crate) use self::market_price_adapter::provider_http_runtime;
|
|
/// Crate-internal redacted holder for provider API keys.
|
|
pub(crate) use self::market_price_api_key::MarketPriceApiKey;
|