[Access] Implement gRPC streaming endpoint SubscribeBlocks

Makefile

@@ -199,6 +199,8 @@ generate-mocks: install-mock-generators
 	mockery --name 'API' --dir="./access" --case=underscore --output="./access/mock" --outpkg="mock"
 	mockery --name 'API' --dir="./engine/protocol" --case=underscore --output="./engine/protocol/mock" --outpkg="mock"
 	mockery --name '.*' --dir="./engine/access/state_stream" --case=underscore --output="./engine/access/state_stream/mock" --outpkg="mock"
+	mockery --name 'BlockTracker' --dir="./engine/access/subscription" --case=underscore --output="./engine/access/subscription/mock"  --outpkg="mock"
+	mockery --name 'ExecutionDataTracker' --dir="./engine/access/subscription" --case=underscore --output="./engine/access/subscription/mock"  --outpkg="mock"
 	mockery --name 'ConnectionFactory' --dir="./engine/access/rpc/connection" --case=underscore --output="./engine/access/rpc/connection/mock" --outpkg="mock"
 	mockery --name 'Communicator' --dir="./engine/access/rpc/backend" --case=underscore --output="./engine/access/rpc/backend/mock" --outpkg="mock"
 

access/api.go

@@ -6,6 +6,7 @@ import (
 	"github.com/onflow/flow/protobuf/go/flow/access"
 	"github.com/onflow/flow/protobuf/go/flow/entities"
 
+	"github.com/onflow/flow-go/engine/access/subscription"
 	"github.com/onflow/flow-go/engine/common/rpc/convert"
 	"github.com/onflow/flow-go/model/flow"
 )
@@ -52,6 +53,147 @@ type API interface {
 
 	GetExecutionResultForBlockID(ctx context.Context, blockID flow.Identifier) (*flow.ExecutionResult, error)
 	GetExecutionResultByID(ctx context.Context, id flow.Identifier) (*flow.ExecutionResult, error)
+
+	// SubscribeBlocks
+
+	// SubscribeBlocksFromStartBlockID subscribes to the finalized or sealed blocks starting at the requested
+	// start block id, up until the latest available block. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block as it becomes available.
+	//
+	// Each block is filtered by the provided block status, and only
+	// those blocks that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - startBlockID: The identifier of the starting block.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlocksFromStartBlockID will return a failed subscription.
+	SubscribeBlocksFromStartBlockID(ctx context.Context, startBlockID flow.Identifier, blockStatus flow.BlockStatus) subscription.Subscription
+	// SubscribeBlocksFromStartHeight subscribes to the finalized or sealed blocks starting at the requested
+	// start block height, up until the latest available block. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block as it becomes available.
+	//
+	// Each block is filtered by the provided block status, and only
+	// those blocks that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - startHeight: The height of the starting block.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlocksFromStartHeight will return a failed subscription.
+	SubscribeBlocksFromStartHeight(ctx context.Context, startHeight uint64, blockStatus flow.BlockStatus) subscription.Subscription
+	// SubscribeBlocksFromLatest subscribes to the finalized or sealed blocks starting at the latest sealed block,
+	// up until the latest available block. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block as it becomes available.
+	//
+	// Each block is filtered by the provided block status, and only
+	// those blocks that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlocksFromLatest will return a failed subscription.
+	SubscribeBlocksFromLatest(ctx context.Context, blockStatus flow.BlockStatus) subscription.Subscription
+
+	// SubscribeHeaders
+
+	// SubscribeBlockHeadersFromStartBlockID streams finalized or sealed block headers starting at the requested
+	// start block id, up until the latest available block header. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block header as it becomes available.
+	//
+	// Each block header are filtered by the provided block status, and only
+	// those block headers that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - startBlockID: The identifier of the starting block.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlockHeadersFromStartBlockID will return a failed subscription.
+	SubscribeBlockHeadersFromStartBlockID(ctx context.Context, startBlockID flow.Identifier, blockStatus flow.BlockStatus) subscription.Subscription
+	// SubscribeBlockHeadersFromStartHeight streams finalized or sealed block headers starting at the requested
+	// start block height, up until the latest available block header. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block header as it becomes available.
+	//
+	// Each block header are filtered by the provided block status, and only
+	// those block headers that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - startHeight: The height of the starting block.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlockHeadersFromStartHeight will return a failed subscription.
+	SubscribeBlockHeadersFromStartHeight(ctx context.Context, startHeight uint64, blockStatus flow.BlockStatus) subscription.Subscription
+	// SubscribeBlockHeadersFromLatest streams finalized or sealed block headers starting at the latest sealed block,
+	// up until the latest available block header. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block header as it becomes available.
+	//
+	// Each block header are filtered by the provided block status, and only
+	// those block headers that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlockHeadersFromLatest will return a failed subscription.
+	SubscribeBlockHeadersFromLatest(ctx context.Context, blockStatus flow.BlockStatus) subscription.Subscription
+
+	// Subscribe digests
+
+	// SubscribeBlockDigestsFromStartBlockID streams finalized or sealed lightweight block starting at the requested
+	// start block id, up until the latest available block. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block as it becomes available.
+	//
+	// Each lightweight block are filtered by the provided block status, and only
+	// those blocks that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - startBlockID: The identifier of the starting block.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlockDigestsFromStartBlockID will return a failed subscription.
+	SubscribeBlockDigestsFromStartBlockID(ctx context.Context, startBlockID flow.Identifier, blockStatus flow.BlockStatus) subscription.Subscription
+	// SubscribeBlockDigestsFromStartHeight streams finalized or sealed lightweight block starting at the requested
+	// start block height, up until the latest available block. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block as it becomes available.
+	//
+	// Each lightweight block are filtered by the provided block status, and only
+	// those blocks that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - startHeight: The height of the starting block.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlockDigestsFromStartHeight will return a failed subscription.
+	SubscribeBlockDigestsFromStartHeight(ctx context.Context, startHeight uint64, blockStatus flow.BlockStatus) subscription.Subscription
+	// SubscribeBlockDigestsFromLatest streams finalized or sealed lightweight block starting at the latest sealed block,
+	// up until the latest available block. Once the latest is
+	// reached, the stream will remain open and responses are sent for each new
+	// block as it becomes available.
+	//
+	// Each lightweight block are filtered by the provided block status, and only
+	// those blocks that match the status are returned.
+	//
+	// Parameters:
+	// - ctx: Context for the operation.
+	// - blockStatus: The status of the block, which could be only BlockStatusSealed or BlockStatusFinalized.
+	//
+	// If invalid parameters will be supplied SubscribeBlockDigestsFromLatest will return a failed subscription.
+	SubscribeBlockDigestsFromLatest(ctx context.Context, blockStatus flow.BlockStatus) subscription.Subscription
 }
 
 // TODO: Combine this with flow.TransactionResult?