antelope_ship_client

README

Antelope SHIP Client

Client Implementation of Antelope state-history websocket.

Install package

go get -u github.com/eosswedenorg-go/antelope-ship-client@latest

Documentation

Documentation can be found over at pkg.go.dev

Examples

• Basic

Author

Henrik Hautakoski - Sw/eden - henrik@eossweden.org

Documentation

Overview

Callback functions

This library uses callback functions to allow the users to execute the code needed when certain events are triggered.

the Client struct accepts the following callback functions

InitHandler func(*eos.ABI)

Called when the client receives the first message from the SHIP node on connection. This message contains the abi with all the information about the functions/types exposed by the websocket api.

BlockHandler func(*ship.GetBlocksResultV0)

Called when the client reveives a block message from the server.

TraceHandler func([]*ship.TransactionTraceV0)

When the client reveives a block message from the server and the Block has any traces attached to it. these traces are then passed to this callback.

StatusHandler func(*ship.GetStatusResultV0)

Called when the client reveives a status message.

CloseHandler func()

Called when a client has closed the socket connection (in `(*ShipClient) Close()` function)

Index

• Constants
• type BlockFn
• type Client
  • func NewClient(options ...Option) *Client
  • func (c *Client) Close() error
  • func (c *Client) Connect(url string) error
  • func (c *Client) ConnectContext(ctx context.Context, url string) error
  • func (c *Client) IsOpen() bool
  • func (c *Client) Read() error
  • func (c *Client) Recv() (int, []byte, error)
  • func (c *Client) SendACK() error
  • func (c *Client) SendBlocksRequest() error
  • func (c *Client) SendStatusRequest() error
  • func (c *Client) Shutdown() error
  • func (c Client) UnconfirmedMessages() uint32
• type ClientError
  • func (e ClientError) Error() string
• type CloseFn
• type InitFn
• type Option
  • func WithBlockHandler(value BlockFn) Option
  • func WithCloseHandler(value CloseFn) Option
  • func WithConnectTimeout(value time.Duration) Option
  • func WithEndBlock(value uint32) Option
  • func WithInitHandler(value InitFn) Option
  • func WithIrreversibleOnly(value bool) Option
  • func WithMaxMessagesInFlight(value uint32) Option
  • func WithShutdownTimeout(value time.Duration) Option
  • func WithStartBlock(value uint32) Option
  • func WithStatusHandler(value StatusFn) Option
  • func WithTraceHandler(value TraceFn) Option
• type StatusFn
• type TraceFn

Constants

const (
	// Not connected to websocket.
	ErrNotConnected = iota

	// Failed to read from websocket
	ErrSockRead

	// Failed to send/read from websocket because it's closed.
	ErrSockClosed

	// Failed to send close message
	ErrSendClose

	// Failed to send Ack message
	ErrSendACK

	// Failed to parse message
	ErrParse
)

const NULL_BLOCK_NUMBER uint32 = 0xffffffff

Types

type BlockFn

type BlockFn func(*ship.GetBlocksResultV0)

type Client

type Client struct {

	// Specifies the duration for the connection to be established before the client bails out.
	ConnectTimeout time.Duration

	// Specifies the duration for Shutdown() to wait before forcefully disconnecting the socket.
	ShutdownTimeout time.Duration

	// Block to start receiving notifications on.
	StartBlock uint32

	// Block to end receiving notifications on.
	EndBlock uint32

	// if only irreversible blocks should be sent.
	IrreversibleOnly bool

	// Max number of non-ACKed messages that may be sent.
	MaxMessagesInFlight uint32

	// Callback functions
	InitHandler   InitFn
	BlockHandler  BlockFn
	TraceHandler  TraceFn
	StatusHandler StatusFn
	CloseHandler  CloseFn
	// contains filtered or unexported fields
}

func NewClient

func NewClient(options ...Option) *Client

Create a new client

func (*Client) Close

func (c *Client) Close() error

Close the socket on the client side.

NOTE: This method closes the underlying network connection without sending or close message.

func (*Client) Connect

func (c *Client) Connect(url string) error

Connect uses context.Background internally; to specify the context, use ConnectContext.

func (*Client) ConnectContext

func (c *Client) ConnectContext(ctx context.Context, url string) error

ConnectContext connects to a ship node using the provided context

The provided Context must be non-nil. If the context expires or is canceled before the connection is complete, an error is returned.

func (*Client) IsOpen

func (c *Client) IsOpen() bool

Returns true if the websocket connection is open. false otherwise.

func (*Client) Read

func (c *Client) Read() error

Read messages from the client and calls the appropriate callback function.

This function will block until atleast one valid message is processed or an error occured.

func (*Client) Recv

func (c *Client) Recv() (int, []byte, error)

func (*Client) SendACK

func (c *Client) SendACK() error

Sends an Acknowledgment message that tells the server that we have received X number of messages where X is the number returned by c.UnconfirmedMessages().

This is normally called internally by Recv() So only use this manually if you know that you need to.

func (*Client) SendBlocksRequest

func (c *Client) SendBlocksRequest() error

Send a blocks request to the ship server. This tells the server to start sending block message to the client.

func (*Client) SendStatusRequest

func (c *Client) SendStatusRequest() error

Send a status request to the ship server. This tells the server to start sending status message to the client.

func (*Client) Shutdown

func (c *Client) Shutdown() error

Shutdown closes the connection gracefully by sending a Close handshake. This function will block until a close message is received from the server an error occure or timeout is exceeded.

func (Client) UnconfirmedMessages

func (c Client) UnconfirmedMessages() uint32

Returns the number of messages the client has received but have not yet been confirmed as having been received by the client

type ClientError

type ClientError struct {
	Type int
	Text string
}

func (ClientError) Error

func (e ClientError) Error() string

type CloseFn

type CloseFn func()

type InitFn

type InitFn func(*eos.ABI)

type Option

type Option func(*Client)

func WithBlockHandler

func WithBlockHandler(value BlockFn) Option

Option to set Client.BlockHandler

func WithCloseHandler

func WithCloseHandler(value CloseFn) Option

Option to set Client.CloseHandler

func WithConnectTimeout

func WithConnectTimeout(value time.Duration) Option

Option to set Client.ConnectTimeout

func WithEndBlock

func WithEndBlock(value uint32) Option

Option to set Client.EndBlock

func WithInitHandler

func WithInitHandler(value InitFn) Option

Option to set Client.InitHandler

func WithIrreversibleOnly

func WithIrreversibleOnly(value bool) Option

Option to set Client.IrreversibleOnly

func WithMaxMessagesInFlight

func WithMaxMessagesInFlight(value uint32) Option

Option to set Client.MaxMessagesInFlight

func WithShutdownTimeout

func WithShutdownTimeout(value time.Duration) Option

Option to set Client.ShutdownTimeout

func WithStartBlock

func WithStartBlock(value uint32) Option

Option to set Client.StartBlock

func WithStatusHandler

func WithStatusHandler(value StatusFn) Option

Option to set Client.StatusHandler

func WithTraceHandler

func WithTraceHandler(value TraceFn) Option

Option to set Client.TraceHandler

type StatusFn

type StatusFn func(*ship.GetStatusResultV0)

type TraceFn

type TraceFn func([]*ship.TransactionTraceV0)