Documentation
¶
Overview ¶
Package entities defines shared domain types for P2P messaging and dynamic configuration.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HashRemoteConfig ¶
func HashRemoteConfig(cfg *DynamicConfig) string
HashRemoteConfig computes a SHA-256 hash of the configurable fields in DynamicConfig.
Types ¶
type DCConfigurable ¶
type DCConfigurable[T any] interface { ApplyDynamicConfig(dcCfg *DynamicConfig) *T Clone() *T }
type DynamicConfig ¶
type DynamicConfig struct {
ChainID string `db:"chain_id" yaml:"chain_id" json:"chain_id"`
ClusterID string `db:"cluster_id" yaml:"cluster_id" json:"cluster_id"`
ServiceVersion string `db:"service_version" yaml:"service_version" json:"service_version"`
UpdatedAt time.Time `db:"updated_at" yaml:"-" json:"updated_at"`
PropagationEnabled bool `db:"propagation_enabled" json:"propagation_enabled" yaml:"propagation_enabled"`
// ExcludeSelfMessages is a flag that indicates whether messages originating from the node itself should be ignored.
// used for tracking eth latency measurements
ExcludeSelfMessages bool `db:"exclude_self_messages" yaml:"exclude_self_messages" json:"exclude_self_messages"`
// Coding and message settings
RandomMessageSize uint32 `db:"random_message_size_bytes" yaml:"random_message_size" json:"random_message_size_bytes"`
ShardFactor uint32 `db:"rlnc_shard_factor" yaml:"shard_factor" json:"rlnc_shard_factor"`
PublisherShardMultiplier float64 `db:"publisher_shard_multiplier" yaml:"publisher_shard_multiplier" json:"publisher_shard_multiplier"`
ForwardShardThreshold float64 `db:"forward_shard_threshold" yaml:"forward_shard_threshold" json:"forward_shard_threshold"`
// Mesh topology settings
MeshDegreeTarget int64 `db:"mesh_degree_target" yaml:"mesh_degree_target" json:"mesh_degree_target"`
MeshDegreeMin int64 `db:"mesh_degree_min" yaml:"mesh_degree_min" json:"mesh_degree_min"`
MeshDegreeMax int64 `db:"mesh_degree_max" yaml:"mesh_degree_max" json:"mesh_degree_max"`
}
DynamicConfig represents runtime-configurable parameters for P2P network behavior. These settings can be updated without restarting the node.
func FromYAMLFile ¶
func FromYAMLFile(path string) (*DynamicConfig, error)
FromYAMLFile loads a DynamicConfig from a YAML file at the specified path. Returns an error if the file cannot be opened or parsed.
func (*DynamicConfig) Normalize ¶
func (d *DynamicConfig) Normalize()
Normalize trims and normalizes ID fields in-place.
func (*DynamicConfig) ToMap ¶
func (d *DynamicConfig) ToMap() map[string]any
ToMap converts the DynamicConfig to a map representation suitable for storage or serialization. The updated_at field is set to the current time.
func (*DynamicConfig) Validate ¶
func (d *DynamicConfig) Validate() error
Validate checks that all configuration values are within valid ranges. Normalizes chainID by converting to lowercase and trimming whitespace. Returns an error if validation fails.
type GatewayClaims ¶
type GatewayClaims struct {
ScopeVersion int64 `json:"scope_version"`
Type GatewayType `json:"type"`
ChainID string `json:"chain_id,omitempty"`
// Set only on the services token; must never leak onto the peer-visible
// p2p handshake token (optimum-bootstrap#262).
OperatorID string `json:"operator_id,omitempty"`
// Pointer so omitempty drops it entirely; a value struct would still emit
// "cnf":{"peer_id":""} on cnf-less handshake tokens.
CNF *GatewayConfirmation `json:"cnf,omitempty"`
jwt.RegisteredClaims
}
GatewayClaims is the superset of gateway-JWT claims across both audiences; each token carries only the subset that applies to it.
func (*GatewayClaims) HasAudience ¶
func (c *GatewayClaims) HasAudience(want TokenAudience) bool
HasAudience reports whether the token's `aud` contains want. aud is multi-valued per RFC 7519, so membership is the spec-correct check.
type GatewayConfirmation ¶
type GatewayConfirmation struct {
PeerID string `json:"peer_id"`
}
GatewayConfirmation is the RFC 7800 `cnf` claim binding the JWT to the gateway's libp2p peer_id, so a replayed bearer token can be rejected.
type GatewayType ¶
type GatewayType string
GatewayType is the per-key gateway role. The role fully determines the publish/subscribe matrix on mump2p (see ADR-004 §Gateway types) — billing does not mint per-key topic lists; verifiers hard-code the mapping.
const ( GatewayTypeHermes GatewayType = "hermes" GatewayTypePartner GatewayType = "partner" GatewayTypeRelay GatewayType = "relay" )
func GatewayTypeFromString ¶
func GatewayTypeFromString(s string) (GatewayType, error)
func (GatewayType) String ¶
func (s GatewayType) String() string
type OptimumConfig ¶
type OptimumConfig struct {
ClusterID string `yaml:"cluster_id" env:"CLUSTER_ID" flag:"cluster_id"`
ChainID string `yaml:"chain_id" env:"CHAIN_ID" flag:"chain_id" default:"default"`
MaxMessageSize int64 `yaml:"max_message_size_bytes" env:"OPTIMUM_MAX_MSG_SIZE" flag:"max_message_size_bytes" default:"1048576"`
// Coding and message settings
RandomMessageSize uint32 `yaml:"random_message_size_bytes" env:"OPTIMUM_RANDOM_MSG_SIZE" flag:"random_message_size_bytes" default:"512"`
ShardFactor uint32 `yaml:"rlnc_shard_factor" env:"OPTIMUM_SHARD_FACTOR" flag:"rlnc_shard_factor" default:"4"`
PublisherShardMultiplier float64 `yaml:"publisher_shard_multiplier" env:"OPTIMUM_SHARD_MULT" flag:"publisher_shard_multiplier" default:"1.5"`
ForwardShardThreshold float64 `yaml:"forward_shard_threshold" env:"OPTIMUM_THRESHOLD" flag:"forward_shard_threshold" default:"0.75"`
// Mesh topology settings
MeshDegreeTarget int64 `yaml:"mesh_degree_target" env:"OPTIMUM_MESH_TARGET" flag:"mesh_degree_target" default:"6"`
MeshDegreeMin int64 `yaml:"mesh_degree_min" env:"OPTIMUM_MESH_MIN" flag:"mesh_degree_min" default:"4"`
MeshDegreeMax int64 `yaml:"mesh_degree_max" env:"OPTIMUM_MESH_MAX" flag:"mesh_degree_max" default:"12"`
BootstrapPeers []string `yaml:"bootstrap_peers" env:"BOOTSTRAP_PEERS" flag:"bootstrap_peers"`
}
OptimumConfig holds configuration for P2P network settings including cluster/chain identifiers, message size limits, sharding parameters, mesh topology settings, and bootstrap peer addresses.
func (*OptimumConfig) ApplyDynamicConfig ¶
func (cfg *OptimumConfig) ApplyDynamicConfig(dcCfg *DynamicConfig) *OptimumConfig
ApplyDynamicConfig creates a new OptimumConfig by applying dynamic configuration overrides to the current config. Returns a new config instance; does not modify the receiver.
func (*OptimumConfig) Clone ¶
func (cfg *OptimumConfig) Clone() *OptimumConfig
Clone creates a deep copy of the configuration. The BootstrapPeers slice is copied to avoid sharing references.
func (*OptimumConfig) Validate ¶
func (cfg *OptimumConfig) Validate() error
Validate checks that required fields are set and values are within valid ranges. Returns an error if validation fails.
type P2PMessage ¶
type P2PMessage struct {
SourceNodeID string `json:"source_node_id"`
UpstreamPeerID string `json:"upstream_peer_id,omitempty"`
Topic string `json:"topic"`
MessageID string `json:"message_id"`
Message []byte `json:"message"`
}
func UnmarshalP2PMessage ¶
func UnmarshalP2PMessage(data []byte) (*P2PMessage, error)
UnmarshalP2PMessage deserializes JSON data into a P2PMessage struct.
func (*P2PMessage) DecodeFrom ¶
func (m *P2PMessage) DecodeFrom(r io.Reader) error
DecodeFrom reads JSON data from an io.Reader and decodes it into the P2PMessage struct.
func (*P2PMessage) Marshal ¶
func (m *P2PMessage) Marshal() ([]byte, error)
Marshal serializes the P2PMessage into JSON format.
type TokenAudience ¶
type TokenAudience string
TokenAudience is a gateway-JWT `aud` value. optimum-auth mints a P2P and a services token from one key/issuer, differing only by audience, so each verifier can require the one meant for it.
const ( TokenAudienceP2P TokenAudience = "p2p" TokenAudienceServices TokenAudience = "services" )
func (TokenAudience) String ¶
func (a TokenAudience) String() string
Source Files