[FAB-9195]: Event Client

Change-Id: Ie1e021885df08df96808dd4ac9ab8a9ede60d244
Signed-off-by: Sandra Vrtikapa <sandra.vrtikapa@securekey.com>

Author: sandrask

doc.go

@@ -15,6 +15,9 @@ SPDX-License-Identifier: Apache-2.0
 // pkg/client/channel: Provides channel transaction capabilities.
 // Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/channel
 //
+// pkg/client/event: Provides channel event capabilities.
+// Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/event
+//
 // pkg/client/ledger: Enables queries to a channel's underlying ledger.
 // Reference: https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/ledger
 //

pkg/client/event/event.go

@@ -0,0 +1,132 @@
+/*
+Copyright SecureKey Technologies Inc. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+// 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.
+//
+//	// prepare channel client context
+//	org1ChannelClientContext := sdk.ChannelContext("mychannel", fabsdk.WithUser("User1"), fabsdk.WithOrg("Org1"))
+//
+//	// create default event client (with filtered block events)
+//	eventClient, _ := event.New(org1ChannelClientContext)
+//	if err != nil {
+//		t.Fatalf("Failed to create new events client: %s", err)
+//	}
+//
+//	// Register chaincode event (returns channel which receives event details when the event is complete)
+//	reg, notifier, err := eventClient.RegisterChaincodeEvent("eventcc", "event123")
+//	if err != nil {
+//		t.Fatalf("Failed to register cc event: %s", err)
+//	}
+//	defer eventClient.Unregister(reg)
+//
+//	select {
+//	case ccEvent := <-notifier:
+//		t.Logf("Received cc event: %#v", ccEvent)
+//	case <-time.After(time.Second * 20):
+//		t.Fatalf("Did NOT receive CC event for 'event123'")
+//	}
+package event
+
+import (
+	"github.com/hyperledger/fabric-sdk-go/pkg/common/logging"
+	"github.com/hyperledger/fabric-sdk-go/pkg/common/providers/context"
+	"github.com/hyperledger/fabric-sdk-go/pkg/common/providers/fab"
+	"github.com/hyperledger/fabric-sdk-go/pkg/fab/events/client"
+	"github.com/pkg/errors"
+)
+
+var logger = logging.NewLogger("fabsdk/client")
+
+// Client enables access to a channel events on a Fabric network.
+type Client struct {
+	eventService      fab.EventService
+	permitBlockEvents bool
+}
+
+// New returns a Client instance. Client receives events such as block, filtered block,
+// chaincode, and transaction status events.
+func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client, error) {
+
+	channelContext, err := channelProvider()
+	if err != nil {
+		return nil, errors.WithMessage(err, "failed to create channel context")
+	}
+
+	eventClient := Client{}
+
+	for _, param := range opts {
+		err := param(&eventClient)
+		if err != nil {
+			return nil, errors.WithMessage(err, "option failed")
+		}
+	}
+
+	if channelContext.ChannelService() == nil {
+		return nil, errors.New("channel service not initialized")
+	}
+
+	var es fab.EventService
+	if eventClient.permitBlockEvents {
+		es, err = channelContext.ChannelService().EventService(client.WithBlockEvents())
+	} else {
+		es, err = channelContext.ChannelService().EventService()
+	}
+
+	if err != nil {
+		return nil, errors.WithMessage(err, "event service creation failed")
+	}
+
+	eventClient.eventService = es
+
+	return &eventClient, nil
+}
+
+// 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.
+func (c *Client) RegisterBlockEvent(filter ...fab.BlockFilter) (fab.Registration, <-chan *fab.BlockEvent, error) {
+	return c.eventService.RegisterBlockEvent(filter...)
+}
+
+// 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.
+func (c *Client) RegisterFilteredBlockEvent() (fab.Registration, <-chan *fab.FilteredBlockEvent, error) {
+	return c.eventService.RegisterFilteredBlockEvent()
+}
+
+// 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.
+func (c *Client) RegisterChaincodeEvent(ccID, eventFilter string) (fab.Registration, <-chan *fab.CCEvent, error) {
+	return c.eventService.RegisterChaincodeEvent(ccID, eventFilter)
+}
+
+// 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.
+func (c *Client) RegisterTxStatusEvent(txID string) (fab.Registration, <-chan *fab.TxStatusEvent, error) {
+	return c.eventService.RegisterTxStatusEvent(txID)
+}
+
+// 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
+func (c *Client) Unregister(reg fab.Registration) {
+	c.eventService.Unregister(reg)
+}