From 388112dcaadc246a6c96b398690e64ccd7f1ebb8 Mon Sep 17 00:00:00 2001 From: Anna Shaleva Date: Wed, 19 Oct 2022 12:46:53 +0300 Subject: [PATCH] rpc: mark old WSClient's SubscribeFor* methods as deprecated --- pkg/rpcclient/wsclient.go | 63 ++++++++++++++++++++++++++-------- pkg/rpcclient/wsclient_test.go | 36 +++++++++---------- 2 files changed, 67 insertions(+), 32 deletions(-) diff --git a/pkg/rpcclient/wsclient.go b/pkg/rpcclient/wsclient.go index da1018639..a2ade71d5 100644 --- a/pkg/rpcclient/wsclient.go +++ b/pkg/rpcclient/wsclient.go @@ -396,15 +396,21 @@ func (c *WSClient) performUnsubscription(id string) error { // of the client. It can be filtered by primary consensus node index and/or block // index allowing to receive blocks since the specified index only, nil value is // treated as missing filter. +// +// Deprecated: please, use SubscribeForNewBlocksWithChan. This method will be removed in future versions. func (c *WSClient) SubscribeForNewBlocks(primary *int, sinceIndex, tillIndex *uint32) (string, error) { return c.SubscribeForNewBlocksWithChan(primary, sinceIndex, tillIndex, c.Notifications) } // SubscribeForNewBlocksWithChan registers provided channel as a receiver for the -// specified new blocks notifications. The receiver channel must be properly read and -// drained after usage in order not to block other notification receivers. -// See SubscribeForNewBlocks for parameter details. +// new block events. Events can be filtered by primary consensus node index, nil +// value doesn't add any filters. If the receiver channel is nil, then the default +// Notifications channel will be used. The receiver channel must be properly read +// and drained after usage in order not to block other notification receivers. func (c *WSClient) SubscribeForNewBlocksWithChan(primary *int, sinceIndex, tillIndex *uint32, rcvrCh chan<- Notification) (string, error) { + if rcvrCh == nil { + rcvrCh = c.Notifications + } params := []interface{}{"block_added"} var flt *neorpc.BlockFilter if primary != nil || sinceIndex != nil || tillIndex != nil { @@ -422,15 +428,22 @@ func (c *WSClient) SubscribeForNewBlocksWithChan(primary *int, sinceIndex, tillI // SubscribeForNewTransactions adds subscription for new transaction events to // this instance of the client. It can be filtered by the sender and/or the signer, nil // value is treated as missing filter. +// +// Deprecated: please, use SubscribeForNewTransactionsWithChan. This method will be removed in future versions. func (c *WSClient) SubscribeForNewTransactions(sender *util.Uint160, signer *util.Uint160) (string, error) { return c.SubscribeForNewTransactionsWithChan(sender, signer, c.Notifications) } // SubscribeForNewTransactionsWithChan registers provided channel as a receiver -// for the specified new transactions notifications. The receiver channel must be +// for new transaction events. Events can be filtered by the sender and/or the +// signer, nil value is treated as missing filter. If the receiver channel is nil, +// then the default Notifications channel will be used. The receiver channel must be // properly read and drained after usage in order not to block other notification -// receivers. See SubscribeForNewTransactions for parameter details. +// receivers. func (c *WSClient) SubscribeForNewTransactionsWithChan(sender *util.Uint160, signer *util.Uint160, rcvrCh chan<- Notification) (string, error) { + if rcvrCh == nil { + rcvrCh = c.Notifications + } params := []interface{}{"transaction_added"} var flt *neorpc.TxFilter if sender != nil || signer != nil { @@ -449,15 +462,22 @@ func (c *WSClient) SubscribeForNewTransactionsWithChan(sender *util.Uint160, sig // generated during transaction execution to this instance of the client. It can be // filtered by the contract's hash (that emits notifications), nil value puts no such // restrictions. +// +// Deprecated: please, use SubscribeForExecutionNotificationsWithChan. This method will be removed in future versions. func (c *WSClient) SubscribeForExecutionNotifications(contract *util.Uint160, name *string) (string, error) { return c.SubscribeForExecutionNotificationsWithChan(contract, name, c.Notifications) } // SubscribeForExecutionNotificationsWithChan registers provided channel as a -// receiver for the specified execution events. The receiver channel must be -// properly read and drained after usage in order not to block other notification -// receivers. See SubscribeForExecutionNotifications for parameter details. +// receiver for execution events. Events can be filtered by the contract's hash +// (that emits notifications), nil value puts no such restrictions. If the +// receiver channel is nil, then the default Notifications channel will be used. +// The receiver channel must be properly read and drained after usage in order +// not to block other notification receivers. func (c *WSClient) SubscribeForExecutionNotificationsWithChan(contract *util.Uint160, name *string, rcvrCh chan<- Notification) (string, error) { + if rcvrCh == nil { + rcvrCh = c.Notifications + } params := []interface{}{"notification_from_execution"} var flt *neorpc.NotificationFilter if contract != nil || name != nil { @@ -477,15 +497,23 @@ func (c *WSClient) SubscribeForExecutionNotificationsWithChan(contract *util.Uin // be filtered by state (HALT/FAULT) to check for successful or failing // transactions; it can also be filtered by script container hash. // nil value means no filtering. +// +// Deprecated: please, use SubscribeForTransactionExecutionsWithChan. This method will be removed in future versions. func (c *WSClient) SubscribeForTransactionExecutions(state *string, container *util.Uint256) (string, error) { return c.SubscribeForTransactionExecutionsWithChan(state, container, c.Notifications) } // SubscribeForTransactionExecutionsWithChan registers provided channel as a -// receiver for the specified execution notifications. The receiver channel must be -// properly read and drained after usage in order not to block other notification -// receivers. See SubscribeForTransactionExecutions for parameter details. +// receiver for application execution result events generated during transaction +// execution. Events can be filtered by state (HALT/FAULT) to check for successful +// or failing transactions; it can also be filtered by script container hash. +// nil value means no filtering. If the receiver channel is nil, then the default +// Notifications channel will be used. The receiver channel must be properly read +// and drained after usage in order not to block other notification receivers. func (c *WSClient) SubscribeForTransactionExecutionsWithChan(state *string, container *util.Uint256, rcvrCh chan<- Notification) (string, error) { + if rcvrCh == nil { + rcvrCh = c.Notifications + } params := []interface{}{"transaction_executed"} var flt *neorpc.ExecutionFilter if state != nil || container != nil { @@ -509,15 +537,22 @@ func (c *WSClient) SubscribeForTransactionExecutionsWithChan(state *string, cont // addition or removal events to this instance of client. It can be filtered by // request sender's hash, or main tx signer's hash, nil value puts no such // restrictions. +// +// Deprecated: please, use SubscribeForNotaryRequestsWithChan. This method will be removed in future versions. func (c *WSClient) SubscribeForNotaryRequests(sender *util.Uint160, mainSigner *util.Uint160) (string, error) { return c.SubscribeForNotaryRequestsWithChan(sender, mainSigner, c.Notifications) } // SubscribeForNotaryRequestsWithChan registers provided channel as a receiver -// for the specified notary requests notifications. The receiver channel must be -// properly read and drained after usage in order not to block other notification -// receivers. See SubscribeForNotaryRequests for parameter details. +// for notary request payload addition or removal events. It can be filtered by +// request sender's hash, or main tx signer's hash, nil value puts no such +// restrictions. If the receiver channel is nil, then the default Notifications +// channel will be used. The receiver channel must be properly read and drained +// after usage in order not to block other notification receivers. func (c *WSClient) SubscribeForNotaryRequestsWithChan(sender *util.Uint160, mainSigner *util.Uint160, rcvrCh chan<- Notification) (string, error) { + if rcvrCh == nil { + rcvrCh = c.Notifications + } params := []interface{}{"notary_request_event"} var flt *neorpc.TxFilter if sender != nil { diff --git a/pkg/rpcclient/wsclient_test.go b/pkg/rpcclient/wsclient_test.go index 5662b1a32..501700b84 100644 --- a/pkg/rpcclient/wsclient_test.go +++ b/pkg/rpcclient/wsclient_test.go @@ -35,25 +35,25 @@ func TestWSClientSubscription(t *testing.T) { ch := make(chan Notification) var cases = map[string]func(*WSClient) (string, error){ "blocks": func(wsc *WSClient) (string, error) { - return wsc.SubscribeForNewBlocks(nil, nil, nil) + return wsc.SubscribeForNewBlocksWithChan(nil, nil, nil, nil) }, "blocks_with_custom_ch": func(wsc *WSClient) (string, error) { return wsc.SubscribeForNewBlocksWithChan(nil, nil, nil, ch) }, "transactions": func(wsc *WSClient) (string, error) { - return wsc.SubscribeForNewTransactions(nil, nil) + return wsc.SubscribeForNewTransactionsWithChan(nil, nil, nil) }, "transactions_with_custom_ch": func(wsc *WSClient) (string, error) { return wsc.SubscribeForNewTransactionsWithChan(nil, nil, ch) }, "notifications": func(wsc *WSClient) (string, error) { - return wsc.SubscribeForExecutionNotifications(nil, nil) + return wsc.SubscribeForExecutionNotificationsWithChan(nil, nil, nil) }, "notifications_with_custom_ch": func(wsc *WSClient) (string, error) { return wsc.SubscribeForExecutionNotificationsWithChan(nil, nil, ch) }, "executions": func(wsc *WSClient) (string, error) { - return wsc.SubscribeForTransactionExecutions(nil, nil) + return wsc.SubscribeForTransactionExecutionsWithChan(nil, nil, nil) }, "executions_with_custom_ch": func(wsc *WSClient) (string, error) { return wsc.SubscribeForTransactionExecutionsWithChan(nil, nil, ch) @@ -274,7 +274,7 @@ func TestWSExecutionVMStateCheck(t *testing.T) { wsc.getNextRequestID = getTestRequestID require.NoError(t, wsc.Init()) filter := "NONE" - _, err = wsc.SubscribeForTransactionExecutions(&filter, nil) + _, err = wsc.SubscribeForTransactionExecutionsWithChan(&filter, nil, nil) require.Error(t, err) wsc.Close() } @@ -288,7 +288,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"blocks primary", func(t *testing.T, wsc *WSClient) { primary := 3 - _, err := wsc.SubscribeForNewBlocks(&primary, nil, nil) + _, err := wsc.SubscribeForNewBlocksWithChan(&primary, nil, nil, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -303,7 +303,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"blocks since", func(t *testing.T, wsc *WSClient) { var since uint32 = 3 - _, err := wsc.SubscribeForNewBlocks(nil, &since, nil) + _, err := wsc.SubscribeForNewBlocksWithChan(nil, &since, nil, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -318,7 +318,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"blocks till", func(t *testing.T, wsc *WSClient) { var till uint32 = 3 - _, err := wsc.SubscribeForNewBlocks(nil, nil, &till) + _, err := wsc.SubscribeForNewBlocksWithChan(nil, nil, &till, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -337,7 +337,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { primary = 2 till uint32 = 5 ) - _, err := wsc.SubscribeForNewBlocks(&primary, &since, &till) + _, err := wsc.SubscribeForNewBlocksWithChan(&primary, &since, &till, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -352,7 +352,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"transactions sender", func(t *testing.T, wsc *WSClient) { sender := util.Uint160{1, 2, 3, 4, 5} - _, err := wsc.SubscribeForNewTransactions(&sender, nil) + _, err := wsc.SubscribeForNewTransactionsWithChan(&sender, nil, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -366,7 +366,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"transactions signer", func(t *testing.T, wsc *WSClient) { signer := util.Uint160{0, 42} - _, err := wsc.SubscribeForNewTransactions(nil, &signer) + _, err := wsc.SubscribeForNewTransactionsWithChan(nil, &signer, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -381,7 +381,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { func(t *testing.T, wsc *WSClient) { sender := util.Uint160{1, 2, 3, 4, 5} signer := util.Uint160{0, 42} - _, err := wsc.SubscribeForNewTransactions(&sender, &signer) + _, err := wsc.SubscribeForNewTransactionsWithChan(&sender, &signer, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -395,7 +395,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"notifications contract hash", func(t *testing.T, wsc *WSClient) { contract := util.Uint160{1, 2, 3, 4, 5} - _, err := wsc.SubscribeForExecutionNotifications(&contract, nil) + _, err := wsc.SubscribeForExecutionNotificationsWithChan(&contract, nil, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -409,7 +409,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"notifications name", func(t *testing.T, wsc *WSClient) { name := "my_pretty_notification" - _, err := wsc.SubscribeForExecutionNotifications(nil, &name) + _, err := wsc.SubscribeForExecutionNotificationsWithChan(nil, &name, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -424,7 +424,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { func(t *testing.T, wsc *WSClient) { contract := util.Uint160{1, 2, 3, 4, 5} name := "my_pretty_notification" - _, err := wsc.SubscribeForExecutionNotifications(&contract, &name) + _, err := wsc.SubscribeForExecutionNotificationsWithChan(&contract, &name, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -438,7 +438,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"executions state", func(t *testing.T, wsc *WSClient) { state := "FAULT" - _, err := wsc.SubscribeForTransactionExecutions(&state, nil) + _, err := wsc.SubscribeForTransactionExecutionsWithChan(&state, nil, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -452,7 +452,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { {"executions container", func(t *testing.T, wsc *WSClient) { container := util.Uint256{1, 2, 3} - _, err := wsc.SubscribeForTransactionExecutions(nil, &container) + _, err := wsc.SubscribeForTransactionExecutionsWithChan(nil, &container, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) { @@ -467,7 +467,7 @@ func TestWSFilteredSubscriptions(t *testing.T) { func(t *testing.T, wsc *WSClient) { state := "FAULT" container := util.Uint256{1, 2, 3} - _, err := wsc.SubscribeForTransactionExecutions(&state, &container) + _, err := wsc.SubscribeForTransactionExecutionsWithChan(&state, &container, nil) require.NoError(t, err) }, func(t *testing.T, p *params.Params) {