Skip to content

Commit 723235e

Browse files
AndriiDiachukAndriiDiachuk
authored
Merge branch 'feature/optimistic-sync' into andron/7655-registers-endpoints-error-handling
2 parents 8d9551f + 4447798 commit 723235e

File tree

23 files changed

+1248
-336
lines changed

23 files changed

+1248
-336
lines changed

‎access/api.go‎

Lines changed: 128 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,143 @@ import (
1212
)
1313

1414
type AccountsAPI interface {
15+
// GetAccount returns the account details at the latest sealed block.
16+
// Alias for GetAccountAtLatestBlock.
17+
//
18+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
19+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
20+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
21+
//
22+
// Expected error returns during normal operation:
23+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
24+
// - [access.DataNotFoundError]: If data is not found.
25+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
26+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
27+
// - [access.RequestCanceledError]: If the request is canceled.
28+
// - [access.RequestTimedOutError]: If the request times out.
29+
// - [access.InternalError]: For internal failures or index conversion errors.
1530
GetAccount(ctx context.Context, address flow.Address, criteria optimistic_sync.Criteria) (*flow.Account, *accessmodel.ExecutorMetadata, error)
31+
// GetAccountAtLatestBlock returns the account details at the latest sealed block.
32+
//
33+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
34+
// As documented in the [access.API], which we partially implement with this function
35+
// - All errors returned by this API are guaranteed to be benign. The node can continue normal operations after such errors.
36+
// - Hence, we MUST check here and crash on all errors *except* for those known to be benign in the present context!
37+
//
38+
// Expected error returns during normal operation:
39+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
40+
// - [access.DataNotFoundError]: If data is not found.
41+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
42+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
43+
// - [access.RequestCanceledError]: If the request is canceled.
44+
// - [access.RequestTimedOutError]: If the request times out.
45+
// - [access.InternalError]: For internal failures or index conversion errors.
1646
GetAccountAtLatestBlock(ctx context.Context, address flow.Address, criteria optimistic_sync.Criteria) (*flow.Account, *accessmodel.ExecutorMetadata, error)
47+
// GetAccountAtBlockHeight returns the account details at the given block height.
48+
//
49+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
50+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
51+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
52+
//
53+
// Expected error returns during normal operation:
54+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
55+
// - [access.DataNotFoundError]: If data is not found.
56+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
57+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
58+
// - [access.RequestCanceledError]: If the request is canceled.
59+
// - [access.RequestTimedOutError]: If the request times out.
60+
// - [access.InternalError]: For internal failures or index conversion errors.
1761
GetAccountAtBlockHeight(ctx context.Context, address flow.Address, height uint64, criteria optimistic_sync.Criteria) (*flow.Account, *accessmodel.ExecutorMetadata, error)
18-
62+
// GetAccountBalanceAtLatestBlock returns the account balance at the latest sealed block.
63+
//
64+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
65+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
66+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
67+
//
68+
// Expected error returns during normal operation:
69+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
70+
// - [access.DataNotFoundError]: If data is not found.
71+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
72+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
73+
// - [access.RequestCanceledError]: If the request is canceled.
74+
// - [access.RequestTimedOutError]: If the request times out.
75+
// - [access.InternalError]: For internal failures or index conversion errors.
1976
GetAccountBalanceAtLatestBlock(ctx context.Context, address flow.Address, criteria optimistic_sync.Criteria) (uint64, *accessmodel.ExecutorMetadata, error)
77+
// GetAccountBalanceAtBlockHeight returns the account balance at the given block height.
78+
//
79+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
80+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
81+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
82+
//
83+
// Expected error returns during normal operation:
84+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
85+
// - [access.DataNotFoundError]: If data is not found.
86+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
87+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
88+
// - [access.RequestCanceledError]: If the request is canceled.
89+
// - [access.RequestTimedOutError]: If the request times out.
90+
// - [access.InternalError]: For internal failures or index conversion errors.
2091
GetAccountBalanceAtBlockHeight(ctx context.Context, address flow.Address, height uint64, criteria optimistic_sync.Criteria) (uint64, *accessmodel.ExecutorMetadata, error)
2192

93+
// GetAccountKeyAtLatestBlock returns the account public key at the latest sealed block.
94+
//
95+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
96+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
97+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
98+
//
99+
// Expected error returns during normal operation:
100+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
101+
// - [access.DataNotFoundError]: If data is not found.
102+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
103+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
104+
// - [access.RequestCanceledError]: If the request is canceled.
105+
// - [access.RequestTimedOutError]: If the request times out.
106+
// - [access.InternalError]: For internal failures or index conversion errors.
22107
GetAccountKeyAtLatestBlock(ctx context.Context, address flow.Address, keyIndex uint32, criteria optimistic_sync.Criteria) (*flow.AccountPublicKey, *accessmodel.ExecutorMetadata, error)
108+
// GetAccountKeyAtBlockHeight returns the account public key by key index at the given block height.
109+
//
110+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
111+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
112+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
113+
//
114+
// Expected error returns during normal operation:
115+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
116+
// - [access.DataNotFoundError]: If data is not found.
117+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
118+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
119+
// - [access.RequestCanceledError]: If the request is canceled.
120+
// - [access.RequestTimedOutError]: If the request times out.
121+
// - [access.InternalError]: For internal failures or index conversion errors.
23122
GetAccountKeyAtBlockHeight(ctx context.Context, address flow.Address, keyIndex uint32, height uint64, criteria optimistic_sync.Criteria) (*flow.AccountPublicKey, *accessmodel.ExecutorMetadata, error)
123+
// GetAccountKeysAtLatestBlock returns the account public keys at the latest sealed block.
124+
//
125+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
126+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
127+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
128+
//
129+
// Expected error returns during normal operation:
130+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
131+
// - [access.DataNotFoundError]: If data is not found.
132+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
133+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
134+
// - [access.RequestCanceledError]: If the request is canceled.
135+
// - [access.RequestTimedOutError]: If the request times out.
136+
// - [access.InternalError]: For internal failures or index conversion errors.
24137
GetAccountKeysAtLatestBlock(ctx context.Context, address flow.Address, criteria optimistic_sync.Criteria) ([]flow.AccountPublicKey, *accessmodel.ExecutorMetadata, error)
138+
// GetAccountKeysAtBlockHeight returns the account public keys at the given block height.
139+
//
140+
// CAUTION: this layer SIMPLIFIES the ERROR HANDLING convention
141+
// - All errors returned are guaranteed to be benign. The node can continue normal operations after such errors.
142+
// - To prevent delivering incorrect results to clients in case of an error, all other return values should be discarded.
143+
//
144+
// Expected error returns during normal operation:
145+
// - [access.InvalidRequestError]: If the request fails due to invalid arguments or runtime errors.
146+
// - [access.DataNotFoundError]: If data is not found.
147+
// - [access.OutOfRangeError]: If the data for the requested height is outside the node's available range.
148+
// - [access.PreconditionFailedError]: If the registers storage is still bootstrapping.
149+
// - [access.RequestCanceledError]: If the request is canceled.
150+
// - [access.RequestTimedOutError]: If the request times out.
151+
// - [access.InternalError]: For internal failures or index conversion errors.
25152
GetAccountKeysAtBlockHeight(ctx context.Context, address flow.Address, height uint64, criteria optimistic_sync.Criteria) ([]flow.AccountPublicKey, *accessmodel.ExecutorMetadata, error)
26153
}
27154

‎access/errors.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import (
88
"github.com/onflow/flow-go/module/irrecoverable"
99
)
1010

11+
var DataNotFoundPrefix = "data not found for"
12+
1113
// RequireNoError returns nil if error is nil, otherwise throws an irrecoverable exception
1214
func RequireNoError(ctx context.Context, err error) error {
1315
if err == nil {
@@ -98,7 +100,7 @@ func NewDataNotFoundError(dataType string, err error) DataNotFoundError {
98100
}
99101

100102
func (e DataNotFoundError) Error() string {
101-
return fmt.Sprintf("data not found for %s: %v", e.dataType, e.err)
103+
return fmt.Sprintf("%s %s: %v", DataNotFoundPrefix, e.dataType, e.err)
102104
}
103105

104106
func (e DataNotFoundError) Unwrap() error {

‎engine/access/handle_irrecoverable_state_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ func (suite *IrrecoverableStateTestSuite) TestGRPCInconsistentNodeState() {
203203
err := fmt.Errorf("inconsistent node state")
204204
suite.snapshot.On("Head").Return(nil, err)
205205

206-
suite.startServers(suite.T(), irrecoverable.NewExceptionf("failed to lookup sealed header: %w", err))
206+
suite.startServers(suite.T(), irrecoverable.NewExceptionf("failed to lookup latest sealed header: %w", err))
207207

208208
conn, err := grpc.NewClient(
209209
suite.unsecureGrpcServer.GRPCAddress().String(),

0 commit comments

Comments
 (0)