Skip to content

Commit cb421c9

Browse files
agaffneyagaffney
authored
Merge pull request #190 from cloudstruct/docs/protocol-localtxsubmission-package
docs: code docs for protocol/localtxsubmission
2 parents 0c7536c + d6f58ae commit cb421c9

File tree

6 files changed

+65
-45
lines changed

6 files changed

+65
-45
lines changed

‎protocol/localtxsubmission/client.go‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,15 @@ import (
77
"sync"
88
)
99

10+
// Client implements the LocalTxSubmission client
1011
type Client struct {
1112
*protocol.Protocol
1213
config *Config
1314
busyMutex sync.Mutex
1415
submitResultChan chan error
1516
}
1617

18+
// NewClient returns a new LocalTxSubmission client object
1719
func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
1820
if cfg == nil {
1921
tmpCfg := NewConfig()
@@ -25,22 +27,22 @@ func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
2527
}
2628
// Update state map with timeout
2729
stateMap := StateMap.Copy()
28-
if entry, ok := stateMap[STATE_BUSY]; ok {
30+
if entry, ok := stateMap[stateBusy]; ok {
2931
entry.Timeout = c.config.Timeout
30-
stateMap[STATE_BUSY] = entry
32+
stateMap[stateBusy] = entry
3133
}
3234
// Configure underlying Protocol
3335
protoConfig := protocol.ProtocolConfig{
34-
Name: PROTOCOL_NAME,
35-
ProtocolId: PROTOCOL_ID,
36+
Name: protocolName,
37+
ProtocolId: protocolId,
3638
Muxer: protoOptions.Muxer,
3739
ErrorChan: protoOptions.ErrorChan,
3840
Mode: protoOptions.Mode,
3941
Role: protocol.ProtocolRoleClient,
4042
MessageHandlerFunc: c.messageHandler,
4143
MessageFromCborFunc: NewMsgFromCbor,
4244
StateMap: stateMap,
43-
InitialState: STATE_IDLE,
45+
InitialState: stateIdle,
4446
}
4547
c.Protocol = protocol.New(protoConfig)
4648
// Start goroutine to cleanup resources on protocol shutdown
@@ -54,16 +56,17 @@ func NewClient(protoOptions protocol.ProtocolOptions, cfg *Config) *Client {
5456
func (c *Client) messageHandler(msg protocol.Message, isResponse bool) error {
5557
var err error
5658
switch msg.Type() {
57-
case MESSAGE_TYPE_ACCEPT_TX:
59+
case MessageTypeAcceptTx:
5860
err = c.handleAcceptTx()
59-
case MESSAGE_TYPE_REJECT_TX:
61+
case MessageTypeRejectTx:
6062
err = c.handleRejectTx(msg)
6163
default:
62-
err = fmt.Errorf("%s: received unexpected message type %d", PROTOCOL_NAME, msg.Type())
64+
err = fmt.Errorf("%s: received unexpected message type %d", protocolName, msg.Type())
6365
}
6466
return err
6567
}
6668

69+
// SubmitTx submits a transaction using the specified transaction era ID and TX payload
6770
func (c *Client) SubmitTx(eraId uint16, tx []byte) error {
6871
c.busyMutex.Lock()
6972
defer c.busyMutex.Unlock()
@@ -75,6 +78,7 @@ func (c *Client) SubmitTx(eraId uint16, tx []byte) error {
7578
return err
7679
}
7780

81+
// Stop transations the protocol to the Done state. No more operations will be possible
7882
func (c *Client) Stop() error {
7983
c.busyMutex.Lock()
8084
defer c.busyMutex.Unlock()

‎protocol/localtxsubmission/error.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import (
44
"fmt"
55
)
66

7+
// TransactionRejectedError represents an explicit transaction rejection
78
type TransactionRejectedError struct {
89
ReasonCbor []byte
910
Reason error

‎protocol/localtxsubmission/localtxsubmission.go‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Package localtxsubmission implements the Ouroboros local-tx-submission protocol
12
package localtxsubmission
23

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

10+
// Protocol identifiers
911
const (
10-
PROTOCOL_NAME = "local-tx-submission"
11-
PROTOCOL_ID uint16 = 6
12+
protocolName = "local-tx-submission"
13+
protocolId uint16 = 6
1214
)
1315

1416
var (
15-
STATE_IDLE = protocol.NewState(1, "Idle")
16-
STATE_BUSY = protocol.NewState(2, "Busy")
17-
STATE_DONE = protocol.NewState(3, "Done")
17+
stateIdle = protocol.NewState(1, "Idle")
18+
stateBusy = protocol.NewState(2, "Busy")
19+
stateDone = protocol.NewState(3, "Done")
1820
)
1921

22+
// LocalTxSubmission protocol state machine
2023
var StateMap = protocol.StateMap{
21-
STATE_IDLE: protocol.StateMapEntry{
24+
stateIdle: protocol.StateMapEntry{
2225
Agency: protocol.AgencyClient,
2326
Transitions: []protocol.StateTransition{
2427
{
25-
MsgType: MESSAGE_TYPE_SUBMIT_TX,
26-
NewState: STATE_BUSY,
28+
MsgType: MessageTypeSubmitTx,
29+
NewState: stateBusy,
2730
},
2831
},
2932
},
30-
STATE_BUSY: protocol.StateMapEntry{
33+
stateBusy: protocol.StateMapEntry{
3134
Agency: protocol.AgencyServer,
3235
Transitions: []protocol.StateTransition{
3336
{
34-
MsgType: MESSAGE_TYPE_ACCEPT_TX,
35-
NewState: STATE_IDLE,
37+
MsgType: MessageTypeAcceptTx,
38+
NewState: stateIdle,
3639
},
3740
{
38-
MsgType: MESSAGE_TYPE_REJECT_TX,
39-
NewState: STATE_IDLE,
41+
MsgType: MessageTypeRejectTx,
42+
NewState: stateIdle,
4043
},
4144
},
4245
},
43-
STATE_DONE: protocol.StateMapEntry{
46+
stateDone: protocol.StateMapEntry{
4447
Agency: protocol.AgencyNone,
4548
},
4649
}
4750

51+
// LocalTxSubmission is a wrapper object that holds the client and server instances
4852
type LocalTxSubmission struct {
4953
Client *Client
5054
Server *Server
5155
}
5256

57+
// Config is used to configure the LocalTxSubmission protocol instance
5358
type Config struct {
5459
SubmitTxFunc SubmitTxFunc
5560
Timeout time.Duration
@@ -58,6 +63,7 @@ type Config struct {
5863
// Callback function types
5964
type SubmitTxFunc func(interface{}) error
6065

66+
// New returns a new LocalTxSubmission object
6167
func New(protoOptions protocol.ProtocolOptions, cfg *Config) *LocalTxSubmission {
6268
l := &LocalTxSubmission{
6369
Client: NewClient(protoOptions, cfg),
@@ -66,8 +72,10 @@ func New(protoOptions protocol.ProtocolOptions, cfg *Config) *LocalTxSubmission
6672
return l
6773
}
6874

75+
// LocalTxSubmissionOptionFunc represents a function used to modify the LocalTxSubmission protocol config
6976
type LocalTxSubmissionOptionFunc func(*Config)
7077

78+
// NewConfig returns a new LocalTxSubmission config object with the provided options
7179
func NewConfig(options ...LocalTxSubmissionOptionFunc) Config {
7280
c := Config{
7381
Timeout: 30 * time.Second,
@@ -79,12 +87,14 @@ func NewConfig(options ...LocalTxSubmissionOptionFunc) Config {
7987
return c
8088
}
8189

90+
// WithSubmitTxFunc specifies the callback function when a TX is submitted when acting as a server
8291
func WithSubmitTxFunc(submitTxFunc SubmitTxFunc) LocalTxSubmissionOptionFunc {
8392
return func(c *Config) {
8493
c.SubmitTxFunc = submitTxFunc
8594
}
8695
}
8796

97+
// WithTimeout specifies the timeout for a TX submit operation when acting as a client
8898
func WithTimeout(timeout time.Duration) LocalTxSubmissionOptionFunc {
8999
return func(c *Config) {
90100
c.Timeout = timeout

‎protocol/localtxsubmission/messages.go‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,35 @@ package localtxsubmission
22

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

11+
// Message types
1012
const (
11-
MESSAGE_TYPE_SUBMIT_TX = 0
12-
MESSAGE_TYPE_ACCEPT_TX = 1
13-
MESSAGE_TYPE_REJECT_TX = 2
14-
MESSAGE_TYPE_DONE = 3
13+
MessageTypeSubmitTx = 0
14+
MessageTypeAcceptTx = 1
15+
MessageTypeRejectTx = 2
16+
MessageTypeDone = 3
1517
)
1618

19+
// NewMsgFromCbor parses a LocalTxSubmission message from CBOR
1720
func NewMsgFromCbor(msgType uint, data []byte) (protocol.Message, error) {
1821
var ret protocol.Message
1922
switch msgType {
20-
case MESSAGE_TYPE_SUBMIT_TX:
23+
case MessageTypeSubmitTx:
2124
ret = &MsgSubmitTx{}
22-
case MESSAGE_TYPE_ACCEPT_TX:
25+
case MessageTypeAcceptTx:
2326
ret = &MsgAcceptTx{}
24-
case MESSAGE_TYPE_REJECT_TX:
27+
case MessageTypeRejectTx:
2528
ret = &MsgRejectTx{}
26-
case MESSAGE_TYPE_DONE:
29+
case MessageTypeDone:
2730
ret = &MsgDone{}
2831
}
2932
if _, err := utils.CborDecode(data, ret); err != nil {
30-
return nil, fmt.Errorf("%s: decode error: %s", PROTOCOL_NAME, err)
33+
return nil, fmt.Errorf("%s: decode error: %s", protocolName, err)
3134
}
3235
if ret != nil {
3336
// Store the raw message CBOR
@@ -51,7 +54,7 @@ type MsgSubmitTxTransaction struct {
5154
func NewMsgSubmitTx(eraId uint16, tx []byte) *MsgSubmitTx {
5255
m := &MsgSubmitTx{
5356
MessageBase: protocol.MessageBase{
54-
MessageType: MESSAGE_TYPE_SUBMIT_TX,
57+
MessageType: MessageTypeSubmitTx,
5558
},
5659
Transaction: MsgSubmitTxTransaction{
5760
EraId: eraId,
@@ -72,7 +75,7 @@ type MsgAcceptTx struct {
7275
func NewMsgAcceptTx() *MsgAcceptTx {
7376
m := &MsgAcceptTx{
7477
MessageBase: protocol.MessageBase{
75-
MessageType: MESSAGE_TYPE_ACCEPT_TX,
78+
MessageType: MessageTypeAcceptTx,
7679
},
7780
}
7881
return m
@@ -88,7 +91,7 @@ type MsgRejectTx struct {
8891
func NewMsgRejectTx(reasonCbor []byte) *MsgRejectTx {
8992
m := &MsgRejectTx{
9093
MessageBase: protocol.MessageBase{
91-
MessageType: MESSAGE_TYPE_REJECT_TX,
94+
MessageType: MessageTypeRejectTx,
9295
},
9396
Reason: cbor.RawMessage(reasonCbor),
9497
}
@@ -102,7 +105,7 @@ type MsgDone struct {
102105
func NewMsgDone() *MsgDone {
103106
m := &MsgDone{
104107
MessageBase: protocol.MessageBase{
105-
MessageType: MESSAGE_TYPE_DONE,
108+
MessageType: MessageTypeDone,
106109
},
107110
}
108111
return m

‎protocol/localtxsubmission/messages_test.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,23 +39,23 @@ var placeholderRejectError = hexDecode("820204")
3939
var tests = []testDefinition{
4040
{
4141
CborHex: fmt.Sprintf("82008204d81846%x", placeholderTx),
42-
MessageType: MESSAGE_TYPE_SUBMIT_TX,
42+
MessageType: MessageTypeSubmitTx,
4343
Message: NewMsgSubmitTx(ledger.TX_TYPE_ALONZO, placeholderTx),
4444
},
4545
{
4646
CborHex: "8101",
4747
Message: NewMsgAcceptTx(),
48-
MessageType: MESSAGE_TYPE_ACCEPT_TX,
48+
MessageType: MessageTypeAcceptTx,
4949
},
5050
{
5151
CborHex: fmt.Sprintf("8202%x", placeholderRejectError),
52-
MessageType: MESSAGE_TYPE_REJECT_TX,
52+
MessageType: MessageTypeRejectTx,
5353
Message: NewMsgRejectTx(placeholderRejectError),
5454
},
5555
{
5656
CborHex: "8103",
5757
Message: NewMsgDone(),
58-
MessageType: MESSAGE_TYPE_DONE,
58+
MessageType: MessageTypeDone,
5959
},
6060
}
6161

‎protocol/localtxsubmission/server.go‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,26 +5,28 @@ import (
55
"github.com/cloudstruct/go-ouroboros-network/protocol"
66
)
77

8+
// Server implements the LocalTxSubmission server
89
type Server struct {
910
*protocol.Protocol
1011
config *Config
1112
}
1213

14+
// NewServer returns a new Server object
1315
func NewServer(protoOptions protocol.ProtocolOptions, cfg *Config) *Server {
1416
s := &Server{
1517
config: cfg,
1618
}
1719
protoConfig := protocol.ProtocolConfig{
18-
Name: PROTOCOL_NAME,
19-
ProtocolId: PROTOCOL_ID,
20+
Name: protocolName,
21+
ProtocolId: protocolId,
2022
Muxer: protoOptions.Muxer,
2123
ErrorChan: protoOptions.ErrorChan,
2224
Mode: protoOptions.Mode,
2325
Role: protocol.ProtocolRoleServer,
2426
MessageHandlerFunc: s.messageHandler,
2527
MessageFromCborFunc: NewMsgFromCbor,
2628
StateMap: StateMap,
27-
InitialState: STATE_IDLE,
29+
InitialState: stateIdle,
2830
}
2931
s.Protocol = protocol.New(protoConfig)
3032
return s
@@ -33,12 +35,12 @@ func NewServer(protoOptions protocol.ProtocolOptions, cfg *Config) *Server {
3335
func (s *Server) messageHandler(msg protocol.Message, isResponse bool) error {
3436
var err error
3537
switch msg.Type() {
36-
case MESSAGE_TYPE_SUBMIT_TX:
38+
case MessageTypeSubmitTx:
3739
err = s.handleSubmitTx(msg)
38-
case MESSAGE_TYPE_DONE:
40+
case MessageTypeDone:
3941
err = s.handleDone()
4042
default:
41-
err = fmt.Errorf("%s: received unexpected message type %d", PROTOCOL_NAME, msg.Type())
43+
err = fmt.Errorf("%s: received unexpected message type %d", protocolName, msg.Type())
4244
}
4345
return err
4446
}

0 commit comments

Comments
 (0)