1+ // Package protocol provides the common functionality for mini-protocols
12package protocol
23
34import (
@@ -13,11 +14,10 @@ import (
1314 "github.com/fxamacker/cbor/v2"
1415)
1516
16- const (
17- // This is completely arbitrary, but the line had to be drawn somewhere
18- MAX_MESSAGES_PER_SEGMENT = 20
19- )
17+ // This is completely arbitrary, but the line had to be drawn somewhere
18+ const maxMessagesPerSegment = 20
2019
20+ // Protocol implements the base functionality of an Ouroboros mini-protocol
2121type Protocol struct {
2222 config ProtocolConfig
2323 muxerSendChan chan * muxer.Segment
@@ -34,6 +34,7 @@ type Protocol struct {
3434 stateTransitionTimer * time.Timer
3535}
3636
37+ // ProtocolConfig provides the configuration for Protocol
3738type ProtocolConfig struct {
3839 Name string
3940 ProtocolId uint16
@@ -47,23 +48,25 @@ type ProtocolConfig struct {
4748 InitialState State
4849}
4950
51+ // ProtocolMode is an enum of the protocol modes
5052type ProtocolMode uint
5153
5254const (
53- ProtocolModeNone ProtocolMode = 0
54- ProtocolModeNodeToClient ProtocolMode = 1
55- ProtocolModeNodeToNode ProtocolMode = 2
55+ ProtocolModeNone ProtocolMode = 0 // Default (invalid) protocol mode
56+ ProtocolModeNodeToClient ProtocolMode = 1 // Node-to-client protocol mode
57+ ProtocolModeNodeToNode ProtocolMode = 2 // Node-to-node protocol mode
5658)
5759
60+ // ProtocolRole is an enum of the protocol roles
5861type ProtocolRole uint
5962
6063const (
61- ProtocolRoleNone ProtocolRole = 0
62- ProtocolRoleClient ProtocolRole = 1
63- ProtocolRoleServer ProtocolRole = 2
64+ ProtocolRoleNone ProtocolRole = 0 // Default (invalid) protocol role
65+ ProtocolRoleClient ProtocolRole = 1 // Client protocol role
66+ ProtocolRoleServer ProtocolRole = 2 // Server protocol role
6467)
6568
66- // Common arguments for individual mini-protocols
69+ // ProtocolOptions provides common arguments for all mini-protocols
6770type ProtocolOptions struct {
6871 Muxer * muxer.Muxer
6972 ErrorChan chan error
@@ -73,9 +76,13 @@ type ProtocolOptions struct {
7376 Version uint16
7477}
7578
79+ // MessageHandlerFunc represents a function that handles an incoming message
7680type MessageHandlerFunc func (Message , bool ) error
81+
82+ // MessageFromCborFunc represents a function that parses a mini-protocol message
7783type MessageFromCborFunc func (uint , []byte ) (Message , error )
7884
85+ // New returns a new Protocol object
7986func New (config ProtocolConfig ) * Protocol {
8087 p := & Protocol {
8188 config : config ,
@@ -84,6 +91,7 @@ func New(config ProtocolConfig) *Protocol {
8491 return p
8592}
8693
94+ // Start initializes the mini-protocol
8795func (p * Protocol ) Start () {
8896 // Register protocol with muxer
8997 p .muxerSendChan , p .muxerRecvChan , p .muxerDoneChan = p .config .Muxer .RegisterProtocol (p .config .ProtocolId )
@@ -108,23 +116,28 @@ func (p *Protocol) Start() {
108116 go p .sendLoop ()
109117}
110118
119+ // Mode returns the protocol mode
111120func (p * Protocol ) Mode () ProtocolMode {
112121 return p .config .Mode
113122}
114123
124+ // Role understands the protocol role
115125func (p * Protocol ) Role () ProtocolRole {
116126 return p .config .Role
117127}
118128
129+ // DoneChan returns the channel used to signal protocol shutdown
119130func (p * Protocol ) DoneChan () chan bool {
120131 return p .doneChan
121132}
122133
134+ // SendMessage appends a message to the send queue
123135func (p * Protocol ) SendMessage (msg Message ) error {
124136 p .sendQueueChan <- msg
125137 return nil
126138}
127139
140+ // SendError sends an error to the handler in the Ouroboros object
128141func (p * Protocol ) SendError (err error ) {
129142 p .config .ErrorChan <- err
130143}
@@ -198,8 +211,8 @@ func (p *Protocol) sendLoop() {
198211 }
199212 setNewState = true
200213 }
201- // We don't want more than MAX_MESSAGES_PER_SEGMENT messages in a segment
202- if msgCount >= MAX_MESSAGES_PER_SEGMENT {
214+ // We don't want more than maxMessagesPerSegment messages in a segment
215+ if msgCount >= maxMessagesPerSegment {
203216 break
204217 }
205218 // We don't want to add more messages once we spill over into a second segment
@@ -357,14 +370,14 @@ func (p *Protocol) setState(state State) {
357370 p .state = state
358371 // Mark protocol as ready to send/receive based on role and agency of the new state
359372 switch p .config .StateMap [p .state ].Agency {
360- case AGENCY_CLIENT :
373+ case AgencyClient :
361374 switch p .config .Role {
362375 case ProtocolRoleClient :
363376 p .sendReadyChan <- true
364377 case ProtocolRoleServer :
365378 p .recvReadyChan <- true
366379 }
367- case AGENCY_SERVER :
380+ case AgencyServer :
368381 switch p .config .Role {
369382 case ProtocolRoleServer :
370383 p .sendReadyChan <- true
0 commit comments