Documentation
¶
Index ¶
- Constants
- type ChainsyncClientState
- type ClientAddedEvent
- type ClientRemoveRequestedEvent
- type ClientRemovedEvent
- type ClientStalledEvent
- type ClientStatus
- type ClientSyncedEvent
- type Config
- type ForkDetectedEvent
- type State
- func (s *State) AddClient(connId connection.ConnectionId, intersectPoint ocommon.Point) (*ChainsyncClientState, error)
- func (s *State) AddClientConnId(connId ouroboros.ConnectionId) bool
- func (s *State) CheckStalledClients() []ouroboros.ConnectionId
- func (s *State) ClearSeenHeaders()
- func (s *State) ClearSeenHeadersFrom(fromSlot uint64)
- func (s *State) ClientConnCount() int
- func (s *State) ClientObservabilityOnly(connId ouroboros.ConnectionId) (bool, bool)
- func (s *State) GetClientConnId() *ouroboros.ConnectionId
- func (s *State) GetClientConnIds() []ouroboros.ConnectionId
- func (s *State) GetTrackedClient(connId ouroboros.ConnectionId) *TrackedClient
- func (s *State) GetTrackedClients() []TrackedClient
- func (s *State) HandleClientRemoveRequestedEvent(evt event.Event)
- func (s *State) HasClientConnId(connId ouroboros.ConnectionId) bool
- func (s *State) MarkClientSynced(connId ouroboros.ConnectionId)
- func (s *State) MaxClients() int
- func (s *State) PruneSeenHeaders(beforeSlot uint64)
- func (s *State) RemoveClient(connId connection.ConnectionId)
- func (s *State) RemoveClientConnId(connId ouroboros.ConnectionId)
- func (s *State) SetClientConnId(connId ouroboros.ConnectionId)
- func (s *State) SetClientObservabilityOnly(connId ouroboros.ConnectionId, observabilityOnly bool) bool
- func (s *State) TryAddClientConnId(connId ouroboros.ConnectionId, maxClients int) bool
- func (s *State) TryAddObservedClientConnId(connId ouroboros.ConnectionId) bool
- func (s *State) UpdateClientTip(connId ouroboros.ConnectionId, point ocommon.Point, tip ochainsync.Tip) bool
- func (s *State) UpdateClientTipWithoutDedup(connId ouroboros.ConnectionId, point ocommon.Point, tip ochainsync.Tip)
- type TrackedClient
Constants ¶
const ( // ClientAddedEventType is emitted when a new chainsync // client is registered. ClientAddedEventType event.EventType = "chainsync.client_added" // ClientRemovedEventType is emitted when a chainsync client // is unregistered (e.g. on disconnect). ClientRemovedEventType event.EventType = "chainsync.client_removed" // ClientSyncedEventType is emitted when a chainsync client // reaches the upstream chain tip. ClientSyncedEventType event.EventType = "chainsync.client_synced" // ClientStalledEventType is emitted when a chainsync client // has not received any headers within the stall timeout. ClientStalledEventType event.EventType = "chainsync.client_stalled" // ForkDetectedEventType is emitted when two clients report // different block hashes for the same slot. ForkDetectedEventType event.EventType = "chainsync.fork_detected" // ClientRemoveRequestedEventType is emitted when another // component requests chainsync to remove a tracked client. ClientRemoveRequestedEventType event.EventType = "chainsync.client_remove_requested" )
const DefaultMaxClients = 3
DefaultMaxClients is the default maximum number of concurrent chainsync clients.
const DefaultStallTimeout = 2 * time.Minute
DefaultStallTimeout is the default duration after which a client with no activity is considered stalled. This value must stay in sync with config.DefaultChainsyncConfig() and the fallback in internal/node/node.go.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChainsyncClientState ¶
type ChainsyncClientState struct {
ChainIter *chain.ChainIterator
Cursor ocommon.Point
NeedsInitialRollback bool
}
ChainsyncClientState holds per-connection state for a chainsync server-side client (node-to-client connections).
type ClientAddedEvent ¶ added in v0.22.0
type ClientAddedEvent struct {
ConnId ouroboros.ConnectionId
TotalClients int
}
ClientAddedEvent contains details about a newly registered chainsync client.
type ClientRemoveRequestedEvent ¶ added in v0.22.0
type ClientRemoveRequestedEvent struct {
ConnId ouroboros.ConnectionId
ConnKey string
Reason string
}
ClientRemoveRequestedEvent contains the connection details for a requested tracked-client removal.
type ClientRemovedEvent ¶ added in v0.22.0
type ClientRemovedEvent struct {
ConnId ouroboros.ConnectionId
TotalClients int
WasPrimary bool
}
ClientRemovedEvent contains details about a removed chainsync client.
type ClientStalledEvent ¶ added in v0.22.0
type ClientStalledEvent struct {
ConnId ouroboros.ConnectionId
Slot uint64
}
ClientStalledEvent is published when a client exceeds the stall timeout.
type ClientStatus ¶ added in v0.22.0
type ClientStatus int
ClientStatus represents the sync status of a chainsync client.
const ( // ClientStatusSyncing indicates the client is actively // receiving headers. ClientStatusSyncing ClientStatus = iota // ClientStatusSynced indicates the client has reached the // upstream chain tip. ClientStatusSynced // ClientStatusStalled indicates the client has not received // activity within the stall timeout. ClientStatusStalled // ClientStatusFailed indicates the client encountered an // error. ClientStatusFailed )
func (ClientStatus) String ¶ added in v0.22.0
func (s ClientStatus) String() string
String returns a human-readable name for the ClientStatus.
type ClientSyncedEvent ¶ added in v0.22.0
type ClientSyncedEvent struct {
ConnId ouroboros.ConnectionId
Slot uint64
}
ClientSyncedEvent is published when a client reaches the upstream chain tip.
type Config ¶ added in v0.22.0
Config holds configuration for the chainsync State.
func DefaultConfig ¶ added in v0.22.0
func DefaultConfig() Config
DefaultConfig returns the default chainsync configuration.
type ForkDetectedEvent ¶ added in v0.22.0
type ForkDetectedEvent struct {
Slot uint64
HashA []byte
HashB []byte
ConnIdA ouroboros.ConnectionId
ConnIdB ouroboros.ConnectionId
Point ocommon.Point
}
ForkDetectedEvent is published when two clients report different block hashes at the same slot.
type State ¶
State manages chainsync client connections and header tracking for both server-side (N2C) and outbound (N2N) connections.
func NewState ¶
func NewState( eventBus *event.EventBus, ledgerState *ledger.LedgerState, ) *State
NewState creates a new chainsync State with the given event bus and ledger state using default configuration.
func NewStateWithConfig ¶ added in v0.22.0
func NewStateWithConfig( eventBus *event.EventBus, ledgerState *ledger.LedgerState, cfg Config, ) *State
NewStateWithConfig creates a new chainsync State with the given event bus, ledger state, and configuration.
func (*State) AddClient ¶
func (s *State) AddClient( connId connection.ConnectionId, intersectPoint ocommon.Point, ) (*ChainsyncClientState, error)
AddClient registers a server-side (N2C) chainsync client.
func (*State) AddClientConnId ¶ added in v0.21.0
func (s *State) AddClientConnId( connId ouroboros.ConnectionId, ) bool
AddClientConnId adds a connection ID to the set of tracked chainsync clients, enforcing the configured MaxClients limit. Returns true if the client was added, false if rejected (already tracked or at capacity). If no active client exists, this connection is automatically set as the active client.
func (*State) CheckStalledClients ¶ added in v0.22.0
func (s *State) CheckStalledClients() []ouroboros.ConnectionId
CheckStalledClients scans all tracked clients and marks any that have exceeded the stall timeout. If the primary client is stalled, a failover to the next best client is triggered. Returns the list of connection IDs that were newly marked as stalled.
func (*State) ClearSeenHeaders ¶ added in v0.22.0
func (s *State) ClearSeenHeaders()
ClearSeenHeaders removes all entries from the header deduplication cache. This should be called on rollback to avoid stale entries.
func (*State) ClearSeenHeadersFrom ¶ added in v0.27.4
ClearSeenHeadersFrom removes entries from the header deduplication cache above the specified slot. This allows a restarted chainsync client to replay headers beyond a known-good intersect point after an active-peer switch without discarding older fork-detection history.
func (*State) ClientConnCount ¶ added in v0.21.0
ClientConnCount returns the number of tracked chainsync clients.
func (*State) ClientObservabilityOnly ¶ added in v0.27.5
func (s *State) ClientObservabilityOnly( connId ouroboros.ConnectionId, ) (bool, bool)
ClientObservabilityOnly reports whether a tracked client is currently observability-only. The second return value reports whether the client exists.
func (*State) GetClientConnId ¶
func (s *State) GetClientConnId() *ouroboros.ConnectionId
GetClientConnId returns the active chainsync client connection ID. This is the connection that should be used for block fetching.
func (*State) GetClientConnIds ¶ added in v0.21.0
func (s *State) GetClientConnIds() []ouroboros.ConnectionId
GetClientConnIds returns all tracked chainsync client connection IDs.
func (*State) GetTrackedClient ¶ added in v0.22.0
func (s *State) GetTrackedClient( connId ouroboros.ConnectionId, ) *TrackedClient
GetTrackedClient returns a deep copy of the TrackedClient for the given connection ID, or nil if not found. Byte slices inside Point.Hash are cloned so the caller cannot race with concurrent UpdateClientTip calls.
func (*State) GetTrackedClients ¶ added in v0.22.0
func (s *State) GetTrackedClients() []TrackedClient
GetTrackedClients returns deep copies of all tracked clients.
func (*State) HandleClientRemoveRequestedEvent ¶ added in v0.22.0
HandleClientRemoveRequestedEvent removes a tracked client when a component publishes a client removal request event.
func (*State) HasClientConnId ¶ added in v0.21.0
func (s *State) HasClientConnId( connId ouroboros.ConnectionId, ) bool
HasClientConnId returns true if the connection ID is being tracked.
func (*State) MarkClientSynced ¶ added in v0.22.0
func (s *State) MarkClientSynced( connId ouroboros.ConnectionId, )
MarkClientSynced marks a tracked client as synced (at chain tip).
func (*State) MaxClients ¶ added in v0.22.0
MaxClients returns the configured maximum number of chainsync clients.
func (*State) PruneSeenHeaders ¶ added in v0.22.0
PruneSeenHeaders removes entries from the header deduplication cache for slots older than the given slot.
func (*State) RemoveClient ¶
func (s *State) RemoveClient(connId connection.ConnectionId)
RemoveClient unregisters a server-side (N2C) chainsync client.
func (*State) RemoveClientConnId ¶
func (s *State) RemoveClientConnId( connId ouroboros.ConnectionId, )
RemoveClientConnId removes a connection from tracking. If this was the active client, promotes the client with the highest tip slot as the new primary.
func (*State) SetClientConnId ¶
func (s *State) SetClientConnId(connId ouroboros.ConnectionId)
SetClientConnId sets the active chainsync client connection ID. This is used when chain selection determines a new best peer.
func (*State) SetClientObservabilityOnly ¶ added in v0.27.5
func (s *State) SetClientObservabilityOnly( connId ouroboros.ConnectionId, observabilityOnly bool, ) bool
SetClientObservabilityOnly toggles whether a tracked client participates in the eligible chainsync pool. Promoting an observability-only client back into the eligible pool respects MaxClients; when the pool is full, the client remains observability-only and this method returns false.
func (*State) TryAddClientConnId ¶ added in v0.21.0
func (s *State) TryAddClientConnId( connId ouroboros.ConnectionId, maxClients int, ) bool
TryAddClientConnId atomically checks if a connection can be added (not already tracked and under maxClients limit) and adds it if allowed. Returns true if the connection was added, false otherwise.
func (*State) TryAddObservedClientConnId ¶ added in v0.27.5
func (s *State) TryAddObservedClientConnId( connId ouroboros.ConnectionId, ) bool
TryAddObservedClientConnId adds a connection to observability-only tracking. Observability-only clients do not consume the eligible client limit and are never promoted as the active chainsync source.
func (*State) UpdateClientTip ¶ added in v0.22.0
func (s *State) UpdateClientTip( connId ouroboros.ConnectionId, point ocommon.Point, tip ochainsync.Tip, ) bool
UpdateClientTip updates the cursor, tip, and activity tracking for a tracked client, and performs header deduplication. Returns true if the header at this point is new (not a duplicate).
func (*State) UpdateClientTipWithoutDedup ¶ added in v0.27.5
func (s *State) UpdateClientTipWithoutDedup( connId ouroboros.ConnectionId, point ocommon.Point, tip ochainsync.Tip, )
UpdateClientTipWithoutDedup updates the cursor, tip, and activity tracking for a tracked client without recording the header in the shared dedup cache. This is used for peers that should not drive ledger ingress, so they do not suppress later delivery of the same header from an eligible peer.
type TrackedClient ¶ added in v0.22.0
type TrackedClient struct {
ConnId ouroboros.ConnectionId
Cursor ocommon.Point
Tip ochainsync.Tip
Status ClientStatus
// ObservabilityOnly marks connections that should keep
// tip/activity metrics but must not consume the eligible
// client pool or become active for ledger ingress.
ObservabilityOnly bool
LastActivity time.Time
HeadersRecv uint64
// TODO: BytesRecv needs to be wired to the underlying
// connection's byte counter. Currently unused.
BytesRecv uint64
}
TrackedClient holds per-connection state for a tracked chainsync client (outbound node-to-node connections).