Merge pull request #185 from cloudstruct/docs/ouroboros-package

docs: code docs for ouroboros package

Author: agaffney

cmd/go-ouroboros-network/chainsync.go

@@ -129,16 +129,16 @@ func testChainSync(f *globalFlags) {
 		fmt.Printf("ERROR: %s\n", err)
 		os.Exit(1)
 	}
-	o.ChainSync.Client.Start()
+	o.ChainSync().Client.Start()
 	if f.ntnProto {
-		o.BlockFetch.Client.Start()
+		o.BlockFetch().Client.Start()
 	}
 
 	syncState.oConn = o
 	syncState.nodeToNode = f.ntnProto
 	var point common.Point
 	if chainSyncFlags.tip {
-		tip, err := o.ChainSync.Client.GetCurrentTip()
+		tip, err := o.ChainSync().Client.GetCurrentTip()
 		if err != nil {
 			fmt.Printf("ERROR: failed to get current tip: %s\n", err)
 			os.Exit(1)
@@ -153,7 +153,7 @@ func testChainSync(f *globalFlags) {
 	} else {
 		point = common.NewPointOrigin()
 	}
-	if err := o.ChainSync.Client.Sync([]common.Point{point}); err != nil {
+	if err := o.ChainSync().Client.Sync([]common.Point{point}); err != nil {
 		fmt.Printf("ERROR: failed to start chain-sync: %s\n", err)
 		os.Exit(1)
 	}
@@ -194,7 +194,7 @@ func chainSyncRollForwardHandler(blockType uint, blockData interface{}, tip chai
 			blockSlot = h.Body.Slot
 			blockHash, _ = hex.DecodeString(h.Id())
 		}
-		if err := syncState.oConn.BlockFetch.Client.RequestRange([]interface{}{blockSlot, blockHash}, []interface{}{blockSlot, blockHash}); err != nil {
+		if err := syncState.oConn.BlockFetch().Client.RequestRange([]interface{}{blockSlot, blockHash}, []interface{}{blockSlot, blockHash}); err != nil {
 			fmt.Printf("error calling RequestRange: %s\n", err)
 			return err
 		}

cmd/go-ouroboros-network/localtxsubmission.go

@@ -64,7 +64,7 @@ func testLocalTxSubmission(f *globalFlags) {
 		fmt.Printf("ERROR: %s\n", err)
 		os.Exit(1)
 	}
-	o.LocalTxSubmission.Client.Start()
+	o.LocalTxSubmission().Client.Start()
 
 	var txBytes []byte
 	if localTxSubmissionFlags.txFile != "" {
@@ -94,7 +94,7 @@ func testLocalTxSubmission(f *globalFlags) {
 		}
 	}
 
-	if err = o.LocalTxSubmission.Client.SubmitTx(ledger.TX_TYPE_ALONZO, txBytes); err != nil {
+	if err = o.LocalTxSubmission().Client.SubmitTx(ledger.TX_TYPE_ALONZO, txBytes); err != nil {
 		fmt.Printf("Error submitting transaction: %s\n", err)
 		os.Exit(1)
 	}

cmd/go-ouroboros-network/mem_usage.go

@@ -71,9 +71,9 @@ func testMemUsage(f *globalFlags) {
 			fmt.Printf("ERROR: %s\n", err)
 			os.Exit(1)
 		}
-		o.ChainSync.Client.Start()
+		o.ChainSync().Client.Start()
 
-		tip, err := o.ChainSync.Client.GetCurrentTip()
+		tip, err := o.ChainSync().Client.GetCurrentTip()
 		if err != nil {
 			fmt.Printf("ERROR: %s\n", err)
 			os.Exit(1)

cmd/go-ouroboros-network/query.go

@@ -56,47 +56,47 @@ func testQuery(f *globalFlags) {
 		fmt.Printf("ERROR: %s\n", err)
 		os.Exit(1)
 	}
-	o.LocalStateQuery.Client.Start()
+	o.LocalStateQuery().Client.Start()
 
 	switch queryFlags.flagset.Args()[0] {
 	case "current-era":
-		era, err := o.LocalStateQuery.Client.GetCurrentEra()
+		era, err := o.LocalStateQuery().Client.GetCurrentEra()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying current era: %s\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("current-era: %d\n", era)
 	case "tip":
-		era, err := o.LocalStateQuery.Client.GetCurrentEra()
+		era, err := o.LocalStateQuery().Client.GetCurrentEra()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying current era: %s\n", err)
 			os.Exit(1)
 		}
-		epochNo, err := o.LocalStateQuery.Client.GetEpochNo()
+		epochNo, err := o.LocalStateQuery().Client.GetEpochNo()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying current epoch: %s\n", err)
 			os.Exit(1)
 		}
-		blockNo, err := o.LocalStateQuery.Client.GetChainBlockNo()
+		blockNo, err := o.LocalStateQuery().Client.GetChainBlockNo()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying current chain block number: %s\n", err)
 			os.Exit(1)
 		}
-		point, err := o.LocalStateQuery.Client.GetChainPoint()
+		point, err := o.LocalStateQuery().Client.GetChainPoint()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying current chain point: %s\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("tip: era = %d, epoch = %d, blockNo = %d, slot = %d, hash = %x\n", era, epochNo, blockNo, point.Slot, point.Hash)
 	case "system-start":
-		systemStart, err := o.LocalStateQuery.Client.GetSystemStart()
+		systemStart, err := o.LocalStateQuery().Client.GetSystemStart()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying system start: %s\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("system-start: year = %d, day = %d, picoseconds = %d\n", systemStart.Year, systemStart.Day, systemStart.Picoseconds)
 	case "era-history":
-		eraHistory, err := o.LocalStateQuery.Client.GetEraHistory()
+		eraHistory, err := o.LocalStateQuery().Client.GetEraHistory()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying era history: %s\n", err)
 			os.Exit(1)
@@ -106,21 +106,21 @@ func testQuery(f *globalFlags) {
 			fmt.Printf("id = %d, begin slot/epoch = %d/%d, end slot/epoch = %d/%d, epoch length = %d, slot length (ms) = %d, slots per KES period = %d\n", eraId, era.Begin.SlotNo, era.Begin.EpochNo, era.End.SlotNo, era.End.EpochNo, era.Params.EpochLength, era.Params.SlotLength, era.Params.SlotsPerKESPeriod.Value)
 		}
 	case "protocol-params":
-		protoParams, err := o.LocalStateQuery.Client.GetCurrentProtocolParams()
+		protoParams, err := o.LocalStateQuery().Client.GetCurrentProtocolParams()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying protocol params: %s\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("protocol-params: %#v\n", *protoParams)
 	case "stake-distribution":
-		stakeDistribution, err := o.LocalStateQuery.Client.GetStakeDistribution()
+		stakeDistribution, err := o.LocalStateQuery().Client.GetStakeDistribution()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying stake distribution: %s\n", err)
 			os.Exit(1)
 		}
 		fmt.Printf("stake-distribution: %#v\n", *stakeDistribution)
 	case "genesis-config":
-		genesisConfig, err := o.LocalStateQuery.Client.GetGenesisConfig()
+		genesisConfig, err := o.LocalStateQuery().Client.GetGenesisConfig()
 		if err != nil {
 			fmt.Printf("ERROR: failure querying genesis config: %s\n", err)
 			os.Exit(1)

options.go

@@ -10,86 +10,103 @@ import (
 	"net"
 )
 
+// OuroborosOptionFunc is a type that represents functions that modify the Ouroboros config
 type OuroborosOptionFunc func(*Ouroboros)
 
+// WithConnection specifies an existing connection to use. If none is provided, the Dial() function can be
+// used to create one later
 func WithConnection(conn net.Conn) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.conn = conn
 	}
 }
 
+// WithNetworkMagic specifies the network magic value
 func WithNetworkMagic(networkMagic uint32) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.networkMagic = networkMagic
 	}
 }
 
+// WithErrorChan specifies the error channel to use. If none is provided, one will be created
 func WithErrorChan(errorChan chan error) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
-		o.ErrorChan = errorChan
+		o.errorChan = errorChan
 	}
 }
 
+// WithServer specifies whether to act as a server
 func WithServer(server bool) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.server = server
 	}
 }
 
+// WithNodeToNode specifies whether to use the node-to-node protocol. The default is to use node-to-client
 func WithNodeToNode(nodeToNode bool) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.useNodeToNodeProto = nodeToNode
 	}
 }
 
+// WithKeepAlives specifies whether to use keep-alives. This is disabled by default
 func WithKeepAlive(keepAlive bool) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.sendKeepAlives = keepAlive
 	}
 }
 
+// WithDelayMuxerStart specifies whether to delay the muxer start. This is useful if you need to take some
+// custom actions before the muxer starts processing messages, generally when acting as a server
 func WithDelayMuxerStart(delayMuxerStart bool) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.delayMuxerStart = delayMuxerStart
 	}
 }
 
+// WithFullDuplex specifies whether to enable full-duplex mode when acting as a client
 func WithFullDuplex(fullDuplex bool) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.fullDuplex = fullDuplex
 	}
 }
 
+// WithBlockFetchConfig specifies BlockFetch protocol config
 func WithBlockFetchConfig(cfg blockfetch.Config) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.blockFetchConfig = &cfg
 	}
 }
 
+// WithChainSyncConfig secifies ChainSync protocol config
 func WithChainSyncConfig(cfg chainsync.Config) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.chainSyncConfig = &cfg
 	}
 }
 
+// WithKeepAliveConfig specifies KeepAlive protocol config
 func WithKeepAliveConfig(cfg keepalive.Config) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.keepAliveConfig = &cfg
 	}
 }
 
+// WithLocalStateQueryConfig specifies LocalStateQuery protocol config
 func WithLocalStateQueryConfig(cfg localstatequery.Config) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.localStateQueryConfig = &cfg
 	}
 }
 
+// WithLocalTxSubmissionConfig specifies LocalTxSubmission protocol config
 func WithLocalTxSubmissionConfig(cfg localtxsubmission.Config) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.localTxSubmissionConfig = &cfg
 	}
 }
 
+// WithTxSubmissionConfig specifies TxSubmission protocol config
 func WithTxSubmissionConfig(cfg txsubmission.Config) OuroborosOptionFunc {
 	return func(o *Ouroboros) {
 		o.txSubmissionConfig = &cfg