v0.3.8-pre.003
This commit is contained in:
366
crates/ksp-store-api/src/model/raw_inspection.rs
Normal file
366
crates/ksp-store-api/src/model/raw_inspection.rs
Normal file
@@ -0,0 +1,366 @@
|
||||
// file: crates/ksp-store-api/src/model/raw_inspection.rs
|
||||
// version: 1
|
||||
|
||||
/// Random-access page request dedicated to bounded interactive RAW inspection.
|
||||
///
|
||||
/// This request is intentionally distinct from [`crate::RawPageRequest`]. It
|
||||
/// provides offset/limit semantics for operator-facing inspection while the
|
||||
/// canonical RAW list APIs keep their opaque backend cursors for replay,
|
||||
/// backfill and worker traversal.
|
||||
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
|
||||
pub struct RawInspectionPageRequest {
|
||||
limit: crate::RawPageLimit,
|
||||
offset: u64,
|
||||
}
|
||||
|
||||
impl RawInspectionPageRequest {
|
||||
/// Creates one inspection request from an absolute zero-based offset and positive page limit.
|
||||
#[must_use]
|
||||
pub const fn new(offset: u64, limit: crate::RawPageLimit) -> Self {
|
||||
return Self { limit, offset };
|
||||
}
|
||||
|
||||
/// Returns the exact caller-requested page size.
|
||||
#[must_use]
|
||||
pub const fn limit(&self) -> crate::RawPageLimit {
|
||||
return self.limit;
|
||||
}
|
||||
|
||||
/// Returns the absolute zero-based item offset within the filtered result set.
|
||||
#[must_use]
|
||||
pub const fn offset(&self) -> u64 {
|
||||
return self.offset;
|
||||
}
|
||||
}
|
||||
|
||||
/// One bounded random-access inspection page with exact logical counts.
|
||||
///
|
||||
/// `total_items` is the exact count inside the mandatory query scope before
|
||||
/// optional filters. `filtered_items` is the exact count after optional query
|
||||
/// filters. The item vector contains only the requested page window.
|
||||
#[derive(Debug)]
|
||||
pub struct RawInspectionPage<T> {
|
||||
filtered_items: u64,
|
||||
items: std::vec::Vec<T>,
|
||||
total_items: u64,
|
||||
}
|
||||
|
||||
impl<T> RawInspectionPage<T> {
|
||||
/// Creates one inspection page after validating count consistency.
|
||||
pub fn try_new(items: std::vec::Vec<T>, total_items: u64, filtered_items: u64) -> crate::Result<Self> {
|
||||
if filtered_items > total_items {
|
||||
return std::result::Result::Err(raw_model_error("filtered_items"));
|
||||
}
|
||||
let item_count = u64::try_from(items.len());
|
||||
let item_count = match item_count {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(_) => return std::result::Result::Err(raw_model_error("items")),
|
||||
};
|
||||
if item_count > filtered_items {
|
||||
return std::result::Result::Err(raw_model_error("items"));
|
||||
}
|
||||
return std::result::Result::Ok(Self { filtered_items, items, total_items });
|
||||
}
|
||||
|
||||
/// Returns the exact count after optional query filters.
|
||||
#[must_use]
|
||||
pub const fn filtered_items(&self) -> u64 {
|
||||
return self.filtered_items;
|
||||
}
|
||||
|
||||
/// Returns the current inspection page items.
|
||||
#[must_use]
|
||||
pub fn items(&self) -> &[T] {
|
||||
return self.items.as_slice();
|
||||
}
|
||||
|
||||
/// Consumes the page and returns its bounded inspection items.
|
||||
#[must_use]
|
||||
pub fn into_items(self) -> std::vec::Vec<T> {
|
||||
return self.items;
|
||||
}
|
||||
|
||||
/// Returns the exact count before optional query filters inside the mandatory scope.
|
||||
#[must_use]
|
||||
pub const fn total_items(&self) -> u64 {
|
||||
return self.total_items;
|
||||
}
|
||||
}
|
||||
|
||||
/// Backend-independent random-access inspection query for RAW transactions.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct RawTransactionInspectionQuery {
|
||||
direction: crate::RawSortDirection,
|
||||
network: crate::RawNetworkId,
|
||||
page: crate::RawInspectionPageRequest,
|
||||
slots: crate::RawSlotRange,
|
||||
}
|
||||
|
||||
impl RawTransactionInspectionQuery {
|
||||
/// Creates one transaction inspection query.
|
||||
#[must_use]
|
||||
pub fn new(network: crate::RawNetworkId, slots: crate::RawSlotRange, direction: crate::RawSortDirection, page: crate::RawInspectionPageRequest) -> Self {
|
||||
return Self { direction, network, page, slots };
|
||||
}
|
||||
|
||||
/// Returns the requested deterministic traversal direction.
|
||||
#[must_use]
|
||||
pub const fn direction(&self) -> crate::RawSortDirection {
|
||||
return self.direction;
|
||||
}
|
||||
|
||||
/// Returns the mandatory logical network scope.
|
||||
#[must_use]
|
||||
pub fn network(&self) -> &crate::RawNetworkId {
|
||||
return &self.network;
|
||||
}
|
||||
|
||||
/// Returns the random-access inspection page request.
|
||||
#[must_use]
|
||||
pub const fn page(&self) -> crate::RawInspectionPageRequest {
|
||||
return self.page;
|
||||
}
|
||||
|
||||
/// Returns optional inclusive slot filters.
|
||||
#[must_use]
|
||||
pub const fn slots(&self) -> crate::RawSlotRange {
|
||||
return self.slots;
|
||||
}
|
||||
}
|
||||
|
||||
/// Backend-independent random-access inspection query for RAW account states.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct RawAccountStateInspectionQuery {
|
||||
direction: crate::RawSortDirection,
|
||||
network: crate::RawNetworkId,
|
||||
page: crate::RawInspectionPageRequest,
|
||||
pubkey: std::option::Option<crate::Pubkey>,
|
||||
slots: crate::RawSlotRange,
|
||||
}
|
||||
|
||||
impl RawAccountStateInspectionQuery {
|
||||
/// Creates one account-state inspection query.
|
||||
#[must_use]
|
||||
pub fn new(
|
||||
network: crate::RawNetworkId,
|
||||
pubkey: std::option::Option<crate::Pubkey>,
|
||||
slots: crate::RawSlotRange,
|
||||
direction: crate::RawSortDirection,
|
||||
page: crate::RawInspectionPageRequest,
|
||||
) -> Self {
|
||||
return Self { direction, network, page, pubkey, slots };
|
||||
}
|
||||
|
||||
/// Returns the requested deterministic traversal direction.
|
||||
#[must_use]
|
||||
pub const fn direction(&self) -> crate::RawSortDirection {
|
||||
return self.direction;
|
||||
}
|
||||
|
||||
/// Returns the mandatory logical network scope.
|
||||
#[must_use]
|
||||
pub fn network(&self) -> &crate::RawNetworkId {
|
||||
return &self.network;
|
||||
}
|
||||
|
||||
/// Returns the random-access inspection page request.
|
||||
#[must_use]
|
||||
pub const fn page(&self) -> crate::RawInspectionPageRequest {
|
||||
return self.page;
|
||||
}
|
||||
|
||||
/// Returns an optional exact account-address filter.
|
||||
#[must_use]
|
||||
pub fn pubkey(&self) -> std::option::Option<&crate::Pubkey> {
|
||||
return self.pubkey.as_ref();
|
||||
}
|
||||
|
||||
/// Returns optional inclusive slot filters.
|
||||
#[must_use]
|
||||
pub const fn slots(&self) -> crate::RawSlotRange {
|
||||
return self.slots;
|
||||
}
|
||||
}
|
||||
|
||||
/// Payload-free summary of one canonical RAW transaction for operator inspection.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct RawTransactionSummary {
|
||||
block_time: std::option::Option<crate::RawTimestamp>,
|
||||
content_hash: crate::RawContentHash,
|
||||
format_id: crate::RawFormatId,
|
||||
format_version: u32,
|
||||
payload_size_bytes: std::option::Option<u64>,
|
||||
reference: crate::RawTransactionReference,
|
||||
retention_state: crate::RawRetentionState,
|
||||
slot: u64,
|
||||
}
|
||||
|
||||
impl RawTransactionSummary {
|
||||
/// Creates one payload-free transaction summary after validating summary invariants.
|
||||
pub fn try_new(
|
||||
reference: crate::RawTransactionReference,
|
||||
slot: u64,
|
||||
block_time: std::option::Option<crate::RawTimestamp>,
|
||||
format_id: crate::RawFormatId,
|
||||
format_version: u32,
|
||||
content_hash: crate::RawContentHash,
|
||||
payload_size_bytes: std::option::Option<u64>,
|
||||
retention_state: crate::RawRetentionState,
|
||||
) -> crate::Result<Self> {
|
||||
if format_version == 0 {
|
||||
return std::result::Result::Err(raw_model_error("format_version"));
|
||||
}
|
||||
if let std::option::Option::Some(size) = payload_size_bytes {
|
||||
let size = usize::try_from(size);
|
||||
let size = match size {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(_) => return std::result::Result::Err(raw_model_error("payload_size_bytes")),
|
||||
};
|
||||
if size == 0 || size > crate::MAX_RAW_PAYLOAD_BYTES {
|
||||
return std::result::Result::Err(raw_model_error("payload_size_bytes"));
|
||||
}
|
||||
}
|
||||
if retention_state == crate::RawRetentionState::Purged {
|
||||
if payload_size_bytes.is_some() {
|
||||
return std::result::Result::Err(raw_model_error("payload_size_bytes"));
|
||||
}
|
||||
} else if payload_size_bytes.is_none() {
|
||||
return std::result::Result::Err(raw_model_error("payload_size_bytes"));
|
||||
}
|
||||
return std::result::Result::Ok(Self {
|
||||
block_time,
|
||||
content_hash,
|
||||
format_id,
|
||||
format_version,
|
||||
payload_size_bytes,
|
||||
reference,
|
||||
retention_state,
|
||||
slot,
|
||||
});
|
||||
}
|
||||
|
||||
/// Returns the optional canonical block timestamp.
|
||||
#[must_use]
|
||||
pub const fn block_time(&self) -> std::option::Option<crate::RawTimestamp> {
|
||||
return self.block_time;
|
||||
}
|
||||
|
||||
/// Returns the deterministic canonical content digest.
|
||||
#[must_use]
|
||||
pub const fn content_hash(&self) -> crate::RawContentHash {
|
||||
return self.content_hash;
|
||||
}
|
||||
|
||||
/// Returns the KSP-owned canonical RAW format identifier.
|
||||
#[must_use]
|
||||
pub fn format_id(&self) -> &crate::RawFormatId {
|
||||
return &self.format_id;
|
||||
}
|
||||
|
||||
/// Returns the KSP-owned canonical RAW format version.
|
||||
#[must_use]
|
||||
pub const fn format_version(&self) -> u32 {
|
||||
return self.format_version;
|
||||
}
|
||||
|
||||
/// Returns the canonical payload size when payload content is logically retained.
|
||||
#[must_use]
|
||||
pub const fn payload_size_bytes(&self) -> std::option::Option<u64> {
|
||||
return self.payload_size_bytes;
|
||||
}
|
||||
|
||||
/// Returns the durable backend-independent transaction identity.
|
||||
#[must_use]
|
||||
pub fn reference(&self) -> &crate::RawTransactionReference {
|
||||
return &self.reference;
|
||||
}
|
||||
|
||||
/// Returns the logical RAW transaction retention state.
|
||||
#[must_use]
|
||||
pub const fn retention_state(&self) -> crate::RawRetentionState {
|
||||
return self.retention_state;
|
||||
}
|
||||
|
||||
/// Returns the Solana slot containing the transaction.
|
||||
#[must_use]
|
||||
pub const fn slot(&self) -> u64 {
|
||||
return self.slot;
|
||||
}
|
||||
}
|
||||
|
||||
/// Data-free summary of one canonical RAW account state for operator inspection.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub struct RawAccountStateSummary {
|
||||
data_length_bytes: u64,
|
||||
executable: bool,
|
||||
lamports: u64,
|
||||
owner: crate::Pubkey,
|
||||
reference: crate::RawAccountStateReference,
|
||||
rent_epoch: u64,
|
||||
}
|
||||
|
||||
impl RawAccountStateSummary {
|
||||
/// Creates one data-free account-state summary after validating its bounded data length.
|
||||
pub fn try_new(
|
||||
reference: crate::RawAccountStateReference,
|
||||
lamports: u64,
|
||||
owner: crate::Pubkey,
|
||||
executable: bool,
|
||||
rent_epoch: u64,
|
||||
data_length_bytes: u64,
|
||||
) -> crate::Result<Self> {
|
||||
let data_length = usize::try_from(data_length_bytes);
|
||||
let data_length = match data_length {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(_) => return std::result::Result::Err(raw_model_error("data_length_bytes")),
|
||||
};
|
||||
if data_length > crate::MAX_RAW_ACCOUNT_DATA_BYTES {
|
||||
return std::result::Result::Err(raw_model_error("data_length_bytes"));
|
||||
}
|
||||
return std::result::Result::Ok(Self { data_length_bytes, executable, lamports, owner, reference, rent_epoch });
|
||||
}
|
||||
|
||||
/// Returns the complete canonical account-data length without exposing account bytes.
|
||||
#[must_use]
|
||||
pub const fn data_length_bytes(&self) -> u64 {
|
||||
return self.data_length_bytes;
|
||||
}
|
||||
|
||||
/// Returns whether the account is executable.
|
||||
#[must_use]
|
||||
pub const fn executable(&self) -> bool {
|
||||
return self.executable;
|
||||
}
|
||||
|
||||
/// Returns the account lamport balance.
|
||||
#[must_use]
|
||||
pub const fn lamports(&self) -> u64 {
|
||||
return self.lamports;
|
||||
}
|
||||
|
||||
/// Returns the account owner program public key.
|
||||
#[must_use]
|
||||
pub const fn owner(&self) -> &crate::Pubkey {
|
||||
return &self.owner;
|
||||
}
|
||||
|
||||
/// Returns the durable backend-independent account-state identity.
|
||||
#[must_use]
|
||||
pub fn reference(&self) -> &crate::RawAccountStateReference {
|
||||
return &self.reference;
|
||||
}
|
||||
|
||||
/// Returns the rent epoch reported for this account state.
|
||||
#[must_use]
|
||||
pub const fn rent_epoch(&self) -> u64 {
|
||||
return self.rent_epoch;
|
||||
}
|
||||
}
|
||||
|
||||
fn raw_model_error(field: &'static str) -> crate::Error {
|
||||
return crate::Error::new(crate::ERROR_CODE_RAW_MODEL_INVALID, "invalid backend-agnostic RAW inspection model").with_context("field", field);
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
#[path = "../../unit_tests/model/raw_inspection.rs"]
|
||||
mod tests;
|
||||
Reference in New Issue
Block a user