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
• Stream

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 Stream struct accepts the following callback functions

InitHandler func(*eos.ABI)

Called when the first message on the stream arrives. 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 stream reveives a block message from the server.

TraceHandler func([]*ship.TransactionTraceV0)

When the stream 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 stream reveives a status message.

CloseHandler func()

Called when a stream has closed the socket connection (in `(*Stream) Shutdown()` function)

Index

• Constants
• Variables
• type BlockFn
• 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 WithTableDeltaHandler(value TableDeltaFn) Option
  • func WithTraceHandler(value TraceFn) Option
  • func WithTraces() Option
• type StatusFn
• type Stream
  • func NewStream(options ...Option) *Stream
  • func (s *Stream) Connect(url string) error
  • func (s *Stream) ConnectContext(ctx context.Context, url string) error
  • func (s *Stream) Run() error
  • func (s *Stream) SendBlocksRequest() error
  • func (s *Stream) SendStatusRequest() error
  • func (s *Stream) Shutdown() error
• type TableDeltaFn
• type TraceFn

Constants

const NULL_BLOCK_NUMBER uint32 = 0xffffffff

Variables

var ErrEndBlockReached = errors.New("ship: end block reached")

Types

type BlockFn

type BlockFn func(*ship.GetBlocksResultV0)

type CloseFn

type CloseFn func()

type InitFn

type InitFn func(*chain.Abi)

type Option

type Option func(*Stream)

func WithBlockHandler

func WithBlockHandler(value BlockFn) Option

Option to set Stream.BlockHandler

func WithCloseHandler

func WithCloseHandler(value CloseFn) Option

Option to set Stream.CloseHandler

func WithConnectTimeout

func WithConnectTimeout(value time.Duration) Option

Option to set Stream.ConnectTimeout

func WithEndBlock

func WithEndBlock(value uint32) Option

Option to set Stream.EndBlock

func WithInitHandler

func WithInitHandler(value InitFn) Option

Option to set Stream.InitHandler

func WithIrreversibleOnly

func WithIrreversibleOnly(value bool) Option

Option to set Stream.IrreversibleOnly

func WithMaxMessagesInFlight

func WithMaxMessagesInFlight(value uint32) Option

Option to set Stream.MaxMessagesInFlight

func WithShutdownTimeout

func WithShutdownTimeout(value time.Duration) Option

Option to set Stream.ShutdownTimeout

func WithStartBlock

func WithStartBlock(value uint32) Option

Option to set Stream.StartBlock

func WithStatusHandler

func WithStatusHandler(value StatusFn) Option

Option to set Stream.StatusHandler

func WithTableDeltaHandler

func WithTableDeltaHandler(value TableDeltaFn) Option

Option to set Stream.TableDeltaHandler

func WithTraceHandler

func WithTraceHandler(value TraceFn) Option

Option to set Stream.TraceHandler

func WithTraces

func WithTraces() Option

Option to include traces without using a specific trace handler

type StatusFn

type StatusFn func(*ship.GetStatusResultV0)

type Stream

type Stream 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 messages that can be sent from the server without being acked.
	MaxMessagesInFlight uint32

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

func NewStream

func NewStream(options ...Option) *Stream

Create a new stream

func (*Stream) Connect

func (s *Stream) Connect(url string) error

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

func (*Stream) ConnectContext

func (s *Stream) 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 (*Stream) Run

func (s *Stream) Run() error

Run starts the stream. Messages from the server is read and forwarded to the appropriate callback function. This function will block until an error occur or the stream is closed. Either way the return value is never nil.

func (*Stream) SendBlocksRequest

func (s *Stream) SendBlocksRequest() error

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

func (*Stream) SendStatusRequest

func (s *Stream) SendStatusRequest() error

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

func (*Stream) Shutdown

func (s *Stream) Shutdown() error

Shutdown closes the stream gracefully by performing a websocket close handshake. This function will block until a close message is received from the server, an error occur or timeout is exceeded.

type TableDeltaFn

type TableDeltaFn func(*ship.TableDeltaArray)

type TraceFn

type TraceFn func(*ship.TransactionTraceArray)