Merge pull request #188 from cloudstruct/docs/protocol-chainsync-package

docs: code docs for protocol/chainsync package

Author: agaffney

protocol/chainsync/chainsync.go

@@ -1,3 +1,4 @@
+// Package chainsync implements the Ouroboros chain-sync protocol
 package chainsync
 
 import (
@@ -7,91 +8,95 @@ import (
 	"github.com/cloudstruct/go-ouroboros-network/protocol/common"
 )
 
+// Protocol identifiers
 const (
-	PROTOCOL_NAME          = "chain-sync"
-	PROTOCOL_ID_NTN uint16 = 2
-	PROTOCOL_ID_NTC uint16 = 5
+	protocolName         = "chain-sync"
+	protocolIdNtN uint16 = 2
+	protocolIdNtC uint16 = 5
 )
 
 var (
-	STATE_IDLE       = protocol.NewState(1, "Idle")
-	STATE_CAN_AWAIT  = protocol.NewState(2, "CanAwait")
-	STATE_MUST_REPLY = protocol.NewState(3, "MustReply")
-	STATE_INTERSECT  = protocol.NewState(4, "Intersect")
-	STATE_DONE       = protocol.NewState(5, "Done")
+	stateIdle      = protocol.NewState(1, "Idle")
+	stateCanAwait  = protocol.NewState(2, "CanAwait")
+	stateMustReply = protocol.NewState(3, "MustReply")
+	stateIntersect = protocol.NewState(4, "Intersect")
+	stateDone      = protocol.NewState(5, "Done")
 )
 
+// ChainSync protocol state machine
 var StateMap = protocol.StateMap{
-	STATE_IDLE: protocol.StateMapEntry{
+	stateIdle: protocol.StateMapEntry{
 		Agency: protocol.AgencyClient,
 		Transitions: []protocol.StateTransition{
 			{
-				MsgType:  MESSAGE_TYPE_REQUEST_NEXT,
-				NewState: STATE_CAN_AWAIT,
+				MsgType:  MessageTypeRequestNext,
+				NewState: stateCanAwait,
 			},
 			{
-				MsgType:  MESSAGE_TYPE_FIND_INTERSECT,
-				NewState: STATE_INTERSECT,
+				MsgType:  MessageTypeFindIntersect,
+				NewState: stateIntersect,
 			},
 			{
-				MsgType:  MESSAGE_TYPE_DONE,
-				NewState: STATE_DONE,
+				MsgType:  MessageTypeDone,
+				NewState: stateDone,
 			},
 		},
 	},
-	STATE_CAN_AWAIT: protocol.StateMapEntry{
+	stateCanAwait: protocol.StateMapEntry{
 		Agency: protocol.AgencyServer,
 		Transitions: []protocol.StateTransition{
 			{
-				MsgType:  MESSAGE_TYPE_AWAIT_REPLY,
-				NewState: STATE_MUST_REPLY,
+				MsgType:  MessageTypeAwaitReply,
+				NewState: stateMustReply,
 			},
 			{
-				MsgType:  MESSAGE_TYPE_ROLL_FORWARD,
-				NewState: STATE_IDLE,
+				MsgType:  MessageTypeRollForward,
+				NewState: stateIdle,
 			},
 			{
-				MsgType:  MESSAGE_TYPE_ROLL_BACKWARD,
-				NewState: STATE_IDLE,
+				MsgType:  MessageTypeRollBackward,
+				NewState: stateIdle,
 			},
 		},
 	},
-	STATE_INTERSECT: protocol.StateMapEntry{
+	stateIntersect: protocol.StateMapEntry{
 		Agency: protocol.AgencyServer,
 		Transitions: []protocol.StateTransition{
 			{
-				MsgType:  MESSAGE_TYPE_INTERSECT_FOUND,
-				NewState: STATE_IDLE,
+				MsgType:  MessageTypeIntersectFound,
+				NewState: stateIdle,
 			},
 			{
-				MsgType:  MESSAGE_TYPE_INTERSECT_NOT_FOUND,
-				NewState: STATE_IDLE,
+				MsgType:  MessageTypeIntersectNotFound,
+				NewState: stateIdle,
 			},
 		},
 	},
-	STATE_MUST_REPLY: protocol.StateMapEntry{
+	stateMustReply: protocol.StateMapEntry{
 		Agency: protocol.AgencyServer,
 		Transitions: []protocol.StateTransition{
 			{
-				MsgType:  MESSAGE_TYPE_ROLL_FORWARD,
-				NewState: STATE_IDLE,
+				MsgType:  MessageTypeRollForward,
+				NewState: stateIdle,
 			},
 			{
-				MsgType:  MESSAGE_TYPE_ROLL_BACKWARD,
-				NewState: STATE_IDLE,
+				MsgType:  MessageTypeRollBackward,
+				NewState: stateIdle,
 			},
 		},
 	},
-	STATE_DONE: protocol.StateMapEntry{
+	stateDone: protocol.StateMapEntry{
 		Agency: protocol.AgencyNone,
 	},
 }
 
+// ChainSync is a wrapper object that holds the client and server instances
 type ChainSync struct {
 	Client *Client
 	Server *Server
 }
 
+// Config is used to configure the ChainSync protocol instance
 type Config struct {
 	RollBackwardFunc RollBackwardFunc
 	RollForwardFunc  RollForwardFunc
@@ -103,6 +108,7 @@ type Config struct {
 type RollBackwardFunc func(common.Point, Tip) error
 type RollForwardFunc func(uint, interface{}, Tip) error
 
+// New returns a new ChainSync object
 func New(protoOptions protocol.ProtocolOptions, cfg *Config) *ChainSync {
 	c := &ChainSync{
 		Client: NewClient(protoOptions, cfg),
@@ -111,8 +117,10 @@ func New(protoOptions protocol.ProtocolOptions, cfg *Config) *ChainSync {
 	return c
 }
 
+// ChainSyncOptionFunc represents a function used to modify the ChainSync protocol config
 type ChainSyncOptionFunc func(*Config)
 
+// NewConfig returns a new ChainSync config object with the provided options
 func NewConfig(options ...ChainSyncOptionFunc) Config {
 	c := Config{
 		IntersectTimeout: 5 * time.Second,
@@ -129,24 +137,28 @@ func NewConfig(options ...ChainSyncOptionFunc) Config {
 	return c
 }
 
+// WithRollBackwardFunc specifies the RollBackward callback function
 func WithRollBackwardFunc(rollBackwardFunc RollBackwardFunc) ChainSyncOptionFunc {
 	return func(c *Config) {
 		c.RollBackwardFunc = rollBackwardFunc
 	}
 }
 
+// WithRollForwardFunc specifies the RollForward callback function
 func WithRollForwardFunc(rollForwardFunc RollForwardFunc) ChainSyncOptionFunc {
 	return func(c *Config) {
 		c.RollForwardFunc = rollForwardFunc
 	}
 }
 
+// WithIntersectTimeout specifies the timeout for intersect operations
 func WithIntersectTimeout(timeout time.Duration) ChainSyncOptionFunc {
 	return func(c *Config) {
 		c.IntersectTimeout = timeout
 	}
 }
 
+// WithBlockTimeout specifies the timeout for block fetch operations
 func WithBlockTimeout(timeout time.Duration) ChainSyncOptionFunc {
 	return func(c *Config) {
 		c.BlockTimeout = timeout

protocol/chainsync/client.go

@@ -8,6 +8,7 @@ import (
 	"sync"
 )
 
+// Client implements the ChainSync client
 type Client struct {
 	*protocol.Protocol
 	config                *Config
@@ -18,13 +19,14 @@ type Client struct {
 	currentTipChan        chan Tip
 }
 
+// NewClient returns a new ChainSync client object
 func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
 	// Use node-to-client protocol ID
-	protocolId := PROTOCOL_ID_NTC
+	protocolId := protocolIdNtC
 	msgFromCborFunc := NewMsgFromCborNtC
 	if protoOptions.Mode == protocol.ProtocolModeNodeToNode {
 		// Use node-to-node protocol ID
-		protocolId = PROTOCOL_ID_NTN
+		protocolId = protocolIdNtN
 		msgFromCborFunc = NewMsgFromCborNtN
 	}
 	if cfg == nil {
@@ -39,19 +41,19 @@ func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
 	}
 	// Update state map with timeouts
 	stateMap := StateMap.Copy()
-	if entry, ok := stateMap[STATE_INTERSECT]; ok {
+	if entry, ok := stateMap[stateIntersect]; ok {
 		entry.Timeout = c.config.IntersectTimeout
-		stateMap[STATE_INTERSECT] = entry
+		stateMap[stateIntersect] = entry
 	}
-	for _, state := range []protocol.State{STATE_CAN_AWAIT, STATE_MUST_REPLY} {
+	for _, state := range []protocol.State{stateCanAwait, stateMustReply} {
 		if entry, ok := stateMap[state]; ok {
 			entry.Timeout = c.config.BlockTimeout
 			stateMap[state] = entry
 		}
 	}
 	// Configure underlying Protocol
 	protoConfig := protocol.ProtocolConfig{
-		Name:                PROTOCOL_NAME,
+		Name:                protocolName,
 		ProtocolId:          protocolId,
 		Muxer:               protoOptions.Muxer,
 		ErrorChan:           protoOptions.ErrorChan,
@@ -60,7 +62,7 @@ func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
 		MessageHandlerFunc:  c.messageHandler,
 		MessageFromCborFunc: msgFromCborFunc,
 		StateMap:            stateMap,
-		InitialState:        STATE_IDLE,
+		InitialState:        stateIdle,
 	}
 	c.Protocol = protocol.New(protoConfig)
 	// Start goroutine to cleanup resources on protocol shutdown
@@ -76,22 +78,23 @@ func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
 func (c *Client) messageHandler(msg protocol.Message, isResponse bool) error {
 	var err error
 	switch msg.Type() {
-	case MESSAGE_TYPE_AWAIT_REPLY:
+	case MessageTypeAwaitReply:
 		err = c.handleAwaitReply()
-	case MESSAGE_TYPE_ROLL_FORWARD:
+	case MessageTypeRollForward:
 		err = c.handleRollForward(msg)
-	case MESSAGE_TYPE_ROLL_BACKWARD:
+	case MessageTypeRollBackward:
 		err = c.handleRollBackward(msg)
-	case MESSAGE_TYPE_INTERSECT_FOUND:
+	case MessageTypeIntersectFound:
 		err = c.handleIntersectFound(msg)
-	case MESSAGE_TYPE_INTERSECT_NOT_FOUND:
+	case MessageTypeIntersectNotFound:
 		err = c.handleIntersectNotFound(msg)
 	default:
-		err = fmt.Errorf("%s: received unexpected message type %d", PROTOCOL_NAME, msg.Type())
+		err = fmt.Errorf("%s: received unexpected message type %d", protocolName, msg.Type())
 	}
 	return err
 }
 
+// Stop transitions the protocol to the Done state. No more protocol operations will be possible afterward
 func (c *Client) Stop() error {
 	c.busyMutex.Lock()
 	defer c.busyMutex.Unlock()
@@ -102,6 +105,7 @@ func (c *Client) Stop() error {
 	return nil
 }
 
+// GetCurrentTip returns the current chain tip
 func (c *Client) GetCurrentTip() (*Tip, error) {
 	c.busyMutex.Lock()
 	defer c.busyMutex.Unlock()
@@ -115,6 +119,8 @@ func (c *Client) GetCurrentTip() (*Tip, error) {
 	return &tip, nil
 }
 
+// Sync begins a chain-sync operation using the provided intersect point(s). Incoming blocks will be delivered
+// via the RollForward callback function specified in the protocol config
 func (c *Client) Sync(intersectPoints []common.Point) error {
 	c.busyMutex.Lock()
 	defer c.busyMutex.Unlock()

protocol/chainsync/error.go

@@ -1,5 +1,6 @@
 package chainsync
 
+// IntersectNotFoundError represents a failure to find a chain intersection
 type IntersectNotFoundError struct {
 }