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:
ParamBlockSyncConfig(DERIVED: ‘bool’ = False, sessions_ceiling: ‘int’ = 1024, recent_kept: ‘int’ = 256)
- name = 'sync'
- 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))
- class fleetmesh_node.planes.store.sync.core.SyncPeer[source]
Bases:
InitiatorMixin,ResponderMixin,HandoverMixin,WireProtocolBoth 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.
- config_cls
alias of
SyncConfig
- 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.
- __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:
- Return type:
None
- 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.
- 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:
ParamBlockRetentionConfig(DERIVED: ‘bool’ = False, sweep_seconds: ‘int’ = 3600, sweep_page: ‘int’ = 500)
- name = 'retention'
- 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))
- class fleetmesh_node.planes.store.retention.compartment.Retention[source]
Bases:
CompartmentPer-kind ages, swept on a slow cadence, with the shards held back.
- 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))
- 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=()),)
- protected()[source]
The shard filters a coverage claim or ProjectedNodeStore covers. Never evicted.
- 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.
- 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:
WireProtocolAnswers have and pull for blobs this node holds; takes offers under policy.
- config_cls
alias of
BlobWireConfig
- 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'))
- 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]
- 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:
- why_not(peer, size, now)[source]
The first reason an offer from this peer may not be taken, or None.
- state()[source]
What this compartment is, as plain data. Never raises. A compartment with a shape worth naming returns its TypedDict.
- 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.
- 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'}}
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:
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),
re-checks held copies on a slow cadence with HEAD, and
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))
- 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.
- config_cls
alias of
BlobReplicationConfig
- 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]
- 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:
- 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_privateto true or to a list of hosts.- Return type:
- source_url()[source]
Where partners fetch from: this node’s own public Blossom base URL.
- Return type:
str | None
- 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.
- 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'}}