provider.rpc_counter_maintenance

Documentation for eth_defi.provider.rpc_counter_maintenance Python module.

Verified snapshots and recoverable resets of scanner request counters.

The caller holds the scanner’s pipeline lock for this entire operation. DuckDB file locking provides a second check against writers outside that convention. Legacy accounting schemas stay unchanged so a scanner rollback remains safe. See eth_defi.provider.rpcdb for the physical-attempt accounting contract.

Module Attributes

COUNTER_TABLES

Only these tables contain counters reset by this utility.

RESET_TABLE

Durable reset receipts are deliberately preserved across subsequent resets.

backup_rpc_counters(database_path, backup_dir)

Compatibility name for existing maintenance callers; new callers should use the name that makes the optional destructive reset explicit.

Functions

backup_rpc_counters(database_path, backup_dir)

Compatibility name for existing maintenance callers; new callers should use the name that makes the optional destructive reset explicit.

fetch_counter_inventory(connection)

Inspect every table, retaining canonical content digests and aggregates.

fetch_protected_state_digests(paths)

Hash protected pipeline state without reading it into memory.

snapshot_and_reset_rpc_counters(...[, ...])

Create a verified dated snapshot and optionally reset physical counters.
COUNTER_TABLES = ('vault_rpc_api_calls', 'vault_rpc_api_errors', 'vault_rpc_operation_calls')

Only these tables contain counters reset by this utility.

RESET_TABLE = 'vault_rpc_counter_resets'

Durable reset receipts are deliberately preserved across subsequent resets.

fetch_protected_state_digests(paths)

Hash protected pipeline state without reading it into memory.

Chunk progress keeps large Parquet and timestamp-cache checks observable. No file is opened for writing or interpreted as application state.

Parameters

paths (tuple[pathlib.Path, ...]) – Explicit critical files selected by the maintenance caller.

Returns

Absolute filenames to SHA-256 digests.

Return type

dict[str, str]

fetch_counter_inventory(connection)

Inspect every table, retaining canonical content digests and aggregates.

Digests include all rows, including errors, without exposing messages in operator output. Ordering makes the digest independent of storage layout. The returned inventory is suitable for source/backup equality checks.

Parameters

connection (_duckdb.DuckDBPyConnection) – Open connection owned by the maintenance operation.

Returns

Table schemas, counts, digests and counter summaries.

Return type

dict[str, Any]

snapshot_and_reset_rpc_counters(database_path, backup_dir, reset_id=None, now=None, protected_paths=())

Create a verified dated snapshot and optionally reset physical counters.

Hold wait_other_writers(PIPELINE_DATA_DIR / 'scan-pipeline') throughout. With no reset ID this only snapshots counters. With an ID, a verified backup precedes the transactional reset. Repeating a committed ID verifies its backup and returns its receipt without clearing newly accumulated calls. No other pipeline files are touched. DuckDB’s locking semantics are described at https://duckdb.org/docs/stable/connect/concurrency.html.

The maintenance script selects protected files and owns the pipeline lock; this helper owns only the accounting database. Protected hashes prove those files did not change during maintenance, but are not backups of their data. The dated database copy, pre-reset manifest and transactional reset receipt serve different recovery points: deletion is allowed only after the first two are verified and durable, and the receipt makes a committed reset recoverable even if writing its final JSON acknowledgement fails.

Parameters

  • database_path (pathlib.Path) – Existing accounting database, never created implicitly.

  • backup_dir (pathlib.Path) – Private non-rotating snapshot directory.

  • reset_id (Optional[str]) – Stable identity for an intentional reset, or None for snapshot.

  • now (Optional[datetime.datetime]) – Naive UTC timestamp; defaults to the current UTC time.

  • protected_paths (tuple[pathlib.Path, ...]) – Critical files whose hashes must remain unchanged.

Returns

Verified manifest, including backup path and reset status.

Return type

dict

backup_rpc_counters(database_path, backup_dir, reset_id=None, now=None, protected_paths=())

Compatibility name for existing maintenance callers; new callers should use the name that makes the optional destructive reset explicit.

Parameters
Return type

dict