158 lines
12 KiB
Rust
158 lines
12 KiB
Rust
// file: crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs
|
|
// version: 27
|
|
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
//! Source-neutral runtime foundation for continuous KSP RAW transaction ingestion.
|
|
//! Owned source, hydration and persistence tasks are bounded and joined before terminal publication.
|
|
//!
|
|
//! This tranche owns the concrete Worker family identity, validated technical settings
|
|
//! and the caller-runtime-owned lifecycle with private child-task supervision. This tranche also
|
|
//! owns bounded source-neutral admission, common RAW canonicalization/assembly and backend-neutral
|
|
//! Store persistence in normal mode plus concrete latest-value snapshots projected onto Worker API. The bounded 1..32 caller-composed aggregate starts
|
|
//! all validated Yellowstone, Standard Logs, Standard Block, Helius Transaction and HTTP live block polling sources under one private supervisor. Reference-bearing
|
|
//! sources share bounded cross-source hydration and fairness budgets; direct-qualified Standard Block and HTTP polling transactions enter the existing central
|
|
//! admission path directly. Public snapshots expose only source-neutral aggregate counts/state and conservative Worker health. Yellowstone
|
|
//! Transaction/TransactionStatus/Block and standard logs notifications become signature/slot references; BlockMeta/Slot remain continuity-only signals.
|
|
//! Hydration is coalesced by network/signature/commitment under bounded in-flight and pending budgets. A bounded run-local processing frontier projects
|
|
//! hydration pending, oldest pending slot and highest unblocked actually observed slot. The productive source also projects safe Transport reconnect/replay
|
|
//! state and faults conservatively when Transport proves a replay-retention continuity gap; history remediation remains outside this crate.
|
|
|
|
mod admission;
|
|
mod continuity;
|
|
mod error;
|
|
mod identity;
|
|
mod persistence;
|
|
mod runtime;
|
|
mod runtime_resources;
|
|
mod settings;
|
|
mod snapshot;
|
|
|
|
/// Error code used when durable Store content conflicts with one admitted canonical RAW transaction.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_CONTENT_CONFLICT;
|
|
/// Error code used when one monotone Worker counter or snapshot sequence cannot advance without wrapping.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_COUNTER_EXHAUSTED;
|
|
/// Error code used when private Worker tasks cannot drain before the configured shutdown deadline.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_DRAIN_TIMEOUT;
|
|
/// Error code used when the RAW transaction ingest Worker reaches an invalid runtime or lifecycle condition.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_RUNTIME_INVALID;
|
|
/// Error code used when RAW transaction ingest Worker settings violate one bounded runtime invariant.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_SETTINGS_INVALID;
|
|
/// Error code used when one private source task terminates with a classified failure.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_SOURCE_FAILED;
|
|
/// Error code used when Store persistence fails for one admitted canonical RAW transaction.
|
|
pub use self::error::ERROR_CODE_RAW_TRANSACTION_INGEST_STORE_FAILED;
|
|
/// Stable Worker kind code used by the continuous RAW transaction ingest vertical.
|
|
pub use self::identity::RAW_TRANSACTION_INGEST_WORKER_KIND_CODE;
|
|
/// Cloneable external control handle for one continuous RAW transaction ingest Worker.
|
|
pub use self::runtime::RawTransactionIngestHandle;
|
|
/// Runtime-neutral boxed future resolving after one RAW transaction ingest Worker has fully reached a terminal lifecycle state.
|
|
pub use self::runtime::RawTransactionIngestTerminalFuture;
|
|
/// Entry point owning synchronous validation and task launch for one RAW transaction ingest Worker run.
|
|
pub use self::runtime::RawTransactionIngestWorker;
|
|
/// Default interval between HTTP live block polling cycles.
|
|
pub use self::runtime_resources::DEFAULT_RAW_TRANSACTION_INGEST_HTTP_POLL_INTERVAL;
|
|
/// Default maximum number of confirmed blocks discovered during one HTTP live block polling cycle.
|
|
pub use self::runtime_resources::DEFAULT_RAW_TRANSACTION_INGEST_HTTP_POLL_MAX_BLOCKS_PER_CYCLE;
|
|
/// Maximum interval accepted between HTTP live block polling cycles.
|
|
pub use self::runtime_resources::MAX_RAW_TRANSACTION_INGEST_HTTP_POLL_INTERVAL;
|
|
/// Maximum number of confirmed blocks accepted during one HTTP live block polling cycle.
|
|
pub use self::runtime_resources::MAX_RAW_TRANSACTION_INGEST_HTTP_POLL_MAX_BLOCKS_PER_CYCLE;
|
|
/// Maximum number of logical live sources accepted by one runtime-resource aggregate.
|
|
pub use self::runtime_resources::MAX_RAW_TRANSACTION_INGEST_LIVE_SOURCES;
|
|
/// Minimum interval accepted between HTTP live block polling cycles.
|
|
pub use self::runtime_resources::MIN_RAW_TRANSACTION_INGEST_HTTP_POLL_INTERVAL;
|
|
/// Minimum number of confirmed blocks accepted during one HTTP live block polling cycle.
|
|
pub use self::runtime_resources::MIN_RAW_TRANSACTION_INGEST_HTTP_POLL_MAX_BLOCKS_PER_CYCLE;
|
|
/// Validated Helius `transactionSubscribe` + HTTP hydration source contract owned by the continuous RAW transaction ingest Worker.
|
|
pub use self::runtime_resources::RawTransactionIngestHeliusTransactionSource;
|
|
/// Validated standard Solana HTTP live block polling source contract owned by the continuous RAW transaction ingest Worker.
|
|
pub use self::runtime_resources::RawTransactionIngestHttpBlockPollingSource;
|
|
/// Caller-composed bounded runtime resources for supported continuous RAW transaction live-source families.
|
|
pub use self::runtime_resources::RawTransactionIngestRuntimeResources;
|
|
/// Validated standard Solana `blockSubscribe` direct RAW source contract owned by the continuous RAW transaction ingest Worker.
|
|
pub use self::runtime_resources::RawTransactionIngestStandardBlockSource;
|
|
/// Validated standard Solana `logsSubscribe` + HTTP hydration source contract owned by the continuous RAW transaction ingest Worker.
|
|
pub use self::runtime_resources::RawTransactionIngestStandardLogsSource;
|
|
/// Validated Yellowstone + HTTP source contract owned by the continuous RAW transaction ingest Worker.
|
|
pub use self::runtime_resources::RawTransactionIngestYellowstoneSource;
|
|
/// Default bounded admission queue capacity for one RAW transaction ingest Worker.
|
|
pub use self::settings::DEFAULT_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY;
|
|
/// Default number of concurrent Store persistence operations for one RAW transaction ingest Worker.
|
|
pub use self::settings::DEFAULT_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY;
|
|
/// Default cooperative shutdown drain deadline for one RAW transaction ingest Worker.
|
|
pub use self::settings::DEFAULT_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT;
|
|
/// Maximum bounded admission queue capacity for one RAW transaction ingest Worker.
|
|
pub use self::settings::MAX_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY;
|
|
/// Maximum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
|
|
pub use self::settings::MAX_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY;
|
|
/// Maximum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
|
|
pub use self::settings::MAX_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT;
|
|
/// Minimum bounded admission queue capacity for one RAW transaction ingest Worker.
|
|
pub use self::settings::MIN_RAW_TRANSACTION_INGEST_ADMISSION_QUEUE_CAPACITY;
|
|
/// Minimum number of concurrent Store persistence operations for one RAW transaction ingest Worker.
|
|
pub use self::settings::MIN_RAW_TRANSACTION_INGEST_PERSISTENCE_CONCURRENCY;
|
|
/// Minimum cooperative shutdown drain deadline for one RAW transaction ingest Worker.
|
|
pub use self::settings::MIN_RAW_TRANSACTION_INGEST_SHUTDOWN_DRAIN_TIMEOUT;
|
|
/// Validated source-neutral runtime settings for one continuous RAW transaction ingest Worker.
|
|
pub use self::settings::RawTransactionIngestSettings;
|
|
/// Complete safe latest-value snapshot of one continuous RAW transaction ingest Worker.
|
|
pub use self::snapshot::RawTransactionIngestSnapshot;
|
|
/// Runtime-neutral boxed future resolving to one newer concrete RAW transaction ingest Worker snapshot.
|
|
pub use self::snapshot::RawTransactionIngestSnapshotFuture;
|
|
/// Cloneable latest-value source exposing concrete and common Worker snapshots from one shared watch state.
|
|
pub use self::snapshot::RawTransactionIngestSnapshotSource;
|
|
/// Source-neutral lifecycle state of the productive RAW transaction ingest source.
|
|
pub use self::snapshot::RawTransactionIngestSourceState;
|
|
|
|
/// Receiver-side owner of the private bounded RAW transaction admission queue.
|
|
pub(crate) use self::admission::RawTransactionAdmission;
|
|
/// Crate-private source-neutral ingress sent through the bounded central admission queue.
|
|
pub(crate) use self::admission::RawTransactionIngress;
|
|
/// Maximum number of simultaneously retained non-repaired run-local continuity gaps.
|
|
pub(crate) use self::continuity::MAX_RAW_TRANSACTION_INGEST_OPEN_REPAIR_GAPS;
|
|
/// Maximum number of run-local continuity gaps that may actively repair at once.
|
|
pub(crate) use self::continuity::MAX_RAW_TRANSACTION_INGEST_REPAIR_ACTIVE_GAPS;
|
|
/// Maximum number of logical block fetches reserved for the later bounded repair scheduler.
|
|
pub(crate) use self::continuity::MAX_RAW_TRANSACTION_INGEST_REPAIR_BLOCK_FETCH_IN_FLIGHT;
|
|
/// Maximum number of slots reserved for one later HTTP repair discovery window.
|
|
pub(crate) use self::continuity::MAX_RAW_TRANSACTION_INGEST_REPAIR_DISCOVERY_WINDOW_SLOTS;
|
|
/// Maximum inclusive slot span accepted by one run-local repair gap.
|
|
pub(crate) use self::continuity::MAX_RAW_TRANSACTION_INGEST_REPAIR_RANGE_SLOTS;
|
|
/// Private run-local continuity aggregate containing capabilities, TargetCoverage and the gap ledger.
|
|
pub(crate) use self::continuity::RawTransactionIngestContinuityContracts;
|
|
/// Private provider-neutral coverage scope used by run-local continuity proof contracts.
|
|
pub(crate) use self::continuity::RawTransactionIngestCoverageScope;
|
|
/// Private source capability descriptor prepared without repair I/O.
|
|
pub(crate) use self::continuity::RawTransactionIngestRepairCapabilityDescriptor;
|
|
/// Creates one terminal content-conflict error without copying conflicting material into diagnostics.
|
|
pub(crate) use self::error::content_conflict_error;
|
|
/// Creates one terminal counter-exhaustion error without exposing runtime material.
|
|
pub(crate) use self::error::counter_exhausted_error;
|
|
/// Creates one runtime-domain error without copying runtime/provider/Store values into diagnostics.
|
|
pub(crate) use self::error::runtime_error;
|
|
/// Creates one settings-domain error without copying caller-supplied values into diagnostics.
|
|
pub(crate) use self::error::settings_error;
|
|
/// Creates one terminal Store error while retaining only the already-safe lower-layer ErrorCode.
|
|
pub(crate) use self::error::store_error;
|
|
/// Canonical entity disposition produced by one successful Worker Store persistence attempt.
|
|
pub(crate) use self::persistence::RawTransactionIngestEntityPersistence;
|
|
/// Observation disposition produced by one successful Worker Store persistence attempt.
|
|
pub(crate) use self::persistence::RawTransactionIngestObservationPersistence;
|
|
/// Private bounded run-local cache serializing repeated canonical identities before Store writes.
|
|
pub(crate) use self::persistence::RawTransactionIngestPersistenceConvergence;
|
|
/// Classified successful outcome of one atomic Worker Store persistence attempt.
|
|
pub(crate) use self::persistence::RawTransactionIngestPersistenceOutcome;
|
|
/// Private backend-neutral Store persistence port used by the Worker and deterministic tests.
|
|
pub(crate) use self::persistence::RawTransactionIngestPersistencePort;
|
|
/// Persists one already-canonical Worker acquisition through the private Store port in `Normal` mode.
|
|
pub(crate) use self::persistence::persist_raw_transaction_ingest_acquisition;
|
|
/// Persists one canonical acquisition through the bounded cross-source convergence cache.
|
|
pub(crate) use self::persistence::persist_raw_transaction_ingest_converged_acquisition;
|
|
/// Private latest-value processing-frontier projection emitted by the productive source task.
|
|
pub(crate) use self::snapshot::RawTransactionIngestProcessingFrontierProjection;
|
|
/// Private latest-value publisher and checked counter owner shared by the Worker supervisor.
|
|
pub(crate) use self::snapshot::RawTransactionIngestSnapshotPublisher;
|