Skip to content

Commit 0c7536c

Browse files
agaffneyagaffney
authored
Merge pull request #189 from cloudstruct/docs/protocol-handshake-package
docs: code docs for protocol/handshake package
2 parents 0f63e11 + ffd6841 commit 0c7536c

File tree

6 files changed

+90
-58
lines changed

6 files changed

+90
-58
lines changed

‎protocol/chainsync/messages.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import (
88
"github.com/fxamacker/cbor/v2"
99
)
1010

11+
// Message types
1112
const (
1213
MessageTypeRequestNext = 0
1314
MessageTypeAwaitReply = 1

‎protocol/handshake/client.go‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,17 @@ package handshake
22

33
import (
44
"fmt"
5+
56
"github.com/cloudstruct/go-ouroboros-network/protocol"
67
)
78

9+
// Client implements the Handshake client
810
type Client struct {
911
*protocol.Protocol
1012
config *Config
1113
}
1214

15+
// NewClient returns a new Handshake client object
1316
func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
1417
if cfg == nil {
1518
tmpCfg := NewConfig()
@@ -20,34 +23,35 @@ func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
2023
}
2124
// Update state map with timeout
2225
stateMap := StateMap.Copy()
23-
if entry, ok := stateMap[STATE_CONFIRM]; ok {
26+
if entry, ok := stateMap[stateConfirm]; ok {
2427
entry.Timeout = c.config.Timeout
25-
stateMap[STATE_CONFIRM] = entry
28+
stateMap[stateConfirm] = entry
2629
}
2730
// Configure underlying Protocol
2831
protoConfig := protocol.ProtocolConfig{
29-
Name: PROTOCOL_NAME,
30-
ProtocolId: PROTOCOL_ID,
32+
Name: protocolName,
33+
ProtocolId: protocolId,
3134
Muxer: protoOptions.Muxer,
3235
ErrorChan: protoOptions.ErrorChan,
3336
Mode: protoOptions.Mode,
3437
Role: protocol.ProtocolRoleClient,
3538
MessageHandlerFunc: c.handleMessage,
3639
MessageFromCborFunc: NewMsgFromCbor,
3740
StateMap: stateMap,
38-
InitialState: STATE_PROPOSE,
41+
InitialState: statePropose,
3942
}
4043
c.Protocol = protocol.New(protoConfig)
4144
return c
4245
}
4346

47+
// Start begins the handshake process
4448
func (c *Client) Start() {
4549
c.Protocol.Start()
4650
// Send our ProposeVersions message
4751
versionMap := make(map[uint16]interface{})
48-
diffusionMode := DIFFUSION_MODE_INITIATOR_ONLY
52+
diffusionMode := DiffusionModeInitiatorOnly
4953
if c.config.ClientFullDuplex {
50-
diffusionMode = DIFFUSION_MODE_INITIATOR_AND_RESPONDER
54+
diffusionMode = DiffusionModeInitiatorAndResponder
5155
}
5256
for _, version := range c.config.ProtocolVersions {
5357
if c.Mode() == protocol.ProtocolModeNodeToNode {
@@ -63,12 +67,12 @@ func (c *Client) Start() {
6367
func (c *Client) handleMessage(msg protocol.Message, isResponse bool) error {
6468
var err error
6569
switch msg.Type() {
66-
case MESSAGE_TYPE_ACCEPT_VERSION:
70+
case MessageTypeAcceptVersion:
6771
err = c.handleAcceptVersion(msg)
68-
case MESSAGE_TYPE_REFUSE:
72+
case MessageTypeRefuse:
6973
err = c.handleRefuse(msg)
7074
default:
71-
err = fmt.Errorf("%s: received unexpected message type %d", PROTOCOL_NAME, msg.Type())
75+
err = fmt.Errorf("%s: received unexpected message type %d", protocolName, msg.Type())
7276
}
7377
return err
7478
}
@@ -82,7 +86,7 @@ func (c *Client) handleAcceptVersion(msgGeneric protocol.Message) error {
8286
if c.Mode() == protocol.ProtocolModeNodeToNode {
8387
versionData := msg.VersionData.([]interface{})
8488
//nolint:gosimple
85-
if versionData[1].(bool) == DIFFUSION_MODE_INITIATOR_AND_RESPONDER {
89+
if versionData[1].(bool) == DiffusionModeInitiatorAndResponder {
8690
fullDuplex = true
8791
}
8892
}
@@ -93,12 +97,12 @@ func (c *Client) handleRefuse(msgGeneric protocol.Message) error {
9397
msg := msgGeneric.(*MsgRefuse)
9498
var err error
9599
switch msg.Reason[0].(uint64) {
96-
case REFUSE_REASON_VERSION_MISMATCH:
97-
err = fmt.Errorf("%s: version mismatch", PROTOCOL_NAME)
98-
case REFUSE_REASON_DECODE_ERROR:
99-
err = fmt.Errorf("%s: decode error: %s", PROTOCOL_NAME, msg.Reason[2].(string))
100-
case REFUSE_REASON_REFUSED:
101-
err = fmt.Errorf("%s: refused: %s", PROTOCOL_NAME, msg.Reason[2].(string))
100+
case RefuseReasonVersionMismatch:
101+
err = fmt.Errorf("%s: version mismatch", protocolName)
102+
case RefuseReasonDecodeError:
103+
err = fmt.Errorf("%s: decode error: %s", protocolName, msg.Reason[2].(string))
104+
case RefuseReasonRefused:
105+
err = fmt.Errorf("%s: refused: %s", protocolName, msg.Reason[2].(string))
102106
}
103107
return err
104108
}

‎protocol/handshake/handshake.go‎

Lines changed: 33 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Package handshake implements the Ouroboros handshake protocol
12
package handshake
23

34
import (
@@ -6,53 +7,60 @@ import (
67
"github.com/cloudstruct/go-ouroboros-network/protocol"
78
)
89

10+
// Protocol identifiers
911
const (
10-
PROTOCOL_NAME = "handshake"
11-
PROTOCOL_ID = 0
12+
protocolName = "handshake"
13+
protocolId = 0
14+
)
1215

13-
DIFFUSION_MODE_INITIATOR_ONLY = false
14-
DIFFUSION_MODE_INITIATOR_AND_RESPONDER = true
16+
// Diffusion modes
17+
const (
18+
DiffusionModeInitiatorOnly = false
19+
DiffusionModeInitiatorAndResponder = true
1520
)
1621

1722
var (
18-
STATE_PROPOSE = protocol.NewState(1, "Propose")
19-
STATE_CONFIRM = protocol.NewState(2, "Confirm")
20-
STATE_DONE = protocol.NewState(3, "Done")
23+
statePropose = protocol.NewState(1, "Propose")
24+
stateConfirm = protocol.NewState(2, "Confirm")
25+
stateDone = protocol.NewState(3, "Done")
2126
)
2227

28+
// Handshake protocol state machine
2329
var StateMap = protocol.StateMap{
24-
STATE_PROPOSE: protocol.StateMapEntry{
30+
statePropose: protocol.StateMapEntry{
2531
Agency: protocol.AgencyClient,
2632
Transitions: []protocol.StateTransition{
2733
{
28-
MsgType: MESSAGE_TYPE_PROPOSE_VERSIONS,
29-
NewState: STATE_CONFIRM,
34+
MsgType: MessageTypeProposeVersions,
35+
NewState: stateConfirm,
3036
},
3137
},
3238
},
33-
STATE_CONFIRM: protocol.StateMapEntry{
39+
stateConfirm: protocol.StateMapEntry{
3440
Agency: protocol.AgencyServer,
3541
Transitions: []protocol.StateTransition{
3642
{
37-
MsgType: MESSAGE_TYPE_ACCEPT_VERSION,
38-
NewState: STATE_DONE,
43+
MsgType: MessageTypeAcceptVersion,
44+
NewState: stateDone,
3945
},
4046
{
41-
MsgType: MESSAGE_TYPE_REFUSE,
42-
NewState: STATE_DONE,
47+
MsgType: MessageTypeRefuse,
48+
NewState: stateDone,
4349
},
4450
},
4551
},
46-
STATE_DONE: protocol.StateMapEntry{
52+
stateDone: protocol.StateMapEntry{
4753
Agency: protocol.AgencyNone,
4854
},
4955
}
5056

57+
// Handshake is a wrapper object that holds the client and server instances
5158
type Handshake struct {
5259
Client *Client
5360
Server *Server
5461
}
5562

63+
// Config is used to configure the Handshake protocol instance
5664
type Config struct {
5765
ProtocolVersions []uint16
5866
NetworkMagic uint32
@@ -61,8 +69,10 @@ type Config struct {
6169
Timeout time.Duration
6270
}
6371

72+
// Callback function types
6473
type FinishedFunc func(uint16, bool) error
6574

75+
// New returns a new Handshake object
6676
func New(protoOptions protocol.ProtocolOptions, cfg *Config) *Handshake {
6777
h := &Handshake{
6878
Client: NewClient(protoOptions, cfg),
@@ -71,8 +81,10 @@ func New(protoOptions protocol.ProtocolOptions, cfg *Config) *Handshake {
7181
return h
7282
}
7383

84+
// HandshakeOptionFunc represents a function used to modify the Handshake protocol config
7485
type HandshakeOptionFunc func(*Config)
7586

87+
// NewConfig returns a new Handshake config object with the provided options
7688
func NewConfig(options ...HandshakeOptionFunc) Config {
7789
c := Config{
7890
Timeout: 5 * time.Second,
@@ -84,30 +96,35 @@ func NewConfig(options ...HandshakeOptionFunc) Config {
8496
return c
8597
}
8698

99+
// WithProtocolVersions specifies the supported protocol versions
87100
func WithProtocolVersions(versions []uint16) HandshakeOptionFunc {
88101
return func(c *Config) {
89102
c.ProtocolVersions = versions
90103
}
91104
}
92105

106+
// WithNetworkMagic specifies the network magic value
93107
func WithNetworkMagic(networkMagic uint32) HandshakeOptionFunc {
94108
return func(c *Config) {
95109
c.NetworkMagic = networkMagic
96110
}
97111
}
98112

113+
// WithClientFullDuplex specifies whether to request full duplex mode when acting as a client
99114
func WithClientFullDuplex(fullDuplex bool) HandshakeOptionFunc {
100115
return func(c *Config) {
101116
c.ClientFullDuplex = fullDuplex
102117
}
103118
}
104119

120+
// WithFinishedFunc specifies the Finished callback function
105121
func WithFinishedFunc(finishedFunc FinishedFunc) HandshakeOptionFunc {
106122
return func(c *Config) {
107123
c.FinishedFunc = finishedFunc
108124
}
109125
}
110126

127+
// WithTimeout specifies the timeout for the handshake operation
111128
func WithTimeout(timeout time.Duration) HandshakeOptionFunc {
112129
return func(c *Config) {
113130
c.Timeout = timeout

‎protocol/handshake/messages.go‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,38 @@ package handshake
22

33
import (
44
"fmt"
5+
56
"github.com/cloudstruct/go-ouroboros-network/protocol"
67
"github.com/cloudstruct/go-ouroboros-network/utils"
78
)
89

10+
// Message types
911
const (
10-
MESSAGE_TYPE_PROPOSE_VERSIONS = 0
11-
MESSAGE_TYPE_ACCEPT_VERSION = 1
12-
MESSAGE_TYPE_REFUSE = 2
12+
MessageTypeProposeVersions = 0
13+
MessageTypeAcceptVersion = 1
14+
MessageTypeRefuse = 2
15+
)
1316

14-
REFUSE_REASON_VERSION_MISMATCH = 0
15-
REFUSE_REASON_DECODE_ERROR = 1
16-
REFUSE_REASON_REFUSED = 2
17+
// Refusal reasons
18+
const (
19+
RefuseReasonVersionMismatch = 0
20+
RefuseReasonDecodeError = 1
21+
RefuseReasonRefused = 2
1722
)
1823

24+
// NewMsgFromCbor parses a Handshake message from CBOR
1925
func NewMsgFromCbor(msgType uint, data []byte) (protocol.Message, error) {
2026
var ret protocol.Message
2127
switch msgType {
22-
case MESSAGE_TYPE_PROPOSE_VERSIONS:
28+
case MessageTypeProposeVersions:
2329
ret = &MsgProposeVersions{}
24-
case MESSAGE_TYPE_ACCEPT_VERSION:
30+
case MessageTypeAcceptVersion:
2531
ret = &MsgAcceptVersion{}
26-
case MESSAGE_TYPE_REFUSE:
32+
case MessageTypeRefuse:
2733
ret = &MsgRefuse{}
2834
}
2935
if _, err := utils.CborDecode(data, ret); err != nil {
30-
return nil, fmt.Errorf("%s: decode error: %s", PROTOCOL_NAME, err)
36+
return nil, fmt.Errorf("%s: decode error: %s", protocolName, err)
3137
}
3238
if ret != nil {
3339
// Store the raw message CBOR
@@ -44,7 +50,7 @@ type MsgProposeVersions struct {
4450
func NewMsgProposeVersions(versionMap map[uint16]interface{}) *MsgProposeVersions {
4551
m := &MsgProposeVersions{
4652
MessageBase: protocol.MessageBase{
47-
MessageType: MESSAGE_TYPE_PROPOSE_VERSIONS,
53+
MessageType: MessageTypeProposeVersions,
4854
},
4955
VersionMap: versionMap,
5056
}
@@ -60,7 +66,7 @@ type MsgAcceptVersion struct {
6066
func NewMsgAcceptVersion(version uint16, versionData interface{}) *MsgAcceptVersion {
6167
m := &MsgAcceptVersion{
6268
MessageBase: protocol.MessageBase{
63-
MessageType: MESSAGE_TYPE_ACCEPT_VERSION,
69+
MessageType: MessageTypeAcceptVersion,
6470
},
6571
Version: version,
6672
VersionData: versionData,
@@ -76,7 +82,7 @@ type MsgRefuse struct {
7682
func NewMsgRefuse(reason []interface{}) *MsgRefuse {
7783
m := &MsgRefuse{
7884
MessageBase: protocol.MessageBase{
79-
MessageType: MESSAGE_TYPE_REFUSE,
85+
MessageType: MessageTypeRefuse,
8086
},
8187
Reason: reason,
8288
}

‎protocol/handshake/messages_test.go‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@ package handshake
22

33
import (
44
"encoding/hex"
5-
"github.com/cloudstruct/go-ouroboros-network/protocol"
6-
"github.com/cloudstruct/go-ouroboros-network/utils"
75
"reflect"
86
"testing"
7+
8+
"github.com/cloudstruct/go-ouroboros-network/protocol"
9+
"github.com/cloudstruct/go-ouroboros-network/utils"
910
)
1011

1112
type testDefinition struct {
@@ -17,7 +18,7 @@ type testDefinition struct {
1718
var tests = []testDefinition{
1819
{
1920
CborHex: "8200a4078202f4088202f4098202f40a8202f4",
20-
MessageType: MESSAGE_TYPE_PROPOSE_VERSIONS,
21+
MessageType: MessageTypeProposeVersions,
2122
Message: NewMsgProposeVersions(
2223
map[uint16]interface{}{
2324
7: []interface{}{uint64(2), false},
@@ -29,15 +30,15 @@ var tests = []testDefinition{
2930
},
3031
{
3132
CborHex: "83010a8202f4",
32-
MessageType: MESSAGE_TYPE_ACCEPT_VERSION,
33+
MessageType: MessageTypeAcceptVersion,
3334
Message: NewMsgAcceptVersion(10, []interface{}{uint64(2), false}),
3435
},
3536
{
3637
CborHex: "82028200840708090a",
37-
MessageType: MESSAGE_TYPE_REFUSE,
38+
MessageType: MessageTypeRefuse,
3839
Message: NewMsgRefuse(
3940
[]interface{}{
40-
uint64(REFUSE_REASON_VERSION_MISMATCH),
41+
uint64(RefuseReasonVersionMismatch),
4142
[]interface{}{
4243
uint64(7),
4344
uint64(8),

0 commit comments

Comments
 (0)