Utilisation de ks-store

Connexion PostgreSQL

let options = match ks_store::PostgresStoreOptions::new(
    database_url,
    10,
    10_000,
    true,
) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("postgres endpoint: {}", options.masked_dsn());

let store = match ks_store::PostgresStore::connect(options).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

PostgresStoreOptions::new valide le DSN, le nombre de connexions et le timeout. Lorsque auto_initialize_schema vaut true, la connexion applique les schémas idempotents. Utiliser masked_dsn ou mask_postgres_dsn dans les logs ; ne jamais journaliser le DSN brut.

Diagnostics

let health = store.health_snapshot().await;
let migrations = store.migration_snapshot().await;
let backend = store.backend_diagnostics().await;

println!("health={:?}", health.status);
println!("migration={:?}", migrations.status);
println!("backend={:?}", backend.descriptor.backend);

Les diagnostics de tables raw, Core et decode/materialization sont également disponibles par les méthodes *_table_diagnostics.

let raw_tables = match store.raw_table_diagnostics().await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

for table in raw_tables {
    println!(
        "table={} domain={} exists={}",
        table.table_name,
        table.domain,
        table.exists
    );
}

Pagination bornée

let first_page = ks_store::PageRequest::first_page();

let next_page = match ks_store::PageRequest::new(250, 250) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

assert_eq!(first_page.limit, ks_store::DEFAULT_PAGE_SIZE);
assert!(next_page.limit <= ks_store::MAX_PAGE_SIZE);

Contrats de repositories

Les traits publics principaux sont :

StoreHealthStore ;
RawTransactionStore ;
CoreTransactionStore ;
CoreExtractionStore ;
DecodePipelineStore ;
ProgramObservationStore ;
DecodedEventStore ;
MaterializedEventStore ;
ProcessingLedgerStore.

Ils permettent au pipeline de dépendre d’un contrat async plutôt que d’une requête SQL directe.

Replay et requêtes bornées

let candidates = match store.replay_transaction_candidates(filter).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

for candidate in candidates {
    println!(
        "signature={} slot={}",
        candidate.signature,
        candidate.slot
    );
}

let programs = match store.replay_program_summaries(program_filter).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

let entities = match store.replay_entity_summaries(entity_filter).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("programs={}, entities={}", programs.len(), entities.len());

Les filtres refusent les limites nulles ou supérieures aux bornes publiques. PageRequest impose également DEFAULT_PAGE_SIZE et MAX_PAGE_SIZE.

Transactions atomiques

Les bundles CoreExtractionBundle, DecodePersistenceBundle et MaterializationPersistenceBundle regroupent les écritures qui doivent réussir ou être annulées ensemble. Les consommateurs ne doivent pas reproduire manuellement ces transactions avec des écritures isolées.

Validation des noms de tables

if let Err(error) = ks_store::validate_raw_store_table_names() {
    return Err(error);
}
if let Err(error) = ks_store::validate_core_store_table_names() {
    return Err(error);
}
if let Err(error) = ks_store::validate_decode_store_table_names() {
    return Err(error);
}

assert!(ks_store::is_valid_solana_table_name(
    ks_store::CORE_TRANSACTIONS_TABLE_NAME
));

Schéma et tables

Les constantes RAW_STORE_TABLE_NAMES, CORE_STORE_TABLE_NAMES et DECODE_STORE_TABLE_NAMES exposent les noms canoniques. Les fonctions validate_*_table_names et is_valid_solana_table_name servent aux audits et outils d’administration.

Erreurs et invariants

Toutes les APIs utilisent ks_core::Result. Les DTO valident notamment les signatures, chemins, Program IDs, clés, montants, états de traitement et identités de ledger. Les erreurs de contrat peuvent être construites avec storage_contract_error.

Tests instructifs

les tests *_rejects_* documentent les invariants des DTO et filtres ;
decoded_events_and_ledger_roll_back_together vérifie l’atomicité ;
optional_postgres_*_from_env couvre les parcours réels lorsque l’environnement PostgreSQL est configuré ;
les tests de schéma vérifient les noms, index, contraintes et migrations.

Limites

backend actif : PostgreSQL ;
les tests réels sont optionnels sans DSN de test ;
la crate ne prend aucune décision de décodage ou de matérialisation.

4.8 KiB Raw Blame History Unescape Escape