event

Documentation

Overview

Package event enables access to a channel events on a Fabric network. Event client receives events such as block, filtered block, chaincode, and transaction status events.

Basic Flow:
1) Prepare channel client context
2) Create event client
3) Register for events
4) Process events (or timeout)
5) Unregister

Example

ec, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

registration, notifier, err := ec.RegisterChaincodeEvent("examplecc", "event123")
if err != nil {
	fmt.Println("failed to register chaincode event")
}
defer ec.Unregister(registration)

select {
case ccEvent := <-notifier:
	fmt.Printf("received chaincode event %v\n", ccEvent)
case <-time.After(time.Second * 5):
	fmt.Println("timeout while waiting for chaincode event")
}

// Timeout is expected since there is no event producer

Output:

timeout while waiting for chaincode event

Index

• type Client
  • func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client, error)
  • func (c *Client) RegisterBlockEvent(filter ...fab.BlockFilter) (fab.Registration, <-chan *fab.BlockEvent, error)
  • func (c *Client) RegisterChaincodeEvent(ccID, eventFilter string) (fab.Registration, <-chan *fab.CCEvent, error)
  • func (c *Client) RegisterFilteredBlockEvent() (fab.Registration, <-chan *fab.FilteredBlockEvent, error)
  • func (c *Client) RegisterTxStatusEvent(txID string) (fab.Registration, <-chan *fab.TxStatusEvent, error)
  • func (c *Client) Unregister(reg fab.Registration)
• type ClientOption
  • func WithBlockEvents() ClientOption
  • func WithBlockNum(from uint64) ClientOption
  • func WithSeekType(seek seek.Type) ClientOption

Examples

• Package
• Client.RegisterBlockEvent
• Client.RegisterChaincodeEvent
• Client.RegisterChaincodeEvent (WithPayload)
• Client.RegisterFilteredBlockEvent
• Client.RegisterTxStatusEvent
• New

Types

type Client

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

Client enables access to a channel events on a Fabric network.

func New

func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client, error)

New returns a Client instance. Client receives events such as block, filtered block, chaincode, and transaction status events.

Example

ctx := mockChannelProvider("mychannel")

ec, err := New(ctx, WithBlockEvents())
if err != nil {
	fmt.Println(err)
}

if ec != nil {
	fmt.Println("event client created")
} else {
	fmt.Println("event client is nil")
}

Output:

event client created

func (*Client) RegisterBlockEvent

func (c *Client) RegisterBlockEvent(filter ...fab.BlockFilter) (fab.Registration, <-chan *fab.BlockEvent, error)

RegisterBlockEvent registers for block events. If the caller does not have permission to register for block events then an error is returned. Unregister must be called when the registration is no longer needed.

Parameters:
filter is an optional filter that filters out unwanted events. (Note: Only one filter may be specified.)

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.

Example

ec, err := New(mockChannelProvider("mychannel"), WithBlockEvents())
if err != nil {
	fmt.Println("failed to create client")
}

registration, _, err := ec.RegisterBlockEvent()
if err != nil {
	fmt.Println("failed to register block event")
}
defer ec.Unregister(registration)

fmt.Println("block event registered successfully")

Output:

block event registered successfully

func (*Client) RegisterChaincodeEvent

func (c *Client) RegisterChaincodeEvent(ccID, eventFilter string) (fab.Registration, <-chan *fab.CCEvent, error)

RegisterChaincodeEvent registers for chaincode events. Unregister must be called when the registration is no longer needed.

Parameters:
ccID is the chaincode ID for which events are to be received
eventFilter is the chaincode event filter (regular expression) for which events are to be received

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.

Example

ec, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

registration, _, err := ec.RegisterChaincodeEvent("examplecc", "event123")
if err != nil {
	fmt.Println("failed to register chaincode event")
}
defer ec.Unregister(registration)

fmt.Println("chaincode event registered successfully")

Output:

chaincode event registered successfully

Example (WithPayload)

// If you require payload for chaincode events you have to use WithBlockEvents() option
ec, err := New(mockChannelProvider("mychannel"), WithBlockEvents())
if err != nil {
	fmt.Println("failed to create client")
}

registration, _, err := ec.RegisterChaincodeEvent("examplecc", "event123")
if err != nil {
	fmt.Println("failed to register chaincode event")
}
defer ec.Unregister(registration)

fmt.Println("chaincode event registered successfully")

Output:

chaincode event registered successfully

func (*Client) RegisterFilteredBlockEvent

func (c *Client) RegisterFilteredBlockEvent() (fab.Registration, <-chan *fab.FilteredBlockEvent, error)

RegisterFilteredBlockEvent registers for filtered block events. Unregister must be called when the registration is no longer needed.

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.

Example

ec, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

registration, _, err := ec.RegisterFilteredBlockEvent()
if err != nil {
	fmt.Println("failed to register filtered block event")
}
defer ec.Unregister(registration)

fmt.Println("filtered block event registered successfully")

Output:

filtered block event registered successfully

func (*Client) RegisterTxStatusEvent

func (c *Client) RegisterTxStatusEvent(txID string) (fab.Registration, <-chan *fab.TxStatusEvent, error)

RegisterTxStatusEvent registers for transaction status events. Unregister must be called when the registration is no longer needed.

Parameters:
txID is the transaction ID for which events are to be received

Returns:
the registration and a channel that is used to receive events. The channel is closed when Unregister is called.

Example

ec, err := New(mockChannelProvider("mychannel"))
if err != nil {
	fmt.Println("failed to create client")
}

registration, _, err := ec.RegisterTxStatusEvent("tx123")
if err != nil {
	fmt.Println("failed to register tx status event")
}
defer ec.Unregister(registration)

fmt.Println("tx status event registered successfully")

Output:

tx status event registered successfully

func (*Client) Unregister

func (c *Client) Unregister(reg fab.Registration)

Unregister removes the given registration and closes the event channel.

Parameters:
reg is the registration handle that was returned from one of the Register functions

type ClientOption

type ClientOption func(*Client) error

ClientOption describes a functional parameter for the New constructor

func WithBlockEvents

func WithBlockEvents() ClientOption

WithBlockEvents indicates that block events are to be received. Note that the caller must have sufficient privileges for this option.

func WithBlockNum

func WithBlockNum(from uint64) ClientOption

WithBlockNum indicates the block number from which events are to be received. Only deliverclient supports this

func WithSeekType

func WithSeekType(seek seek.Type) ClientOption

WithSeekType indicates the type of seek desired - newest, oldest or from given block Only deliverclient supports this