5. Storage Engines & Backends (fleetmesh_node.storage)

The fleetmesh_node.storage package provides pluggable persistent storage for events, blobs, accounting ledgers, and peer grants across SQLite and PostgreSQL backends.

5.1. Storage Base Interface

The backend-independent half of a store: the lock, the transaction, and the declarative schema. Bound to SqliteDialect by default. Everything here is backend-independent and tested across supported backends.

Subclasses declare their schema rather than running DDL in __init__:

  • SCHEMA: CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS statements, one per entry, executed in order on every open. They must be idempotent, which the IF NOT EXISTS form guarantees.

  • MIGRATIONS: (version, sql) pairs, ascending. Each is applied once, when the stored schema version is below version; afterwards the version is raised to the highest applied. A fresh database runs through every migration too, so SCHEMA can stay the original DDL and a column added later is expressed exactly once, as the ALTER TABLE that added it. A database from before the version was tracked may already carry such a column (the old open path added it under a has_column guard): a duplicate-column error from an ADD COLUMN migration is therefore treated as “already applied”, which the dialect decides rather than a message match here.

  • _post_schema(): hook for data backfills that need Python, run inside the same transaction after the migrations.

All of it runs in _ensure_schema() as one transaction at open, so a crash midway leaves the database as it was.

DURABILITY names what a store needs of its backend, for the three classes in docs/storage-backends.md section 6:

‘commit’ a write is durable before the call returns ‘window’ may be batched, durable before the window closes or before a

receipt citing it leaves

‘cache’ may be lost; rebuildable from elsewhere

It is declared, not yet enforced: on SQLite every write is already a commit, so the classes describe the contract a networked backend will have to honour. I15 is the defect that exists because this was never named - see docs/audit-2026-10-07-4-issues.md.

class fleetmesh_node.storage.base.StoreLease[source]

Bases: TypedDict

The lease as meshnode health reports it.

A named record rather than a loose mapping, because check-dicts.py holds this tree to typing what it returns, and a row an operator reads by field name is exactly the case that rule exists for.

owner: str
expires_at: int
mine: bool
expires_in: int
exception fleetmesh_node.storage.base.StoreOwnedError[source]

Bases: RuntimeError

Another node holds a live lease on this database.

Raised by open() rather than letting two nodes write one database. One node per database is a decision (docs/storage-backends.md header), and it is a decision a connection string can break where a file could not: meters is keyed (peer, epoch, side) and grants (peer, direction), and neither includes the node, so two nodes would interleave rows, read each other’s accounting as their own, and price windows that never happened with nothing in the schema complaining.

class fleetmesh_node.storage.base.BaseStore[source]

Bases: object

Thread-safe persistence with a declarative schema, over any dialect.

MIGRATIONS: tuple[Migration | tuple[int, str], ...] = ()
DURABILITY: str = 'commit'
__init__(path=':memory:', timeout=5.0, dialect=None, owner=None, lease_seconds=900, clock=None, readonly=False, schema=None)[source]
Parameters:
Return type:

None

path: str
dialect: Dialect
owner: str | None
lease_seconds: int
clock: Callable[[], int]
readonly: bool
SCHEMA: tuple[Any, ...] = ()
db: Any
renew_lease()[source]

Push the lease out. The tick calls this; a node that stops renewing releases the database to its successor once the lease runs out.

Return type:

None

lease()[source]

The lease as health should report it, or None when none is held.

Return type:

StoreLease | None

property safe_path: str

path with any credentials removed, for a message or a log.

A SQLite target is a filename and comes back unchanged. A server target is a connection string and carries a password, so anything an operator reads - a refusal, a log line, a health block - must use this and not path. The lease refusal below is the case that found it: it is the one message a misconfigured fleet is guaranteed to produce, and it printed the whole URL.

schema_name()[source]

How this store identifies itself to the dialect’s version table.

One node per database means all fourteen stores share one database on a server backend, where a single version row would make their separate migration series collide.

Return type:

str

user_version()[source]

This store’s stored schema version (0 if it never migrated).

Return type:

int

integrity_check()[source]

None if the database is sound, else what is wrong with it.

Return type:

str | None

vacuum(pages=50)[source]

Reclaim freed space and refresh planner statistics, per the dialect.

Parameters:

pages (int)

Return type:

int

close()[source]

Safely close the underlying database connection.

Return type:

None

execute(q, args=())[source]

Execute a single statement and return the cursor within the locked context.

Parameters:
Return type:

Any

executescript(script)[source]

Execute multiple SQL statements and commit.

Parameters:

script (str)

Return type:

None

commit()[source]

Commit active transaction under lock.

Return type:

None

transaction()[source]

Atomic block: commit on success, rollback on exception.

The retry a serializable backend would need belongs here and nowhere else, which is what keeps CockroachDB a later addition rather than a rewrite (docs/storage-backends.md section 5). None is built: SQLite never raises a retryable error, and neither does a Postgres backend that keeps this one-connection-behind-one-lock shape.

Return type:

Iterator[Any]

has_table(table_name)[source]

Return True if the specified table exists in the database.

Parameters:

table_name (str)

Return type:

bool

has_column(table_name, column_name)[source]

Return True if the column exists in the table schema.

Parameters:
  • table_name (str)

  • column_name (str)

Return type:

bool

5.2. PostgreSQL Backend

PostgreSQL, as an option beside the SQLite default.

Optional in the convention this repo already uses for wasmtime: the driver is imported lazily, a node without it still starts and serves, and a postgres:// URL is refused by name rather than failing at import. CI sets FLEETMESH_REQUIRE_POSTGRES=1 so a missing driver cannot turn a suite green by skipping.

The thirteen stores write SQLite’s dialect, which is the house dialect, and sql() here renders it into PostgreSQL’s. The census that says this is a short list rather than a rewrite is docs/storage-backends.md section 4; what it actually comes to:

placeholders ? -> %s, outside string literals upserts INSERT OR REPLACE -> ON CONFLICT (pk) DO UPDATE SET …

INSERT OR IGNORE -> ON CONFLICT DO NOTHING

types nothing to do. The node’s DDL uses TEXT and INTEGER and

nothing else across all 44 tables, and both are PostgreSQL types.

WITHOUT ROWID dropped; it is a SQLite storage hint. PRAGMA never reaches here; tune sets what a server needs instead.

The conflict target comes from the table’s own DDL. Every CREATE TABLE in the tree passes through sql() during _ensure_schema, before any INSERT can, so the dialect learns each table’s columns and primary key on the way past and has them when an upsert arrives. All 44 tables declare a primary key, so DO UPDATE always has a target - checked, not assumed.

One connection behind one lock, the shape BaseStore already had. That is what makes this backend need no retry policy: with a single writer there is nothing to serialize against, so no transaction is ever told to retry.

class fleetmesh_node.storage.postgres.PostgresDialect[source]

Bases: object

PostgreSQL. Learns each table’s shape from the DDL it renders.

name: str = 'postgres'
rowid_expr: str | None = None
__init__()[source]
Return type:

None

connect(target, timeout, readonly=False)[source]
Parameters:
Return type:

Any

tune(db, target, lock)[source]

What a server needs in place of SQLite’s PRAGMAs: a statement timeout so a wedged query cannot hold the one connection for ever.

Parameters:
Return type:

None

learn_table(table)[source]
Parameters:

table (Any)

Return type:

None

sql(statement)[source]
Parameters:

statement (Any)

Return type:

str

begin(db)[source]
Parameters:

db (Any)

Return type:

None

commit(db)[source]
Parameters:

db (Any)

Return type:

None

rollback(db)[source]
Parameters:

db (Any)

Return type:

None

get_version(db, store)[source]

The schema version of ONE store, keyed by its name.

SQLite gets this for free: each store is its own file, so PRAGMA user_version is per store. Here all fourteen share one database, and a single version row made them collide - AccountStore wrote 2, GrantStore read 2, concluded its own migrations were applied and skipped the ALTER that adds grants.env_created_at. The table was then one column short of what its INSERT supplies, and the first write failed with “INSERT has more expressions than target columns”. Only a multi-store test on a server could find that; one store alone passes.

Parameters:
Return type:

int

set_version(db, store, version)[source]
Parameters:
Return type:

None

has_table(db, table)[source]
Parameters:
Return type:

bool

has_column(db, table, column)[source]
Parameters:
Return type:

bool

is_duplicate_column(exc)[source]
Parameters:

exc (BaseException)

Return type:

bool

vacuum(db, pages)[source]

ANALYZE, and nothing more. Postgres reclaims by autovacuum; a manual VACUUM here would block the one connection the node has, and pages has no meaning on a server. Returns 0 - nothing was reclaimed by this call, and saying otherwise would be a fake count.

Parameters:
Return type:

int

integrity_check(db)[source]

None. File integrity is a file-backed idea; a server answers for its own soundness and PRAGMA quick_check has no counterpart here.

Parameters:

db (Any)

Return type:

str | None

errors()[source]
Return type:

tuple[type[BaseException], …]

fleetmesh_node.storage.postgres.available()[source]
Return type:

bool

fleetmesh_node.storage.postgres.driver()[source]

psycopg, or a refusal naming the remedy rather than an ImportError.

Return type:

Any

fleetmesh_node.storage.postgres.placeholders(statement)[source]

? -> %s, leaving anything inside a single-quoted literal alone.

The node’s SQL carries literals like status=’verified’; a blind replace would corrupt one that happened to contain a question mark.

Parameters:

statement (str)

Return type:

str

5.3. Storage Adapter

The database adapter module: provides typed schema binding, query execution, transactions, and leases across database backends (SQLite, PostgreSQL, etc.).

Instantiated with the compartment into a database adapter module.

class fleetmesh_node.storage.adapter.DatabaseAdapter[source]

Bases: BaseStore

The database adapter module: binds a compartment’s declared SCHEMA to a database backend and provides query execution, transactions, and leases.

__init__(target=':memory:', schema=(), migrations=(), timeout=5.0, dialect=None, owner=None, lease_seconds=900, clock=None, readonly=False)[source]
Parameters:
Return type:

None

one(q, args=())[source]

Execute query and fetch one row, closing the cursor before returning.

Parameters:
Return type:

tuple[Any, …] | None

all(q, args=())[source]

Execute query and fetch all rows, closing the cursor before returning.

Parameters:
Return type:

list[tuple[Any, …]]

class fleetmesh_node.storage.adapter.SqliteAdapter[source]

Bases: DatabaseAdapter

SQLite database adapter module.

__init__(path=':memory:', schema=(), migrations=(), timeout=5.0, dialect=None, owner=None, lease_seconds=900, clock=None, readonly=False)[source]
Parameters:
Return type:

None

class fleetmesh_node.storage.adapter.PsqlAdapter[source]

Bases: DatabaseAdapter

PostgreSQL database adapter module.

__init__(url, schema=(), migrations=(), timeout=5.0, dialect=None, owner=None, lease_seconds=900, clock=None, readonly=False)[source]
Parameters:
Return type:

None

fleetmesh_node.storage.adapter.PostgresAdapter

alias of PsqlAdapter

fleetmesh_node.storage.adapter.create_adapter(backend=None, target=None, schema=(), migrations=(), **kw)[source]

Create a DatabaseAdapter for the specified backend or target.

Parameters:
Return type:

DatabaseAdapter

fleetmesh_node.storage.adapter.adapter_from_locator(locator, name, schema=(), migrations=(), **kw)[source]

Instantiate a DatabaseAdapter using the node’s storage Locator.

Parameters:
Return type:

DatabaseAdapter

5.4. Content & Blob Locator

Where each of the node’s stores lives, decided once from config.

Every store site in the tree reads the same two things: a directory and a logical name, joined into <directory>/<name>.sqlite. That join is the only reason the tree is tied to SQLite now that the dialect layer exists, so it is the thing to replace - not with a flag threaded through fourteen files, but with one object that answers “where does the store called grants live” and is built once from the node’s configuration.

loc = Locator.from_config(directory) # the default loc = Locator.from_config(directory, url=’postgresql://…’) store = loc.open(grants.GrantStore, ‘grants’)

On SQLite that is the same path the site computed before, so the default node is byte-for-byte unchanged. On PostgreSQL every store gets the same URL: one node per database is settled (docs/storage-backends.md section 10), the forty- four table names do not collide, and the schema version is already keyed by store name rather than by database - the defect that taught us so is recorded at postgres.py:218.

One dialect instance is shared by every store it opens. PostgresDialect learns each table’s columns and primary key from the DDL passing through sql(), so sharing means the reflection is learned once rather than fourteen times, and the methods that use a connection take it as an argument.

A backend is named by URL scheme, and an unknown one is refused by name rather than quietly becoming a filename.

class fleetmesh_node.storage.locator.StorageBackend[source]

Bases: _Backend

The backend as meshnode health reports it.

A named record rather than a loose mapping, for the same reason StoreLease is one: check-dicts.py holds this tree to typing what it returns, and a row an operator reads by field name is the case that rule exists for. Exactly one of directory and server is present - which one is the answer being reported.

directory: str
server: str
owner: str
backend: str
class fleetmesh_node.storage.locator.Locator[source]

Bases: object

The node’s storage target. Build it with from_config.

__init__(directory, dialect, url=None, owner=None)[source]
Parameters:
Return type:

None

directory: str
dialect: Dialect
url: str | None
owner: str | None
classmethod from_config(directory, url=None, owner=None)[source]

The locator a node’s config asks for.

No URL is the default and needs nothing of the operator. A URL names its backend by scheme; anything else is a configuration error and is reported as one, because treating it as a path would produce a node that silently ran on SQLite while an operator believed otherwise.

owner is the node’s identity for the ownership lease. It is what makes one node per database enforced rather than assumed (docs/storage-backends.md section 5a): BaseStore claims a lease only when it is given an owner, so a locator without one opens stores that claim nothing. On a server every store shares the database and therefore shares the one fleetmesh_owner row, so the first store to open claims the database for this node and a second node is refused.

Parameters:
  • directory (str)

  • url (str | None)

  • owner (str | None)

Return type:

Locator

target(name)[source]

The connection target for the store called name.

A file per store on SQLite. One database for all of them on a server, which is what “one node per database” means.

Parameters:

name (str)

Return type:

str

open(store_cls, name, **kw)[source]

Construct a store of store_cls where name belongs.

kw is passed through untouched, so a store with its own arguments - ttl_seconds, readonly - keeps them, and a caller naming owner itself wins over the locator’s.

Parameters:
Return type:

Any

describe()[source]

The backend, for meshnode health.

Which backend is live is otherwise invisible until something breaks, and a node believed to be on PostgreSQL while running on SQLite is exactly the failure this reports. The URL is reduced to host and database: a connection string carries a password.

Return type:

StorageBackend

fleetmesh_node.storage.locator.redact(url)[source]

postgresql://user:pw@host:5432/db -> host:5432/db.

A password in a connection string must not reach a log, a health block or a receipt, and the part an operator needs to recognise the server is the part after the credentials.

Parameters:

url (str)

Return type:

str

5.5. Peer Grant Index

Grants on disk: the ones this node issued and the ones it holds.

One SQLite table, one row per (peer, direction). The payload is the grant as decrypted or as written, the envelope id is the kind 30801 that committed to it, and status is live or revoked. A node that restarts must know exactly what it granted and what it was granted, or its receipts are fiction.

Two more tables came from the two-machine run. history keeps every grant a pair has been under and the epoch from which it governed, because a window is priced under the grant that governed it and not under whatever grant happens to be current when the grace period ends. pending holds the grant a window evaluation decided on until the next window boundary, because a grant that changes mid-window changes what a receipt in flight means: the issuer was rejecting every receipt naming the grant it had just replaced, and the subject was restarting its chain at seq 0 on the grant it had just taken up, so every amend filed an S2 misreport against an honest node. An amend now takes effect at a boundary, as the specification’s grant loop says: the verdict on one window shapes “the next window’s grant”.

class fleetmesh_node.storage.grants.GrantStore[source]

Bases: BaseSqliteStore

SCHEMA: tuple[Any, ...] = (Table(name='grants', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='direction', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='envelope_id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='payload', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='tier', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='status', type='TEXT', nullable=False, primary_key=False, default="'live'", unique=False), Column(name='updated_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('peer', 'direction'), indices=(), without_rowid=False), Table(name='history', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='direction', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='envelope_id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='payload', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='effective_epoch', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='put_at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('peer', 'direction', 'envelope_id'), indices=(), without_rowid=False), Table(name='pending', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='payload', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='note', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='severity', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='decided_epoch', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='seeds', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='tier', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False))
MIGRATIONS: tuple[Migration | tuple[int, str], ...] = (Migration(version=1, up=('ALTER TABLE grants ADD COLUMN env_created_at INTEGER',), down=None, name='grants_env_created_at'), Migration(version=2, up=('ALTER TABLE history ADD COLUMN event TEXT',), down=None, name='history_event'), Migration(version=3, up=('ALTER TABLE history ADD COLUMN seq INTEGER NOT NULL DEFAULT 0',), down=None, name='history_seq'))
put(peer, direction, payload, envelope_id, now=None, env_created_at=None, effective_epoch=None, event=None)[source]

Record a grant. effective_epoch is the first window it governs; a caller that does not say gets the window now falls in.

Parameters:
Return type:

None

governing(peer, direction, epoch)[source]

The grant that governed one window: the latest one effective at or before it. Two written in the same second tie on put_at, so insertion order breaks the tie: a grant is only superseded forwards. Falls back to the current row, so a store that predates the history still answers.

Parameters:
  • peer (str)

  • direction (Literal['issued', 'received'])

  • epoch (int)

Return type:

GoverningRow | None

envelope_event(peer, direction, envelope_id, as_json=False)[source]

The signed kind 30801 this node held under that id, if it kept one.

Parameters:
  • peer (str)

  • direction (Literal['issued', 'received'])

  • envelope_id (str)

  • as_json (bool)

Return type:

Any

known_envelopes(peer, direction)[source]
Parameters:
  • peer (str)

  • direction (Literal['issued', 'received'])

Return type:

list[str]

put_pending(peer, payload, note, severity, decided_epoch)[source]
Parameters:
Return type:

None

pending(peer)[source]
Parameters:

peer (str)

Return type:

PendingRow | None

clear_pending(peer)[source]
Parameters:

peer (str)

Return type:

None

seed_applied(peer)[source]
Parameters:

peer (str)

Return type:

tuple[str, int] | None

put_seed(peer, tier, at)[source]
Parameters:
Return type:

None

get(peer, direction)[source]
Parameters:
  • peer (str)

  • direction (Literal['issued', 'received'])

Return type:

GrantRow | None

history(peer, direction)[source]

Every grant that has governed a window with this peer, oldest first.

Here because grant_view in app.py used to read it straight off the connection, without the lock, from the control socket’s thread while the tick and the sync threads were writing. windows_view beside it took the account store’s lock, so the rule was known and this one call was missed. A store that hands out its connection cannot enforce anything about how it is used.

Parameters:
  • peer (str)

  • direction (Literal['issued', 'received'])

Return type:

list[HistoryRow]

list(direction=None)[source]
Parameters:

direction (Literal['issued', 'received'] | None)

Return type:

list[GrantListRow]

zero(peer, now=None)[source]

Both directions to zero and revoked: a terminate or a revocation.

Parameters:
Return type:

None

peers()[source]
Return type:

list[str]

5.6. Account Ledgers

What a node must not forget when it restarts: its accounting.

Grants and events were on disk from the start. The meters, the receipts a node has received, and the chain state of the receipts it sends were not: they lived in memory, and a restart lost them. That is not a lost convenience, it is a correctness bug, and a two-machine run is what showed its shape.

A receipt chain is seq and prev, and the issuer checks both. A subject that restarts mid-window begins again at seq 0 with a zero prev, while the issuer is still expecting seq N chained onto what it last held. The issuer reads that as a broken chain and files an S2 misreport. Its counters are cumulative within a window, too, so the restarted subject also reports fewer than it did before, which is a counter going backwards: the second half of the same finding. An honest node that was restarted is priced exactly as a liar.

So the accounting is persisted here, in the node’s own directory, beside the grants it already kept.

class fleetmesh_node.storage.accounts.AccountStore[source]

Bases: BaseSqliteStore

SCHEMA: tuple[Any, ...] = (Table(name='meters', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='epoch', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='side', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='counters', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('peer', 'epoch', 'side'), indices=(), without_rowid=False), Table(name='receipts', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='epoch', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='seq', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='body', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('peer', 'epoch', 'seq'), indices=(), without_rowid=False), Table(name='chain', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='epoch', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='state', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('peer', 'epoch'), indices=(), without_rowid=False), Table(name='evaluated', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='epoch', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='severity', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('peer', 'epoch'), indices=(), without_rowid=False), Table(name='findings', columns=(Column(name='fid', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='peer', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='epoch', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='body', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='seen_wraps', columns=(Column(name='wid', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='awaiting_acks', columns=(Column(name='mid', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='peer', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='type', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='relays', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='reports_seen', columns=(Column(name='reporter', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='report_id', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='contradicted', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('reporter', 'report_id'), indices=(), without_rowid=False), Table(name='strain', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='shard', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='transport', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='kind', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='n', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False), Column(name='last_at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('peer', 'shard', 'transport', 'kind'), indices=(), without_rowid=False), Table(name='handovers', columns=(Column(name='shard', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='frm', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='body', type='TEXT', nullable=True, primary_key=False, default=None, unique=False), Column(name='at', type='INTEGER', nullable=True, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False))
MIGRATIONS: tuple[Migration | tuple[int, str], ...] = (Migration(version=1, up=('ALTER TABLE evaluated ADD COLUMN tier TEXT',), down=None, name='evaluated_tier'),)
put_meter(peer, epoch, side, counters, now=None)[source]
Parameters:
Return type:

None

put_receipt(peer, epoch, body)[source]
Parameters:
Return type:

None

put_chain(peer, epoch, state)[source]

An OutChain, as its to_dict renders it; chains() hands the mapping back for from_dict.

Parameters:
Return type:

None

put_finding(fid, peer, epoch, body)[source]

A reporter Finding, as its to_dict renders it; findings() hands the mapping back for from_dict.

Parameters:
Return type:

None

drop_finding(fid)[source]
Parameters:

fid (str)

Return type:

None

findings()[source]

Every pending finding, oldest opened first.

Return type:

list[FindingDict]

seen_wrap(wid)[source]
Parameters:

wid (str)

Return type:

bool

put_seen_wrap(wid, at)[source]
Parameters:
Return type:

None

put_awaiting(mid, peer, mtype, at, relays)[source]
Parameters:
Return type:

None

drop_awaiting(mid)[source]
Parameters:

mid (str)

Return type:

None

awaiting()[source]
Return type:

list[tuple[str, str, str, int, list[str]]]

put_report_seen(reporter, report_id, contradicted)[source]
Parameters:
  • reporter (str)

  • report_id (str)

  • contradicted (bool)

Return type:

None

reports_seen()[source]
Return type:

list[tuple[str, str, bool]]

put_evaluated(peer, epoch, severity, tier=None)[source]
Parameters:
  • peer (str)

  • epoch (int)

  • severity (str | None)

  • tier (str | None)

Return type:

None

put_strain(peer, shard, transport, kind, at, n=1)[source]
Parameters:
Return type:

None

put_handover(shard, chain)[source]

The whole chain, ordered from the first-hand root. frm is the last link’s signer: the node that handed it to this one.

Parameters:
Return type:

None

drop_handover(shard)[source]
Parameters:

shard (str)

Return type:

None

handover(shard)[source]

The chain this node holds for a shard, root first, or None.

Parameters:

shard (str)

Return type:

list[HandoverLink] | None

handovers()[source]
Return type:

dict[str, list[HandoverLink]]

strain()[source]

[(peer, shard, transport, kind, n, last_at)] - everything survived.

Return type:

list[tuple[str, str, str, str, int, int]]

meters()[source]
Return type:

dict[str, dict[str, dict[int, dict[str, int]]]]

receipts()[source]
Return type:

dict[str, dict[int, list[ReceiptBody]]]

chains()[source]
Return type:

dict[str, dict[int, OutChainDict]]

evaluated()[source]
Return type:

set[tuple[str, int]]

evaluations()[source]

(peer, epoch, severity) in window order, severity None for a window that was not evaluated. The standing ledger is rebuilt from this on a restart: it lived in memory, so every streak began again at zero.

Return type:

list[tuple[str, int, str | None, str | None]]

forget_before(epoch)[source]

Windows old enough that nothing can still be said about them.

A closed window that has been evaluated is history; keeping every one forever would grow without bound on a node that never restarts.

Parameters:

epoch (int)

Return type:

None

5.7. Dialect Abstraction

What differs between one SQL backend and another, and nothing else.

The thirteen stores on BaseStore declare their schema and write ordinary SQL. Almost all of it is portable; this module holds the parts that are not, so that a second backend is one class here rather than edits at 152 execute sites. The census behind that number, and why the list is this short, is docs/storage-backends.md section 4.

A dialect owns:

connect/tune opening the connection and the per-backend setup that

follows it (SQLite’s PRAGMAs, and nothing on a server)

sql() rendering a statement written in the house dialect -

? placeholders and INSERT OR REPLACE/IGNORE - into what this backend accepts. SQLite’s is identity, which is what makes the split provably behaviour-preserving.

schema version read and write it (SQLite: PRAGMA user_version) reflection has_table / has_column errors is_duplicate_column, so a migration that was already

applied is recognised without matching a message string at the call site

maintenance vacuum, which means different things per backend

Nothing here knows what a meter or a grant is.

fleetmesh_node.storage.dialect.ensure_incremental_vacuum(db, path, max_bytes=268435456)[source]

One-off migration of a pre-existing auto_vacuum=NONE database.

PRAGMA auto_vacuum only takes effect on an empty database; on one created before incremental vacuum was introduced it is silently ignored, and incremental_vacuum() then reclaims nothing forever. Switching needs a full VACUUM, which rewrites the file once. Done at open, before other writers, and skipped above max_bytes (override FLEETMESH_VACUUM_MIGRATE_MAX_BYTES) so a very large store is never blocked at startup - operators run VACUUM by hand there. Returns True if the database was converted.

Parameters:
Return type:

bool

class fleetmesh_node.storage.dialect.Dialect[source]

Bases: Protocol

The backend-specific half of a store. One implementation per backend.

name: str
rowid_expr: str | None
connect(target, timeout, readonly=False)[source]
Parameters:
Return type:

Any

tune(db, target, lock)[source]
Parameters:
Return type:

None

sql(statement)[source]
Parameters:

statement (str)

Return type:

str

begin(db)[source]
Parameters:

db (Any)

Return type:

None

commit(db)[source]
Parameters:

db (Any)

Return type:

None

rollback(db)[source]
Parameters:

db (Any)

Return type:

None

get_version(db, store)[source]
Parameters:
Return type:

int

set_version(db, store, version)[source]
Parameters:
Return type:

None

has_table(db, table)[source]
Parameters:
Return type:

bool

has_column(db, table, column)[source]
Parameters:
Return type:

bool

is_duplicate_column(exc)[source]
Parameters:

exc (BaseException)

Return type:

bool

vacuum(db, pages)[source]
Parameters:
Return type:

int

integrity_check(db)[source]
Parameters:

db (Any)

Return type:

str | None

learn_table(table)[source]
Parameters:

table (Any)

Return type:

None

errors()[source]
Return type:

tuple[type[BaseException], …]

__init__(*args, **kwargs)
class fleetmesh_node.storage.dialect.SqliteDialect[source]

Bases: object

SQLite, which is the default and the only backend that needs no operator.

sql() is the identity function: the house dialect is SQLite’s, so the extraction of BaseStore from BaseSqliteStore cannot change a statement. A second dialect is where the translation lives.

name: str = 'sqlite'
rowid_expr: str | None = 'rowid'
learn_table(table)[source]

SQLite requires no reflection for upsert queries.

Parameters:

table (Any)

Return type:

None

connect(target, timeout, readonly=False)[source]
Parameters:
Return type:

Connection

tune(db, target, lock)[source]

Apply high-concurrency PRAGMAs while holding the lock.

Parameters:
Return type:

None

sql(statement)[source]
Parameters:

statement (str)

Return type:

str

begin(db)[source]
Parameters:

db (Connection)

Return type:

None

commit(db)[source]
Parameters:

db (Connection)

Return type:

None

rollback(db)[source]
Parameters:

db (Connection)

Return type:

None

get_version(db, store)[source]
Parameters:
Return type:

int

set_version(db, store, version)[source]
Parameters:
Return type:

None

has_table(db, table)[source]
Parameters:
Return type:

bool

has_column(db, table, column)[source]
Parameters:
Return type:

bool

is_duplicate_column(exc)[source]
Parameters:

exc (BaseException)

Return type:

bool

vacuum(db, pages)[source]

Incremental vacuum to reclaim freed pages, and optimize the planner.

Parameters:
Return type:

int

integrity_check(db)[source]

None if the database is sound, else what is wrong with it.

PRAGMA quick_check is SQLite’s, and a file-integrity check is a file-backed idea: a server backend answers for its own soundness and returns None here rather than pretending to run this.

Parameters:

db (Connection)

Return type:

str | None

errors()[source]
Return type:

tuple[type[BaseException], …]