3.1.5. Store Plane (fleetmesh_node.planes.store)

The Store Plane is responsible for content-addressed storage, range-based set reconciliation, retention pruning, and chunked blob streaming.

3.1.5.1. Sync (Negentropy) Compartment

The SyncPeer compartment: construction, the metered send/receive every role shares, the session table, and the compartment contract. The roles are in initiator.py / responder.py; the handover in handover.py.

class fleetmesh_node.planes.store.sync.core.SyncConfig[source]

Bases: ParamBlock

SyncConfig(DERIVED: ‘bool’ = False, sessions_ceiling: ‘int’ = 1024, recent_kept: ‘int’ = 256)

key: ClassVar[str] = 'sync'
name = 'sync'
DERIVED: bool = False
PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='sessions_ceiling', name='Sessions Ceiling', description='Maximum concurrent open sync sessions answered', type=<class 'int'>, default=1024, must='', tags=('sync', 'concurrency'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=1, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='recent_kept', name='Recent Kept', description='Number of recent completed or refused sessions kept', type=<class 'int'>, default=256, must='', tags=('sync', 'history'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=10, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True))
sessions_ceiling: int = 1024
recent_kept: int = 256
__init__(DERIVED=False, sessions_ceiling=1024, recent_kept=256)
Parameters:
  • DERIVED (bool)

  • sessions_ceiling (int)

  • recent_kept (int)

Return type:

None

class fleetmesh_node.planes.store.sync.core.SyncPeer[source]

Bases: InitiatorMixin, ResponderMixin, HandoverMixin, WireProtocol

Both roles of sync/1.0 for one node, as a compartment.

Its refusals are the sessions it would not open - a grant that does not cover one, a peer with too many already, a node over its own ceiling - and the deliveries it would not store. Those lived in three separate lists that only the CLI knew how to read.

name: str = 'sync'
requires: tuple[str, ...] = ('budget', 'strain')
piuris: tuple[str, ...] = ('https://fleetmesh.org/sync/1.0',)
reads: tuple[str, ...] = ('handover', 'coverage')
config_cls

alias of SyncConfig

live: tuple[str, ...] = ('handover',)
CHANNELS: tuple[Any, ...] = (Channel(name='handed', description='Handover signed and offered to peer', level='info', wire=None, say='handed {shard} to {peer} ({events} events)', tags=()), Channel(name='held', description='Handover accepted from peer', level='info', wire=None, say='held {shard} handed over by {peer} ({events} events, {chain_len} in the chain)', tags=()))
METRICS: tuple[Any, ...] = (Metric(name='sync_handovers_offered', description='Times shard coverage was handed over.', kind='counter', unit='', labels=(), counts='handed', sample=None, buckets=(), tags=('sync', 'handover')), Metric(name='sync_handovers_accepted', description='Times shard coverage was accepted.', kind='counter', unit='', labels=(), counts='held', sample=None, buckets=(), tags=('sync', 'handover')))
HANDLERS: tuple[Handler, ...] = (Handler(kind='open', run='handle_open', schema=None, doc='answer inbound sync/1.0 open session request', exact=False, reads=(), writes=()), Handler(kind='handover', run='handle_handover', schema=None, doc='accept inbound sync/1.0 handover envelope', exact=False, reads=(), writes=()), Handler(kind='range', run='handle_range', schema=None, doc='answer inbound sync/1.0 range request', exact=False, reads=(), writes=()), Handler(kind='need', run='handle_need', schema=None, doc='answer inbound sync/1.0 need request', exact=False, reads=(), writes=()), Handler(kind='done', run='handle_done', schema=None, doc='answer inbound sync/1.0 done session finish', exact=False, reads=(), writes=()))
OUTBOUND: tuple[Outbound, ...] = (Outbound('open', reply=('range', 'deliver', 'done')), Outbound('range', reply=('range', 'have', 'need', 'deliver', 'done')), Outbound('have', reply=('need', 'done')), Outbound('need', reply=('deliver', 'done')), Outbound('deliver', reply=('range', 'need', 'done')), Outbound('done'), Outbound('handover'))
COMMANDS: tuple[Any, ...] = (Command(key='show', name='Sync', description='sessions open, refused and aborted, and what could not be sent', tags=('sync', 'status'), parameters=(), permission='sync/show', process=(), run='state', reply='{open, refused, aborted, completed, unsent, malformed, handed, held}', reads=(), writes=()),)
STORES: tuple[Store, ...] = (Store(key='totals', description='sessions since the process started, by how they ended', kind='counters', shape=<class 'fleetmesh_node.planes.store.sync.types.SyncTotals'>, bound=0, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='aborted', description='sessions a peer stopped answering, as (peer, thid), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='refused', description='sessions this node would not open, as (peer, thid, why), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='completed', description='sessions that ended, as (peer, role, result), newest last', kind='ring', shape=<class 'tuple'>, bound=256, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='rejected', description='messages without the shape of their type, as (peer, kind, why), newest last', kind='ring', shape=<class 'tuple'>, bound=200, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='unsent', description='messages no relay would take, as (peer, type, why, at), newest last', kind='ring', shape=<class 'tuple'>, bound=200, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='handed', description='handovers this node signed and sent, as (peer, shard, fingerprint, at), newest last', kind='ring', shape=<class 'tuple'>, bound=200, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='held', description='handovers this node accepted, as (peer, shard, at), newest last', kind='ring', shape=<class 'tuple'>, bound=200, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()), Store(key='sessions', description='sessions this node is answering, with when each last moved', kind='table', shape=<class 'tuple'>, bound=1024, evict='refuse', keyed_by='thid', persist='memory', sensitive=False, tags=()), Store(key='_initiated', description='sessions this node opened, by thid', kind='set', shape=<class 'str'>, bound=4096, evict='oldest', keyed_by='thid', persist='memory', sensitive=False, tags=()), Store(key='_offered', description='the fingerprint last handed over, per peer and shard', kind='table', shape=<class 'str'>, bound=4096, evict='oldest', keyed_by='peer and shard', persist='memory', sensitive=False, tags=()))
NEEDS: tuple[Any, ...] = (Need(key='keystore', source='ks', block=None, late=False, getter=False, path=None, field=None), Need(key='my_store', source='stores.events', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='grant_store', source='stores.grants', block=None, late=False, getter=False, path=None, field=None), Need(key='budget', source='budget', block=None, late=False, getter=False, path=None, field=None), Need(key='session_cls', source='cfg', block=None, late=False, getter=False, path=None, field='_session_cls'), Need(key='strain', source='strain', block=None, late=False, getter=False, path=None, field=None), Need(key='accounts', source='stores.accounts', block=None, late=False, getter=False, path=None, field=None), Need(key='events', source='events', block=None, late=False, getter=False, path=None, field=None), Need(key='discovery', source='discovery', block=None, late=True, getter=False, path=None, field=None), Need(key='presence', source='presence', block=None, late=True, getter=False, path=None, field=None), Need(key='reporter', source='reporter', block=None, late=True, getter=False, path=None, field=None))
bind(discovery=None, presence=None)[source]

The two soft dependencies that tick after sync: discovery holds the coverage claims a handover rests on, presence says whether a peer that went quiet had announced it was leaving. Both are built after sync, so they are bound once all three exist; either may stay None (a bare SyncPeer in a suite), and the handover and partition paths check for that.

Parameters:
  • discovery (Any)

  • presence (Any)

Return type:

None

start()[source]

Everything that needs the rest of the node to exist already.

Return type:

None

__init__(keystore, my_store, transport, grant_store, clock=None, budget=None, session_cls=None, strain=None, node=None, accounts=None, events=None, discovery=None, presence=None, reporter=None)[source]
Parameters:
  • keystore (Any)

  • my_store (Any)

  • transport (Any)

  • grant_store (Any)

  • clock (Callable[[], int] | None)

  • budget (Any | None)

  • session_cls (Any | None)

  • strain (Any | None)

  • node (Any | None)

  • accounts (Any | None)

  • events (Any | None)

  • discovery (Any | None)

  • presence (Any | None)

  • reporter (Any | None)

Return type:

None

strain: Any | None
accounts: Any | None
session_cls: Any
ks: Any
store: Any
transport: Any
grants: Any
budget: Any | None
on_session: list[Callable[[str, str, SyncSessionResult], Any]]
totals: Counters
aborted: Ring[tuple[str, str]]
refused: Ring[tuple[str, str | None, str]]
sessions: Table[str, tuple[str, Any, int]]
rejected: Ring[tuple[str, str, str]]
unsent: Ring[tuple[str, str, str, int]]
completed: Ring[tuple[str, str, SyncSessionResult]]
handed: Ring[tuple[str, str, str, int]]
held: Ring[tuple[str, str, int]]
state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

SyncStateReport

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'sessions open, refused and aborted, and what could not be sent', 'reply': '{open, refused, aborted, completed, unsent, malformed, handed, held}', 'subsystem': 'sync'}}

3.1.5.2. Retention & Pruning Compartment

What this node stops keeping, and the one thing it must never stop keeping.

An open relay face collects what an open face invites. On the alpha mesh one node was holding 6,025 events to every other node’s 38, of which 5,625 were NIP-59 gift wraps between strangers using it as an ordinary DM relay - about 5,200 arriving a day, 62 MB and climbing, on a box with 113 MB of memory free. Nothing bounded it: NIP-40 expiry is enforced when an event is read and never on disk, and only 68 of those 6,025 carried an expiration tag at all, so leaning on other people’s compliance would have reclaimed nothing.

So retention is the operator’s, stated per kind, and the default keeps everything. A relay that quietly began deleting what it was handed would be a worse thing than one that fills up, and the specification prices retrieval rather than retention precisely because a standing promise to hold something is the one product this protocol declines to sell. Nothing here is protocol. It is a disk, and whose disk it is decides.

The guard is the part that is not a preference. A kind 30803 coverage claim names a shard as a filter and carries a negentropy fingerprint over the set; evicting an event inside a claimed shard would leave this node advertising a fingerprint it can no longer reproduce, and a peer reconciling against it would find the difference and be right. So an event matching any shard this node claims is never evicted, whatever the operator asked for, and the refusal is recorded rather than performed silently.

class fleetmesh_node.planes.store.retention.compartment.RetentionConfig[source]

Bases: ParamBlock

RetentionConfig(DERIVED: ‘bool’ = False, sweep_seconds: ‘int’ = 3600, sweep_page: ‘int’ = 500)

key: ClassVar[str] = 'retention'
name = 'retention'
DERIVED: bool = False
PARAMS: tuple[Parameter[Any], ...] = (Parameter(key='sweep_seconds', name='Sweep Cadence', description='Seconds between retention sweeps', type=<class 'int'>, default=3600, must='', tags=('retention', 'sweep'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='sweep_page', name='Sweep Page Size', description='Number of events examined per sweep page', type=<class 'int'>, default=500, must='', tags=('retention', 'sweep'), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True))
sweep_seconds: int = 3600
sweep_page: int = 500
__init__(DERIVED=False, sweep_seconds=3600, sweep_page=500)
Parameters:
  • DERIVED (bool)

  • sweep_seconds (int)

  • sweep_page (int)

Return type:

None

class fleetmesh_node.planes.store.retention.compartment.Retention[source]

Bases: Compartment

Per-kind ages, swept on a slow cadence, with the shards held back.

name: str | None = 'retention'
reads: tuple[str, ...] = ('retention', 'coverage')
live: tuple[str, ...] = ()
config_cls

alias of RetentionConfig

CHANNELS: tuple[Any, ...] = (Channel(name='events_evicted', description='Expired events evicted during sweep', level='note', wire=None, say='retention sweep evicted {count} expired events', tags=('retention', 'sweep')), Channel(name='eviction_refused', description='Event eviction refused because it matches a claimed shard', level='note', wire=None, say='retention eviction refused for event {id}', tags=('retention', 'sweep')))
METRICS: tuple[Any, ...] = (Metric(name='retention_events_evicted', description='Times expired events were evicted.', kind='counter', unit='', labels=(), counts='events_evicted', sample=None, buckets=(), tags=('retention', 'sweep')), Metric(name='retention_evictions_refused', description='Times evictions were refused.', kind='counter', unit='', labels=(), counts='eviction_refused', sample=None, buckets=(), tags=('retention', 'sweep')))
NEEDS: tuple[Any, ...] = (Need(key='store', source='stores.events', block=None, late=False, getter=False, path=None, field=None), Need(key='cfg', source='cfg', block=None, late=False, getter=True, path=None, field=None))
EVERY: tuple[Any, ...] = (Every(seconds=3600, run='sweep', name='sweep', report=None),)
COMMANDS: tuple[Any, ...] = (Command(key='show', name='Retention', description='the ages this operator set, what they protect, and what has been evicted', tags=('retention', 'status'), parameters=(), permission='retention/show', process=(), run='state', reply='{ages, protected, swept_at, evicted, held_back}', reads=(), writes=()), Command(key='sweep', name='Retention sweep', description='run the sweep now rather than waiting for the cadence', tags=('retention',), parameters=(), permission='retention/sweep', process=(), run='sweep', reply='{evicted: {kind: n}, held_back: n, scanned: n}', reads=(), writes=()))
STORES: tuple[Store, ...] = (Store(key='evicted', description='total ever evicted, per event kind', kind='table', shape=<class 'int'>, bound=1024, evict='lru', keyed_by='kind', persist='memory', sensitive=False, tags=()),)
__init__(store, cfg, clock, node=None)[source]
Parameters:
Return type:

None

swept_at: int | None
evicted: Table[int, int]
held_back: int
ages()[source]

{kind: seconds}. Absent, empty or unreadable all mean keep everything.

Return type:

dict[int, int]

protected()[source]

The shard filters a coverage claim or ProjectedNodeStore covers. Never evicted.

Return type:

list[Mapping[str, Any]]

sweep(now=None)[source]
Parameters:

now (int | None)

Return type:

Mapping[str, Any]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

RetentionStateReport

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'show': {'args': {}, 'does': 'the ages this operator set, what they protect, and what has been evicted', 'reply': '{ages, protected, swept_at, evicted, held_back}', 'subsystem': 'retention'}, 'sweep': {'args': {}, 'does': 'run the sweep now rather than waiting for the cadence', 'reply': '{evicted: {kind: n}, held_back: n, scanned: n}', 'subsystem': 'retention'}}

3.1.5.3. Blob Wire Streaming Compartment

The blob_wire compartment: serve pulls for what this node holds, take offers within the operator’s caps, drop replicas when the grant ends.

class fleetmesh_node.planes.store.blob_wire.core.BlobWire[source]

Bases: WireProtocol

Answers have and pull for blobs this node holds; takes offers under policy.

name: str | None = 'blob_wire'
piuris: tuple[str, ...] = ('https://fleetmesh.org/blob/1.0',)
reads: tuple[str, ...] = ('blob_wire',)
config_cls

alias of BlobWireConfig

live: tuple[str, ...] = ()
SCHEMA: tuple[Any, ...] = (Table(name='replicas_in', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='size', type='INTEGER', 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=('sha256', 'peer'), indices=(Index(name='idx_replicas_in_peer', columns=('peer',), table='replicas_in', unique=False),), without_rowid=False), Table(name='intake_day', columns=(Column(name='peer', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='day', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='bytes', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=('peer', 'day'), indices=(), without_rowid=False))
STORE_CLS

alias of IntakeStore

CHANNELS: tuple[Any, ...] = (Channel(name='blob_served', description='Blob chunk or have served to peer', level='info', wire=None, say='blob chunk served to peer {peer}', tags=('blob', 'wire')), Channel(name='offer_refused', description='Blob offer refused under policy', level='trouble', wire=None, say='blob offer refused from peer {peer}: {reason}', tags=('blob', 'wire')))
METRICS: tuple[Any, ...] = (Metric(name='blob_wire_chunks_served', description='Times blob chunks were served.', kind='counter', unit='', labels=(), counts='blob_served', sample=None, buckets=(), tags=('blob', 'wire')), Metric(name='blob_wire_offers_refused', description='Times blob offers were refused.', kind='counter', unit='', labels=(), counts='offer_refused', sample=None, buckets=(), tags=('blob', 'wire')))
STORES: tuple[Store, ...] = (Store(key='_inflight', description='concurrent blob transfers per peer', kind='table', shape=<class 'int'>, bound=1024, evict='lru', keyed_by='peer', persist='memory', sensitive=False, tags=()),)
COMMANDS: tuple[Any, ...] = (Command(key='held', name='Held Replicas', description='replicas taken over the transport, per peer', tags=('blob_wire', 'held'), parameters=(Parameter(key='peer', name='peer', description='peer pubkey to filter by', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='blob_wire/held', process=(), run='cmd_held', reply='{peer: [{sha256, size, at}]}', reads=(), writes=()), Command(key='drop', name='Drop Peer Replicas', description='drop every replica held for a peer now', tags=('blob_wire', 'drop'), parameters=(Parameter(key='peer', name='peer', description='peer pubkey', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='blob_wire/drop', process=(), run='cmd_drop', reply='{peer, dropped}', reads=(), writes=()))
HANDLERS: tuple[Handler, ...] = (Handler(kind='have', run='handle_have', schema=None, doc='answer have with held hashes', exact=False, reads=('blobs',), writes=()), Handler(kind='pull', run='handle_pull', schema=None, doc='serve requested chunk of held blob', exact=False, reads=('blobs',), writes=()), Handler(kind='offer', run='handle_offer', schema=None, doc='evaluate offer and pull if accepted', exact=False, reads=(), writes=('blobs',)), Handler(kind='chunk', run='handle_chunk', schema=None, doc='handle unprompted chunk', exact=False, reads=(), writes=()), Handler(kind='refuse', run='handle_refuse', schema=None, doc='handle unprompted refuse', exact=False, reads=(), writes=()))
OUTBOUND: tuple[Outbound, ...] = (Outbound('have'), Outbound('offer', reply=('have', 'refuse')), Outbound('pull', reply=('chunk', 'refuse')), Outbound('chunk'), Outbound('refuse'))
REPLICAS_DB: str = 'blob_replicas.sqlite'
NEEDS: tuple[Any, ...] = (Need(key='blobs', source='stores.blobs', block=None, late=False, getter=False, path=None, field=None), Need(key='transport', source='transport', block=None, late=False, getter=False, path=None, field=None), Need(key='db_path', source=None, block=None, late=False, getter=False, path='REPLICAS_DB', field=None), Need(key='cfg', source='cfg', block=None, late=False, getter=True, path=None, field=None), Need(key='grants', source='stores.grants', block=None, late=False, getter=False, path=None, field=None))
__init__(blobs, transport, db_path, cfg, grantees=None, clock=None, node=None, grants=None)[source]
Parameters:
Return type:

None

rc()[source]

The operator’s blob_wire block as it is now; it reads live.

Return type:

BlobWireConfig

settings()[source]

This compartment’s own config block, typed, as the file says now.

config_cls names the Block; its key is read through config() so the read is counted against reads like any other. Parsed on each call, so a compartment that lists its key in live sees an edit without a restart; the others call it once at construction.

Return type:

BlobWireConfig

cap(name)[source]
Parameters:

name (str)

Return type:

int

chunk_bytes()[source]
Return type:

int

accepts(peer)[source]
Parameters:

peer (str)

Return type:

bool

why_not(peer, size, now)[source]

The first reason an offer from this peer may not be taken, or None.

Parameters:
Return type:

str | None

handle_have(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_pull(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_offer(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_chunk(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

handle_refuse(inbound, sender)[source]
Parameters:
Return type:

tuple[Any, …]

drop_peer(peer, now=None)[source]

Let go of every replica held for a peer: unpin, delete, forget.

Parameters:
Return type:

Mapping[str, Any]

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

Mapping[str, Any]

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

cmd_held(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

cmd_drop(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

Any

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'drop': {'args': {'peer': 'required'}, 'does': 'drop every replica held for a peer now', 'reply': '{peer, dropped}', 'subsystem': 'blob_wire'}, 'held': {'args': {'peer': 'optional'}, 'does': 'replicas taken over the transport, per peer', 'reply': '{peer: [{sha256, size, at}]}', 'subsystem': 'blob_wire'}}
fleetmesh_node.planes.store.blob_wire.core.partner_transport_peers(node)[source]

peer:<pk> for every grantee that has no Blossom URL in its descriptor.

Peers with an HTTP endpoint take the Blossom path; this is for the rest.

Parameters:

node (Any)

Return type:

list[str]

3.1.5.4. Blob Replication Compartment

Blossom replication: keep N copies of every pinned blob on other nodes.

Pinning keeps a blob off this node’s LRU eviction; it does nothing if this node’s disk dies. Replication is the other half. For each pinned blob the operator gives a target copy count, and on every tick this compartment:

  1. asks candidate servers without a copy to mirror it (BUD-04 PUT /mirror, signed kind 24242 by this node, source = this node’s public Blossom URL),

  2. re-checks held copies on a slow cadence with HEAD, and

  3. forgets a copy that has gone, so step 1 asks again - on another server if there is one.

Where copies go: servers from config blob_replication.servers, then every peer this node holds a live grant with that advertises an http(s)/ws(s) endpoint in its descriptor (a node’s face serves Blossom on the same port). A peering partner is who this node already trusts with its traffic; a stranger found on a relay is not asked to hold its data.

A partner with a grant but no http(s)/ws(s) endpoint - a node behind NAT - takes the second path: blob/1.0 over the peering transport (blob_wire.py). Such a candidate is named peer:<pubkey> and driven through the same mirror_blob/head_blob calls, so run() and verify() below do not know which path a copy took.

What it cannot do, and says so: a partner may accept a mirror and later drop it; this is found by the verify pass, not prevented. A node with no public URL (blob_replication.source_url, or a first http(s)/ws(s) endpoint) cannot be mirrored from over Blossom, and trouble reports that instead of failing silently; the transport path needs no URL.

State lives in SQLite beside the blob index (blob_replicas.sqlite).

class fleetmesh_node.planes.store.blob_replication.compartment.ReplicaStore[source]

Bases: BaseSqliteStore

SCHEMA: tuple[Any, ...] = (Table(name='wants', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='copies', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='since', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='replicas', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='server', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='state', 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), Column(name='why', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('sha256', 'server'), indices=(), without_rowid=False))
want(h, copies, now)[source]
Parameters:
Return type:

None

unwant(h)[source]
Parameters:

h (str)

Return type:

bool

wants()[source]
Return type:

list[tuple[str, int]]

copies(h)[source]
Parameters:

h (str)

Return type:

int

want_row(h)[source]
Parameters:

h (str)

Return type:

tuple[Any, …] | None

replicas(h)[source]
Parameters:

h (str)

Return type:

list[Mapping[str, Any]]

mark(h, server, state, now, why=None)[source]
Parameters:
Return type:

None

forget(h, server=None)[source]
Parameters:
Return type:

None

class fleetmesh_node.planes.store.blob_replication.compartment.Replication[source]

Bases: Compartment

requires: tuple[str, ...] = ('blob_wire',)

Keeps a target number of copies of each pinned blob on other servers.

name: str | None = 'blob_replication'
reads: tuple[str, ...] = ('blob_replication', 'endpoints')
config_cls

alias of BlobReplicationConfig

live: tuple[str, ...] = ()
REPLICAS_DB = 'blob_replicas.sqlite'
SCHEMA: tuple[Any, ...] = (Table(name='wants', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=True, default=None, unique=False), Column(name='copies', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False), Column(name='since', type='INTEGER', nullable=False, primary_key=False, default=None, unique=False)), primary_key=(), indices=(), without_rowid=False), Table(name='replicas', columns=(Column(name='sha256', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='server', type='TEXT', nullable=False, primary_key=False, default=None, unique=False), Column(name='state', 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), Column(name='why', type='TEXT', nullable=True, primary_key=False, default=None, unique=False)), primary_key=('sha256', 'server'), indices=(), without_rowid=False))
STORE_CLS

alias of ReplicaStore

STORES: tuple[Store, ...] = (Store(key='replicas', description='replicated blob records in sqlite', kind='ring', shape=<class 'dict'>, bound=1024, evict='oldest', keyed_by='', persist='memory', sensitive=False, tags=()),)
CHANNELS: tuple[Any, ...] = (Channel(name='blob_replicated', description='Blob successfully mirrored to remote partner', level='info', wire=None, say='blob {sha256} replicated to {server}', tags=('blob', 'replication')), Channel(name='replication_failed', description='Blob mirroring attempt failed', level='note', wire=None, say='blob {sha256} replication failed on {server}: {why}', tags=('blob', 'replication')))
METRICS: tuple[Any, ...] = (Metric(name='blob_replication_replicated', description='Times blobs were replicated.', kind='counter', unit='', labels=(), counts='blob_replicated', sample=None, buckets=(), tags=('blob', 'replication')), Metric(name='blob_replication_failed', description='Times blob replications failed.', kind='counter', unit='', labels=(), counts='replication_failed', sample=None, buckets=(), tags=('blob', 'replication')))
NEEDS: tuple[Any, ...] = (Need(key='blobs', source='stores.blobs', block=None, late=False, getter=False, path=None, field=None), Need(key='db_path', source=None, block=None, late=False, getter=False, path='REPLICAS_DB', field=None), Need(key='signer_sk', source='ks.node_sk', block=None, late=False, getter=False, path=None, field=None), Need(key='cfg', source='cfg', block=None, late=False, getter=True, path=None, field=None), Need(key='blob_wire', source='blob_wire', block=None, late=False, getter=False, path=None, field=None))
COMMANDS: tuple[Any, ...] = (Command(key='pin', name='Pin Blob', description='pin a blob here and keep that many copies of it on other servers', tags=('blob_replication', 'pin'), parameters=(Parameter(key='sha256', name='sha256', description='hex digest of blob', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True), Parameter(key='copies', name='copies', description='target copy count', type=<class 'int'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True)), permission='blob_replication/pin', process=(), run='pin_cmd', reply='{sha256, copies, pinned}', reads=(), writes=()), Command(key='unpin', name='Unpin Blob', description='stop replicating (and unpin) a blob; copies already made stay', tags=('blob_replication', 'unpin'), parameters=(Parameter(key='sha256', name='sha256', description='hex digest of blob', type=<class 'str'>, default='', must='', tags=(), required=True, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='blob_replication/unpin', process=(), run='unpin_cmd', reply='{sha256, unpinned}', reads=(), writes=()), Command(key='status', name='Replication Status', description='target and held copies, per blob', tags=('blob_replication', 'status'), parameters=(Parameter(key='sha256', name='sha256', description='hex digest of blob to query', type=<class 'str'>, default=None, must='', tags=(), required=False, choices=(), verify_regex='', live=False, item=None, field='', secret=False, requires='', sources=(), minimum=None, maximum=None, env='', validate=None, coerce=None, short='', cli_name='', positional=False, nargs='', cli=True),), permission='blob_replication/status', process=(), run='status_cmd', reply='[{sha256, copies, held, servers}]', reads=(), writes=()), Command(key='run', name='Run Replication', description='mirror under-replicated blobs now', tags=('blob_replication', 'run'), parameters=(), permission='blob_replication/run', process=(), run='run_cmd', reply='[(replication, ...)]', reads=(), writes=()), Command(key='verify', name='Verify Copies', description='re-check every held copy now', tags=('blob_replication', 'verify'), parameters=(), permission='blob_replication/verify', process=(), run='verify_cmd', reply='[(replication, ...)]', reads=(), writes=()))
EVERY: tuple[Any, ...] = (Every(seconds=21600, run='verify', name='replication_verify', report=None), Every(seconds=300, run='run', name='replication_run', report=None))
__init__(blobs, db_path, signer_sk, cfg, candidates=None, clock=None, client=None, node=None, transport_client=None, blob_wire=None)[source]
Parameters:
Return type:

None

last_run: int | None
last_verify: int | None
rc()[source]

The operator’s blob_replication block as it is now; it reads live.

Return type:

BlobReplicationConfig

settings()[source]

This compartment’s own config block, typed, as the file says now.

config_cls names the Block; its key is read through config() so the read is counted against reads like any other. Parsed on each call, so a compartment that lists its key in live sees an edit without a restart; the others call it once at construction.

Return type:

BlobReplicationConfig

default_copies()[source]
Return type:

int

allow_private()[source]

Address policy for partner Blossom servers.

Partner URLs come out of peer descriptors, so a peer could name a loopback or LAN address and make this node mirror into it. netfetch refuses that by default; an operator running a LAN cluster sets blob_replication.allow_private to true or to a list of hosts.

Return type:

Any

source_url()[source]

Where partners fetch from: this node’s own public Blossom base URL.

Return type:

str | None

servers()[source]
Return type:

list[str]

client_for(server)[source]
Parameters:

server (str)

Return type:

Any

pin(h, copies=None)[source]
Parameters:
Return type:

PinResult

unpin(h)[source]
Parameters:

h (str)

Return type:

UnpinResult

status(h=None)[source]
Parameters:

h (str | None)

Return type:

list[BlobReplicationStatus]

run(now=None)[source]

Ask servers to mirror every blob below its target copy count.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

verify(now=None)[source]

HEAD every held copy; forget the ones that are gone so run() re-asks.

Parameters:

now (int | None)

Return type:

list[tuple[Any, …]]

tick(now)[source]

Periodic work. Runs due EVERY jobs when not overridden.

Parameters:

now (int)

Return type:

list[tuple[Any, …]]

state()[source]

What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.

Return type:

BlobReplicationStateReport

trouble()[source]

What an operator should be told without having to ask for it.

Everything here is WRONG: a watcher reds on it and a deploy fails on it. Something worth reading that is not a fault goes in notes(). May return a list of strings or typed Trouble instances.

Return type:

list[str]

pin_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

unpin_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

Mapping[str, Any]

status_cmd(args)[source]
Parameters:

args (Mapping[str, Any])

Return type:

list[Mapping[str, Any]]

run_cmd()[source]
Return type:

list[tuple[Any, …]]

verify_cmd()[source]
Return type:

list[tuple[Any, …]]

stop()[source]

Anything that must be said before the node goes. Must not raise.

Return type:

Any

abstract: ClassVar[bool] = False
commands: Mapping[str, CommandSpec] = {'pin': {'args': {'copies': 'optional', 'sha256': 'required'}, 'does': 'pin a blob here and keep that many copies of it on other servers', 'reply': '{sha256, copies, pinned}', 'subsystem': 'blob_replication'}, 'run': {'args': {}, 'does': 'mirror under-replicated blobs now', 'reply': '[(replication, ...)]', 'subsystem': 'blob_replication'}, 'status': {'args': {'sha256': 'optional'}, 'does': 'target and held copies, per blob', 'reply': '[{sha256, copies, held, servers}]', 'subsystem': 'blob_replication'}, 'unpin': {'args': {'sha256': 'required'}, 'does': 'stop replicating (and unpin) a blob; copies already made stay', 'reply': '{sha256, unpinned}', 'subsystem': 'blob_replication'}, 'verify': {'args': {}, 'does': 're-check every held copy now', 'reply': '[(replication, ...)]', 'subsystem': 'blob_replication'}}
fleetmesh_node.planes.store.blob_replication.compartment.partner_blossom_servers(node)[source]

Blossom URLs of every peer this node holds a grant with, from their descriptors.

Parameters:

node (Any)

Return type:

list[str]