144 lines
8.6 KiB
Rust
144 lines
8.6 KiB
Rust
// file: crates/ksp-job-backfill-lib/src/lib.rs
|
|
// version: 6
|
|
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
//! Concrete bounded historical RAW transaction Backfill foundation.
|
|
//!
|
|
//! This tranche owns explicit admission, network-scoped candidate identity, deterministic
|
|
//! `getSignaturesForAddress` pagination and canonical RAW v1 conversion through observed
|
|
//! `getTransaction`. Transport retains provider/endpoint selection and retry; Store retains
|
|
//! durable idempotence through the atomic Store facade. This tranche also owns bounded concurrent
|
|
//! candidate execution, caller-owned contiguous checkpoints, cooperative cancellation and concrete
|
|
//! latest-value snapshots for external listeners.
|
|
|
|
mod checkpoint;
|
|
mod constants;
|
|
mod conversion;
|
|
mod discovery;
|
|
mod error;
|
|
mod execution;
|
|
mod persistence;
|
|
mod request;
|
|
mod runtime;
|
|
|
|
/// Opaque caller-owned checkpoint for one controlled Backfill resumption.
|
|
pub use self::checkpoint::BackfillCheckpoint;
|
|
/// Result of hydrating one deterministic candidate through observed `getTransaction`.
|
|
pub use self::conversion::BackfillHydrationOutcome;
|
|
/// Complete in-memory RAW transaction acquisition ready for later Store persistence.
|
|
pub use self::conversion::BackfillRawAcquisition;
|
|
/// KSP-owned source-independent RAW transaction format identifier produced by this Backfill vertical.
|
|
pub use self::conversion::RAW_TRANSACTION_FORMAT_ID;
|
|
/// Initial KSP-owned RAW transaction format version produced by this Backfill vertical.
|
|
pub use self::conversion::RAW_TRANSACTION_FORMAT_VERSION;
|
|
/// Hydrates one candidate through observed Transport and converts a non-null response to canonical RAW v1.
|
|
pub use self::conversion::hydrate_backfill_candidate;
|
|
/// One deterministic transaction candidate produced by bounded discovery.
|
|
pub use self::discovery::BackfillCandidate;
|
|
/// Network-scoped identity of one discovered transaction candidate before canonical signature decoding.
|
|
pub use self::discovery::BackfillCandidateIdentity;
|
|
/// Complete bounded output of one candidate discovery pass.
|
|
pub use self::discovery::BackfillDiscovery;
|
|
/// Reason bounded candidate discovery stopped.
|
|
pub use self::discovery::BackfillDiscoveryBoundary;
|
|
/// Discovers one bounded deterministic candidate set through the typed KSP Transport wrapper.
|
|
pub use self::discovery::discover_backfill_candidates;
|
|
/// Error code used when one checkpoint/frontier is incompatible with the current Job or semantic scope.
|
|
pub use self::error::ERROR_CODE_BACKFILL_CHECKPOINT_INVALID;
|
|
/// Error code used when a signature page violates a bounded discovery invariant.
|
|
pub use self::error::ERROR_CODE_BACKFILL_DISCOVERY_INVALID;
|
|
/// Error code used when paginated discovery cannot advance its exclusive RPC cursor safely.
|
|
pub use self::error::ERROR_CODE_BACKFILL_DISCOVERY_STALLED;
|
|
/// Error code used when bounded concurrent execution violates an internal admission or clock invariant.
|
|
pub use self::error::ERROR_CODE_BACKFILL_EXECUTION_INVALID;
|
|
/// Error code used when Store persistence returns an impossible Backfill state or targets a different network.
|
|
pub use self::error::ERROR_CODE_BACKFILL_PERSISTENCE_INVALID;
|
|
/// Error code used when deterministic Transport-to-RAW conversion violates the v1 contract.
|
|
pub use self::error::ERROR_CODE_BACKFILL_RAW_CONVERSION_INVALID;
|
|
/// Error code used when one Backfill request violates its bounded admission contract.
|
|
pub use self::error::ERROR_CODE_BACKFILL_REQUEST_INVALID;
|
|
/// Error code used when the concrete Backfill runtime reaches an impossible lifecycle or notification state.
|
|
pub use self::error::ERROR_CODE_BACKFILL_RUNTIME_INVALID;
|
|
/// Error code used when one transaction signature text violates the bounded Base58-shape contract.
|
|
pub use self::error::ERROR_CODE_BACKFILL_SIGNATURE_INVALID;
|
|
/// Bounded result of one concurrent Backfill candidate execution pass.
|
|
pub use self::execution::BackfillExecutionBatch;
|
|
/// Executes one bounded discovered candidate set with request-owned hydration concurrency.
|
|
pub use self::execution::execute_backfill_discovery;
|
|
/// Canonical entity disposition produced by one Backfill Store persistence attempt.
|
|
pub use self::persistence::BackfillEntityPersistence;
|
|
/// Observation disposition produced by one Backfill Store persistence attempt.
|
|
pub use self::persistence::BackfillObservationPersistence;
|
|
/// Stable Backfill projection of one hydration persistence result.
|
|
pub use self::persistence::BackfillPersistenceOutcome;
|
|
/// Persists one hydrated result through the backend-neutral atomic Store contract.
|
|
pub use self::persistence::persist_backfill_hydration;
|
|
/// Commitment levels intentionally admitted by the historical Backfill vertical.
|
|
pub use self::request::BackfillCommitment;
|
|
/// Fully explicit bounded request for one historical transaction Backfill Job.
|
|
pub use self::request::BackfillRequest;
|
|
/// Validated bounded discovery scope for one historical Backfill Job.
|
|
pub use self::request::BackfillScope;
|
|
/// Opaque deterministic fingerprint of one semantic Backfill scope.
|
|
pub use self::request::BackfillScopeFingerprint;
|
|
/// Stable category of one bounded Backfill discovery scope.
|
|
pub use self::request::BackfillScopeKind;
|
|
/// Bounded Base58-shaped transaction signature text with exact RAW signature conversion.
|
|
pub use self::request::BackfillSignature;
|
|
/// Maximum number of transaction candidates admitted by one bounded Backfill Job.
|
|
pub use self::request::MAX_BACKFILL_CANDIDATES;
|
|
/// Maximum number of concurrent transaction hydrations admitted by one Backfill request.
|
|
pub use self::request::MAX_BACKFILL_HYDRATION_CONCURRENCY;
|
|
/// Maximum page size admitted for one `getSignaturesForAddress` request.
|
|
pub use self::request::MAX_BACKFILL_PAGE_SIZE;
|
|
/// Maximum number of `getSignaturesForAddress` pages admitted by one address Backfill request.
|
|
pub use self::request::MAX_BACKFILL_PAGES;
|
|
/// Maximum Base58 text length possible for one canonical 64-byte Solana signature.
|
|
pub use self::request::MAX_BACKFILL_SIGNATURE_TEXT_BYTES;
|
|
/// Minimum Base58 text length possible for one canonical 64-byte Solana signature.
|
|
pub use self::request::MIN_BACKFILL_SIGNATURE_TEXT_BYTES;
|
|
/// Stable Job kind code used by the concrete historical RAW transaction Backfill runtime.
|
|
pub use self::runtime::BACKFILL_JOB_KIND_CODE;
|
|
/// Cloneable external control handle for one concrete Backfill runtime.
|
|
pub use self::runtime::BackfillJobHandle;
|
|
/// Current concrete phase of one historical RAW transaction Backfill Job.
|
|
pub use self::runtime::BackfillJobPhase;
|
|
/// Concrete single-run Backfill coordinator paired with a cloneable control/snapshot handle.
|
|
pub use self::runtime::BackfillJobRuntime;
|
|
/// Complete safe latest-value snapshot of one concrete historical RAW transaction Backfill Job.
|
|
pub use self::runtime::BackfillJobSnapshot;
|
|
/// Cloneable runtime-neutral-facing latest-value source for concrete Backfill snapshots.
|
|
pub use self::runtime::BackfillSnapshotSource;
|
|
|
|
/// Internal contiguous completion frontier used by bounded execution.
|
|
pub(crate) use self::checkpoint::CompletionFrontier;
|
|
/// Builds one safe caller-owned checkpoint from the current contiguous frontier.
|
|
pub(crate) use self::checkpoint::checkpoint_from_frontier;
|
|
/// Resolves the candidate offset skipped by one validated replay checkpoint.
|
|
pub(crate) use self::checkpoint::execution_resume_offset;
|
|
/// Resolves the internal exclusive Before cursor for discovery resumption.
|
|
pub(crate) use self::checkpoint::resume_before_cursor;
|
|
/// Validates that one discovery result belongs to the current request identity.
|
|
pub(crate) use self::checkpoint::validate_discovery_identity;
|
|
/// Validates one caller-owned checkpoint against Job and semantic scope identity.
|
|
pub(crate) use self::checkpoint::validate_request_checkpoint;
|
|
/// Owning tracing target used by the concrete Backfill runtime.
|
|
pub(crate) use self::constants::TRACING_TARGET;
|
|
/// Exact private Base58 decoder shared by the public signature wrapper and hydration path.
|
|
pub(crate) use self::conversion::decode_backfill_signature;
|
|
/// Internal cancellable discovery path used by the concrete runtime.
|
|
pub(crate) use self::discovery::discover_backfill_candidates_cancellable;
|
|
/// Internal cooperative cancellation code used to distinguish cancellation from failure.
|
|
pub(crate) use self::error::ERROR_CODE_BACKFILL_CANCELLED;
|
|
/// Internal execution progress facts fed into the concrete latest-value source.
|
|
pub(crate) use self::execution::BackfillExecutionProgress;
|
|
/// Internal cancellable execution path used by the concrete runtime.
|
|
pub(crate) use self::execution::execute_backfill_discovery_cancellable;
|
|
/// Internal concrete cancellation signal shared by discovery and execution.
|
|
pub(crate) use self::runtime::BackfillCancellationSignal;
|
|
/// Internal execution progress publisher feeding the latest-value snapshot source.
|
|
pub(crate) use self::runtime::BackfillRuntimePublisher;
|