stratum

README

Stratum

A portable library to manage a stratum client or server. This was created to isolate the more challenging (asynchronous) logic of TCP clients and servers, so that they can be tested separately from heavily asynchronous client and server implementations. Though the client is more "useful" since it has more functionality, the server is still extremely valuable to have a plug and play TCP listener with connection management. For both the client and the server, TLS support will eventually be added.

The client is fairly generalized, only with some bias on the requirement of the handshake request (usually mining.subscribe, or eth_submitLogin). It automatically manages reconnects and JSON RPC request ID management, so that it can properly associate requests and their responses asynchronously. The client is completely thread-safe and generally used in that way. It does not, however, manage multi-host rotation and prioritization, since that is the purpose of the TCPPool in pkg/hostpool. The only thing missing is probably batch request and multiple (or sequential) handshake request support (like mining.subscribe and mining.authorize).

The server is a little bit more generalized since the server Conn has some specific needs with data store in the client. Currently this is managed through getters and setters, though it could become an interface that the user implements if this becomes too cumbersome. For all current needs, it works well. The server implements no routing and leaves that up to the user, it is merely meant to be a convenient wrapper for net.Listener and the corresponding list of net.Conns. One thing that could be implemented is better backoff for disconnecting clients when the server is shut down instead of disconnecting them all at once (which can have adverse affects for the clients in production).

Documentation

Index

• Variables
• type Client
  • func NewClient(ctx context.Context, host string, timeout, reconnect time.Duration) *Client
  • func (c *Client) ForceReconnect()
  • func (c *Client) Start(handshakeReqs []*rpc.Request) (chan *rpc.Request, chan *rpc.Response, chan error)
  • func (c *Client) URL() string
  • func (c *Client) WaitForHandshake(timeout time.Duration) error
  • func (c *Client) WriteRequest(req *rpc.Request) (*rpc.Response, error)
  • func (c *Client) WriteRequestWithTimeout(req *rpc.Request, timeout time.Duration) (*rpc.Response, error)
  • func (c *Client) WriteResponse(res *rpc.Response) error
• type Conn
  • func NewConn(id uint64, port int, ip string, enableVarDiff bool, rawConn net.Conn) *Conn
  • func (c *Conn) Close()
  • func (c *Conn) GetAuthorized() bool
  • func (c *Conn) GetClient() string
  • func (c *Conn) GetClientType() int
  • func (c *Conn) GetCompoundID() string
  • func (c *Conn) GetDiffFactor() int
  • func (c *Conn) GetErrorCount() int
  • func (c *Conn) GetExtraNonce() string
  • func (c *Conn) GetExtraNonceSubscribed() bool
  • func (c *Conn) GetID() uint64
  • func (c *Conn) GetIP() string
  • func (c *Conn) GetIsSolo() bool
  • func (c *Conn) GetLastDiffFactor() int
  • func (c *Conn) GetLastDiffFactorAt() time.Time
  • func (c *Conn) GetLastErrorAt() time.Time
  • func (c *Conn) GetLatency() (time.Duration, error)
  • func (c *Conn) GetMiner() string
  • func (c *Conn) GetMinerID() uint64
  • func (c *Conn) GetPort() int
  • func (c *Conn) GetSubscribed() bool
  • func (c *Conn) GetWorker() string
  • func (c *Conn) GetWorkerID() uint64
  • func (c *Conn) NewScanner() *bufio.Scanner
  • func (c *Conn) SetAuthorized(authorized bool)
  • func (c *Conn) SetClient(client string)
  • func (c *Conn) SetClientType(clientType int)
  • func (c *Conn) SetDiffFactor(diffFactor int)
  • func (c *Conn) SetErrorCount(count int)
  • func (c *Conn) SetExtraNonce(extraNonce string)
  • func (c *Conn) SetExtraNonceSubscribed(extraNonceSubscribed bool)
  • func (c *Conn) SetIsSolo(isSolo bool)
  • func (c *Conn) SetLastErrorAt(ts time.Time)
  • func (c *Conn) SetLastShareAt(ts time.Time) int
  • func (c *Conn) SetMiner(miner string)
  • func (c *Conn) SetMinerID(minerID uint64)
  • func (c *Conn) SetReadDeadline(timestamp time.Time)
  • func (c *Conn) SetSubscribed(subscribed bool)
  • func (c *Conn) SetWorker(worker string)
  • func (c *Conn) SetWorkerID(workerID uint64)
  • func (c *Conn) SoftClose()
  • func (c *Conn) Write(data []byte) error
• type Message
• type Server
  • func NewServer(ctx context.Context, logger *log.Logger, enableVarDiff bool, ports ...int) (*Server, error)
  • func (s *Server) GetConn(id uint64) (*Conn, error)
  • func (s *Server) Port(idx int) int
  • func (s *Server) Start(connTimeout time.Duration) (chan Message, chan uint64, chan *Conn, chan error, error)
  • func (s *Server) Wait()

Variables

var (
	ErrNoActiveConn    = fmt.Errorf("no active conn")
	ErrResponseTimeout = fmt.Errorf("response timeout")
	ErrClientClosed    = fmt.Errorf("client closed")
	ErrRequestIDInUse  = fmt.Errorf("request id in use")
)

var (
	ErrConnNotFound = fmt.Errorf("conn not found")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(
	ctx context.Context,
	host string,
	timeout, reconnect time.Duration,
) *Client

func (*Client) ForceReconnect

func (c *Client) ForceReconnect()

func (*Client) Start

func (c *Client) Start(handshakeReqs []*rpc.Request) (
	chan *rpc.Request,
	chan *rpc.Response,
	chan error,
)

func (*Client) URL

func (c *Client) URL() string

func (*Client) WaitForHandshake

func (c *Client) WaitForHandshake(timeout time.Duration) error

func (*Client) WriteRequest

func (c *Client) WriteRequest(req *rpc.Request) (*rpc.Response, error)

func (*Client) WriteRequestWithTimeout

func (c *Client) WriteRequestWithTimeout(
	req *rpc.Request,
	timeout time.Duration,
) (*rpc.Response, error)

func (*Client) WriteResponse

func (c *Client) WriteResponse(res *rpc.Response) error

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

func NewConn

func NewConn(id uint64, port int, ip string, enableVarDiff bool, rawConn net.Conn) *Conn

func (*Conn) Close

func (c *Conn) Close()

func (*Conn) GetAuthorized

func (c *Conn) GetAuthorized() bool

func (*Conn) GetClient

func (c *Conn) GetClient() string

func (*Conn) GetClientType

func (c *Conn) GetClientType() int

func (*Conn) GetCompoundID

func (c *Conn) GetCompoundID() string

func (*Conn) GetDiffFactor

func (c *Conn) GetDiffFactor() int

func (*Conn) GetErrorCount

func (c *Conn) GetErrorCount() int

func (*Conn) GetExtraNonce

func (c *Conn) GetExtraNonce() string

func (*Conn) GetExtraNonceSubscribed

func (c *Conn) GetExtraNonceSubscribed() bool

func (*Conn) GetID

func (c *Conn) GetID() uint64

func (*Conn) GetIP

func (c *Conn) GetIP() string

func (*Conn) GetIsSolo

func (c *Conn) GetIsSolo() bool

func (*Conn) GetLastDiffFactor

func (c *Conn) GetLastDiffFactor() int

func (*Conn) GetLastDiffFactorAt

func (c *Conn) GetLastDiffFactorAt() time.Time

func (*Conn) GetLastErrorAt

func (c *Conn) GetLastErrorAt() time.Time

func (*Conn) GetLatency

func (c *Conn) GetLatency() (time.Duration, error)

func (*Conn) GetMiner

func (c *Conn) GetMiner() string

func (*Conn) GetMinerID

func (c *Conn) GetMinerID() uint64

func (*Conn) GetPort

func (c *Conn) GetPort() int

func (*Conn) GetSubscribed

func (c *Conn) GetSubscribed() bool

func (*Conn) GetWorker

func (c *Conn) GetWorker() string

func (*Conn) GetWorkerID

func (c *Conn) GetWorkerID() uint64

func (*Conn) NewScanner

func (c *Conn) NewScanner() *bufio.Scanner

func (*Conn) SetAuthorized

func (c *Conn) SetAuthorized(authorized bool)

func (*Conn) SetClient

func (c *Conn) SetClient(client string)

func (*Conn) SetClientType

func (c *Conn) SetClientType(clientType int)

func (*Conn) SetDiffFactor

func (c *Conn) SetDiffFactor(diffFactor int)

func (*Conn) SetErrorCount

func (c *Conn) SetErrorCount(count int)

func (*Conn) SetExtraNonce

func (c *Conn) SetExtraNonce(extraNonce string)

func (*Conn) SetExtraNonceSubscribed

func (c *Conn) SetExtraNonceSubscribed(extraNonceSubscribed bool)

func (*Conn) SetIsSolo

func (c *Conn) SetIsSolo(isSolo bool)

func (*Conn) SetLastErrorAt

func (c *Conn) SetLastErrorAt(ts time.Time)

func (*Conn) SetLastShareAt

func (c *Conn) SetLastShareAt(ts time.Time) int

func (*Conn) SetMiner

func (c *Conn) SetMiner(miner string)

func (*Conn) SetMinerID

func (c *Conn) SetMinerID(minerID uint64)

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(timestamp time.Time)

func (*Conn) SetSubscribed

func (c *Conn) SetSubscribed(subscribed bool)

func (*Conn) SetWorker

func (c *Conn) SetWorker(worker string)

func (*Conn) SetWorkerID

func (c *Conn) SetWorkerID(workerID uint64)

func (*Conn) SoftClose

func (c *Conn) SoftClose()

func (*Conn) Write

func (c *Conn) Write(data []byte) error

type Message

type Message struct {
	Conn *Conn
	Req  *rpc.Request
}

type Server

type Server struct {
	// contains filtered or unexported fields
}

func NewServer

func NewServer(
	ctx context.Context,
	logger *log.Logger,
	enableVarDiff bool,
	ports ...int,
) (*Server, error)

func (*Server) GetConn

func (s *Server) GetConn(id uint64) (*Conn, error)

func (*Server) Port

func (s *Server) Port(idx int) int

func (*Server) Start

func (s *Server) Start(connTimeout time.Duration) (
	chan Message,
	chan uint64,
	chan *Conn,
	chan error,
	error,
)

func (*Server) Wait

func (s *Server) Wait()