@metamask-previews/network-controller 26.0.0-preview-bc80feb8 → 27.0.0-preview-84f90603

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/CHANGELOG.md +23 -1
  2. package/dist/NetworkController.cjs +37 -10
  3. package/dist/NetworkController.cjs.map +1 -1
  4. package/dist/NetworkController.d.cts +135 -12
  5. package/dist/NetworkController.d.cts.map +1 -1
  6. package/dist/NetworkController.d.mts +135 -12
  7. package/dist/NetworkController.d.mts.map +1 -1
  8. package/dist/NetworkController.mjs +37 -10
  9. package/dist/NetworkController.mjs.map +1 -1
  10. package/dist/constants.cjs +18 -10
  11. package/dist/constants.cjs.map +1 -1
  12. package/dist/constants.d.cts +18 -10
  13. package/dist/constants.d.cts.map +1 -1
  14. package/dist/constants.d.mts +18 -10
  15. package/dist/constants.d.mts.map +1 -1
  16. package/dist/constants.mjs +18 -10
  17. package/dist/constants.mjs.map +1 -1
  18. package/dist/create-auto-managed-network-client.cjs +4 -1
  19. package/dist/create-auto-managed-network-client.cjs.map +1 -1
  20. package/dist/create-auto-managed-network-client.d.cts +5 -2
  21. package/dist/create-auto-managed-network-client.d.cts.map +1 -1
  22. package/dist/create-auto-managed-network-client.d.mts +5 -2
  23. package/dist/create-auto-managed-network-client.d.mts.map +1 -1
  24. package/dist/create-auto-managed-network-client.mjs +4 -1
  25. package/dist/create-auto-managed-network-client.mjs.map +1 -1
  26. package/dist/create-network-client.cjs +132 -42
  27. package/dist/create-network-client.cjs.map +1 -1
  28. package/dist/create-network-client.d.cts +5 -2
  29. package/dist/create-network-client.d.cts.map +1 -1
  30. package/dist/create-network-client.d.mts +5 -2
  31. package/dist/create-network-client.d.mts.map +1 -1
  32. package/dist/create-network-client.mjs +132 -42
  33. package/dist/create-network-client.mjs.map +1 -1
  34. package/dist/index.cjs.map +1 -1
  35. package/dist/index.d.cts +1 -1
  36. package/dist/index.d.cts.map +1 -1
  37. package/dist/index.d.mts +1 -1
  38. package/dist/index.d.mts.map +1 -1
  39. package/dist/index.mjs.map +1 -1
  40. package/dist/rpc-service/rpc-service-chain.cjs +247 -39
  41. package/dist/rpc-service/rpc-service-chain.cjs.map +1 -1
  42. package/dist/rpc-service/rpc-service-chain.d.cts +106 -25
  43. package/dist/rpc-service/rpc-service-chain.d.cts.map +1 -1
  44. package/dist/rpc-service/rpc-service-chain.d.mts +106 -25
  45. package/dist/rpc-service/rpc-service-chain.d.mts.map +1 -1
  46. package/dist/rpc-service/rpc-service-chain.mjs +247 -39
  47. package/dist/rpc-service/rpc-service-chain.mjs.map +1 -1
  48. package/dist/rpc-service/rpc-service-requestable.cjs.map +1 -1
  49. package/dist/rpc-service/rpc-service-requestable.d.cts +15 -5
  50. package/dist/rpc-service/rpc-service-requestable.d.cts.map +1 -1
  51. package/dist/rpc-service/rpc-service-requestable.d.mts +15 -5
  52. package/dist/rpc-service/rpc-service-requestable.d.mts.map +1 -1
  53. package/dist/rpc-service/rpc-service-requestable.mjs.map +1 -1
  54. package/dist/rpc-service/rpc-service.cjs +65 -33
  55. package/dist/rpc-service/rpc-service.cjs.map +1 -1
  56. package/dist/rpc-service/rpc-service.d.cts +33 -24
  57. package/dist/rpc-service/rpc-service.d.cts.map +1 -1
  58. package/dist/rpc-service/rpc-service.d.mts +33 -24
  59. package/dist/rpc-service/rpc-service.d.mts.map +1 -1
  60. package/dist/rpc-service/rpc-service.mjs +66 -34
  61. package/dist/rpc-service/rpc-service.mjs.map +1 -1
  62. package/dist/rpc-service/shared.cjs.map +1 -1
  63. package/dist/rpc-service/shared.d.cts +25 -3
  64. package/dist/rpc-service/shared.d.cts.map +1 -1
  65. package/dist/rpc-service/shared.d.mts +25 -3
  66. package/dist/rpc-service/shared.d.mts.map +1 -1
  67. package/dist/rpc-service/shared.mjs.map +1 -1
  68. package/package.json +2 -1
@@ -1,15 +1,14 @@
1
1
  import type { Json, JsonRpcParams, JsonRpcRequest, JsonRpcResponse } from "@metamask/utils";
2
2
  import { RpcService } from "./rpc-service.cjs";
3
3
  import type { RpcServiceOptions } from "./rpc-service.cjs";
4
- import type { RpcServiceRequestable } from "./rpc-service-requestable.cjs";
5
- import type { FetchOptions } from "./shared.cjs";
4
+ import type { CockatielEventToEventListenerWithData, ExcludeCockatielEventData, ExtractCockatielEventData, FetchOptions } from "./shared.cjs";
6
5
  /**
7
- * This class constructs a chain of RpcService objects which represent a
8
- * particular network. The first object in the chain is intended to be the
9
- * primary way of reaching the network and the remaining objects are used as
10
- * failovers.
6
+ * This class constructs and manages requests to a chain of RpcService objects
7
+ * which represent RPC endpoints with which to access a particular network. The
8
+ * first service in the chain is intended to be the primary way of hitting the
9
+ * network and the remaining services are used as failovers.
11
10
  */
12
- export declare class RpcServiceChain implements RpcServiceRequestable {
11
+ export declare class RpcServiceChain {
13
12
  #private;
14
13
  /**
15
14
  * Constructs a new RpcServiceChain object.
@@ -18,38 +17,120 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
18
17
  * that you want to construct. Each object in this array is the same as
19
18
  * {@link RpcServiceOptions}.
20
19
  */
21
- constructor(rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[]);
20
+ constructor(rpcServiceConfigurations: [RpcServiceOptions, ...RpcServiceOptions[]]);
22
21
  /**
23
- * Listens for when any of the RPC services retry a request.
22
+ * Calls the provided callback when any of the RPC services is retried.
24
23
  *
25
- * @param listener - The callback to be called when the retry occurs.
26
- * @returns What {@link RpcService.onRetry} returns.
24
+ * This is mainly useful for tests.
25
+ *
26
+ * @param listener - The callback to be called.
27
+ * @returns An object with a `dispose` method which can be used to unregister
28
+ * the event listener.
27
29
  */
28
- onRetry(listener: Parameters<RpcService['onRetry']>[0]): {
30
+ onServiceRetry(listener: CockatielEventToEventListenerWithData<RpcService['onRetry'], {
31
+ primaryEndpointUrl: string;
32
+ }>): {
29
33
  dispose(): void;
30
34
  };
31
35
  /**
32
- * Listens for when any of the RPC services retry the request too many times
33
- * in a row.
36
+ * Calls the provided callback only when the maximum number of failed
37
+ * consecutive attempts to receive a 2xx response has been reached for all
38
+ * RPC services in the chain, and all services' underlying circuits have
39
+ * broken.
40
+ *
41
+ * The callback will not be called if a service's circuit breaks but its
42
+ * failover does not. Use `onServiceBreak` if you'd like a lower level of
43
+ * granularity.
44
+ *
45
+ * @param listener - The callback to be called.
46
+ * @returns An object with a `dispose` method which can be used to unregister
47
+ * the callback.
48
+ */
49
+ onBreak(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onBreak']>, 'endpointUrl'>) => void): import("cockatiel").IDisposable;
50
+ /**
51
+ * Calls the provided callback each time when, for *any* of the RPC services
52
+ * in this chain, the maximum number of failed consecutive attempts to receive
53
+ * a 2xx response has been reached and the underlying circuit has broken. A
54
+ * more granular version of `onBreak`.
34
55
  *
35
- * @param listener - The callback to be called when the retry occurs.
36
- * @returns What {@link RpcService.onBreak} returns.
56
+ * @param listener - The callback to be called.
57
+ * @returns An object with a `dispose` method which can be used to unregister
58
+ * the callback.
37
59
  */
38
- onBreak(listener: Parameters<RpcService['onBreak']>[0]): {
60
+ onServiceBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
61
+ primaryEndpointUrl: string;
62
+ }>): {
39
63
  dispose(): void;
40
64
  };
41
65
  /**
42
- * Listens for when any of the RPC services send a slow request.
66
+ * Calls the provided callback if no requests have been initiated yet or
67
+ * all requests to RPC services in this chain have responded successfully in a
68
+ * timely fashion, and then one of the two conditions apply:
43
69
  *
44
- * @param listener - The callback to be called when the retry occurs.
45
- * @returns What {@link RpcService.onRetry} returns.
70
+ * 1. When a retriable error is encountered making a request to an RPC
71
+ * service, and the request is retried until a set maximum is reached.
72
+ * 2. When a RPC service responds successfully, but the request takes longer
73
+ * than a set number of seconds to complete.
74
+ *
75
+ * Note that the callback will be called even if there are local connectivity
76
+ * issues which prevent requests from being initiated. This is intentional.
77
+ *
78
+ * Also note this callback will only be called if the RPC service chain as a
79
+ * whole is in a "degraded" state, and will then only be called once (e.g., it
80
+ * will not be called if a failover service falls into a degraded state, then
81
+ * the primary comes back online, but it is slow). Use `onServiceDegraded` if
82
+ * you'd like a lower level of granularity.
83
+ *
84
+ * @param listener - The callback to be called.
85
+ * @returns An object with a `dispose` method which can be used to unregister
86
+ * the callback.
46
87
  */
47
- onDegraded(listener: Parameters<RpcService['onDegraded']>[0]): {
88
+ onDegraded(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onDegraded']>, 'endpointUrl'>) => void): import("cockatiel").IDisposable;
89
+ /**
90
+ * Calls the provided callback each time one of the two conditions apply:
91
+ *
92
+ * 1. When a retriable error is encountered making a request to an RPC
93
+ * service, and the request is retried until a set maximum is reached.
94
+ * 2. When a RPC service responds successfully, but the request takes longer
95
+ * than a set number of seconds to complete.
96
+ *
97
+ * Note that the callback will be called even if there are local connectivity
98
+ * issues which prevent requests from being initiated. This is intentional.
99
+ *
100
+ * This is a more granular version of `onDegraded`. The callback will be
101
+ * called for each slow request to an RPC service. It may also be called again
102
+ * if a failover service falls into a degraded state, then the primary comes
103
+ * back online, but it is slow.
104
+ *
105
+ * @param listener - The callback to be called.
106
+ * @returns An object with a `dispose` method which can be used to unregister
107
+ * the callback.
108
+ */
109
+ onServiceDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
110
+ primaryEndpointUrl: string;
111
+ }>): {
48
112
  dispose(): void;
49
113
  };
50
114
  /**
51
- * Makes a request to the first RPC service in the chain. If this service is
52
- * down, then the request is forwarded to the next service in the chain, etc.
115
+ * Calls the provided callback in one of the following two conditions:
116
+ *
117
+ * 1. The first time that a 2xx request is made to any of the RPC services in
118
+ * this chain.
119
+ * 2. When requests to any the failover RPC services in this chain were
120
+ * failing such that they were degraded or their underyling circuits broke,
121
+ * but the first request to the primary succeeds again.
122
+ *
123
+ * Note this callback will only be called if the RPC service chain as a whole
124
+ * is in an "available" state.
125
+ *
126
+ * @param listener - The callback to be called.
127
+ * @returns An object with a `dispose` method which can be used to unregister
128
+ * the callback.
129
+ */
130
+ onAvailable(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onAvailable']>, 'endpointUrl'>) => void): import("cockatiel").IDisposable;
131
+ /**
132
+ * Uses the RPC services in the chain to make a request, using each service
133
+ * after the first as a fallback to the previous one as necessary.
53
134
  *
54
135
  * This overload is specifically designed for `eth_getBlockByNumber`, which
55
136
  * can return a `result` of `null` despite an expected `Result` being
@@ -69,8 +150,8 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
69
150
  method: 'eth_getBlockByNumber';
70
151
  }, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
71
152
  /**
72
- * Makes a request to the first RPC service in the chain. If this service is
73
- * down, then the request is forwarded to the next service in the chain, etc.
153
+ * Uses the RPC services in the chain to make a request, using each service
154
+ * after the first as a fallback to the previous one as necessary.
74
155
  *
75
156
  * This overload is designed for all RPC methods except for
76
157
  * `eth_getBlockByNumber`, which are expected to return a `result` of the
@@ -1 +1 @@
1
- {"version":3,"file":"rpc-service-chain.d.cts","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,cAAc,EACd,eAAe,EAChB,wBAAwB;AAEzB,OAAO,EAAE,UAAU,EAAE,0BAAsB;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,0BAAsB;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,sCAAkC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAiB;AAE7C;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;;IAG3D;;;;;;OAMG;gBAED,wBAAwB,EAAE,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE;IAKxE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAYtD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAYtD;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAY5D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG;QACjD,MAAM,EAAE,sBAAsB,CAAC;KAChC,EACD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CAiCpC"}
1
+ {"version":3,"file":"rpc-service-chain.d.cts","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,cAAc,EACd,eAAe,EAChB,wBAAwB;AAEzB,OAAO,EAAE,UAAU,EAAE,0BAAsB;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,0BAAsB;AACvD,OAAO,KAAK,EACV,qCAAqC,EACrC,yBAAyB,EACzB,yBAAyB,EACzB,YAAY,EACb,qBAAiB;AAoBlB;;;;;GAKG;AACH,qBAAa,eAAe;;IA8C1B;;;;;;OAMG;gBAED,wBAAwB,EAAE,CAAC,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAkDvE;;;;;;;;OAQG;IACH,cAAc,CACZ,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;OAaG;IACH,OAAO,CACL,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAChD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;OASG;IACH,cAAc,CACZ,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CACR,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EACnD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CACf,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,YAAY,CAAC,EACxB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CACT,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,EACpD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG;QACjD,MAAM,EAAE,sBAAsB,CAAC;KAChC,EACD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CA8FpC"}
@@ -1,15 +1,14 @@
1
1
  import type { Json, JsonRpcParams, JsonRpcRequest, JsonRpcResponse } from "@metamask/utils";
2
2
  import { RpcService } from "./rpc-service.mjs";
3
3
  import type { RpcServiceOptions } from "./rpc-service.mjs";
4
- import type { RpcServiceRequestable } from "./rpc-service-requestable.mjs";
5
- import type { FetchOptions } from "./shared.mjs";
4
+ import type { CockatielEventToEventListenerWithData, ExcludeCockatielEventData, ExtractCockatielEventData, FetchOptions } from "./shared.mjs";
6
5
  /**
7
- * This class constructs a chain of RpcService objects which represent a
8
- * particular network. The first object in the chain is intended to be the
9
- * primary way of reaching the network and the remaining objects are used as
10
- * failovers.
6
+ * This class constructs and manages requests to a chain of RpcService objects
7
+ * which represent RPC endpoints with which to access a particular network. The
8
+ * first service in the chain is intended to be the primary way of hitting the
9
+ * network and the remaining services are used as failovers.
11
10
  */
12
- export declare class RpcServiceChain implements RpcServiceRequestable {
11
+ export declare class RpcServiceChain {
13
12
  #private;
14
13
  /**
15
14
  * Constructs a new RpcServiceChain object.
@@ -18,38 +17,120 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
18
17
  * that you want to construct. Each object in this array is the same as
19
18
  * {@link RpcServiceOptions}.
20
19
  */
21
- constructor(rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[]);
20
+ constructor(rpcServiceConfigurations: [RpcServiceOptions, ...RpcServiceOptions[]]);
22
21
  /**
23
- * Listens for when any of the RPC services retry a request.
22
+ * Calls the provided callback when any of the RPC services is retried.
24
23
  *
25
- * @param listener - The callback to be called when the retry occurs.
26
- * @returns What {@link RpcService.onRetry} returns.
24
+ * This is mainly useful for tests.
25
+ *
26
+ * @param listener - The callback to be called.
27
+ * @returns An object with a `dispose` method which can be used to unregister
28
+ * the event listener.
27
29
  */
28
- onRetry(listener: Parameters<RpcService['onRetry']>[0]): {
30
+ onServiceRetry(listener: CockatielEventToEventListenerWithData<RpcService['onRetry'], {
31
+ primaryEndpointUrl: string;
32
+ }>): {
29
33
  dispose(): void;
30
34
  };
31
35
  /**
32
- * Listens for when any of the RPC services retry the request too many times
33
- * in a row.
36
+ * Calls the provided callback only when the maximum number of failed
37
+ * consecutive attempts to receive a 2xx response has been reached for all
38
+ * RPC services in the chain, and all services' underlying circuits have
39
+ * broken.
40
+ *
41
+ * The callback will not be called if a service's circuit breaks but its
42
+ * failover does not. Use `onServiceBreak` if you'd like a lower level of
43
+ * granularity.
44
+ *
45
+ * @param listener - The callback to be called.
46
+ * @returns An object with a `dispose` method which can be used to unregister
47
+ * the callback.
48
+ */
49
+ onBreak(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onBreak']>, 'endpointUrl'>) => void): import("cockatiel").IDisposable;
50
+ /**
51
+ * Calls the provided callback each time when, for *any* of the RPC services
52
+ * in this chain, the maximum number of failed consecutive attempts to receive
53
+ * a 2xx response has been reached and the underlying circuit has broken. A
54
+ * more granular version of `onBreak`.
34
55
  *
35
- * @param listener - The callback to be called when the retry occurs.
36
- * @returns What {@link RpcService.onBreak} returns.
56
+ * @param listener - The callback to be called.
57
+ * @returns An object with a `dispose` method which can be used to unregister
58
+ * the callback.
37
59
  */
38
- onBreak(listener: Parameters<RpcService['onBreak']>[0]): {
60
+ onServiceBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
61
+ primaryEndpointUrl: string;
62
+ }>): {
39
63
  dispose(): void;
40
64
  };
41
65
  /**
42
- * Listens for when any of the RPC services send a slow request.
66
+ * Calls the provided callback if no requests have been initiated yet or
67
+ * all requests to RPC services in this chain have responded successfully in a
68
+ * timely fashion, and then one of the two conditions apply:
43
69
  *
44
- * @param listener - The callback to be called when the retry occurs.
45
- * @returns What {@link RpcService.onRetry} returns.
70
+ * 1. When a retriable error is encountered making a request to an RPC
71
+ * service, and the request is retried until a set maximum is reached.
72
+ * 2. When a RPC service responds successfully, but the request takes longer
73
+ * than a set number of seconds to complete.
74
+ *
75
+ * Note that the callback will be called even if there are local connectivity
76
+ * issues which prevent requests from being initiated. This is intentional.
77
+ *
78
+ * Also note this callback will only be called if the RPC service chain as a
79
+ * whole is in a "degraded" state, and will then only be called once (e.g., it
80
+ * will not be called if a failover service falls into a degraded state, then
81
+ * the primary comes back online, but it is slow). Use `onServiceDegraded` if
82
+ * you'd like a lower level of granularity.
83
+ *
84
+ * @param listener - The callback to be called.
85
+ * @returns An object with a `dispose` method which can be used to unregister
86
+ * the callback.
46
87
  */
47
- onDegraded(listener: Parameters<RpcService['onDegraded']>[0]): {
88
+ onDegraded(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onDegraded']>, 'endpointUrl'>) => void): import("cockatiel").IDisposable;
89
+ /**
90
+ * Calls the provided callback each time one of the two conditions apply:
91
+ *
92
+ * 1. When a retriable error is encountered making a request to an RPC
93
+ * service, and the request is retried until a set maximum is reached.
94
+ * 2. When a RPC service responds successfully, but the request takes longer
95
+ * than a set number of seconds to complete.
96
+ *
97
+ * Note that the callback will be called even if there are local connectivity
98
+ * issues which prevent requests from being initiated. This is intentional.
99
+ *
100
+ * This is a more granular version of `onDegraded`. The callback will be
101
+ * called for each slow request to an RPC service. It may also be called again
102
+ * if a failover service falls into a degraded state, then the primary comes
103
+ * back online, but it is slow.
104
+ *
105
+ * @param listener - The callback to be called.
106
+ * @returns An object with a `dispose` method which can be used to unregister
107
+ * the callback.
108
+ */
109
+ onServiceDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
110
+ primaryEndpointUrl: string;
111
+ }>): {
48
112
  dispose(): void;
49
113
  };
50
114
  /**
51
- * Makes a request to the first RPC service in the chain. If this service is
52
- * down, then the request is forwarded to the next service in the chain, etc.
115
+ * Calls the provided callback in one of the following two conditions:
116
+ *
117
+ * 1. The first time that a 2xx request is made to any of the RPC services in
118
+ * this chain.
119
+ * 2. When requests to any the failover RPC services in this chain were
120
+ * failing such that they were degraded or their underyling circuits broke,
121
+ * but the first request to the primary succeeds again.
122
+ *
123
+ * Note this callback will only be called if the RPC service chain as a whole
124
+ * is in an "available" state.
125
+ *
126
+ * @param listener - The callback to be called.
127
+ * @returns An object with a `dispose` method which can be used to unregister
128
+ * the callback.
129
+ */
130
+ onAvailable(listener: (data: ExcludeCockatielEventData<ExtractCockatielEventData<RpcService['onAvailable']>, 'endpointUrl'>) => void): import("cockatiel").IDisposable;
131
+ /**
132
+ * Uses the RPC services in the chain to make a request, using each service
133
+ * after the first as a fallback to the previous one as necessary.
53
134
  *
54
135
  * This overload is specifically designed for `eth_getBlockByNumber`, which
55
136
  * can return a `result` of `null` despite an expected `Result` being
@@ -69,8 +150,8 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
69
150
  method: 'eth_getBlockByNumber';
70
151
  }, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
71
152
  /**
72
- * Makes a request to the first RPC service in the chain. If this service is
73
- * down, then the request is forwarded to the next service in the chain, etc.
153
+ * Uses the RPC services in the chain to make a request, using each service
154
+ * after the first as a fallback to the previous one as necessary.
74
155
  *
75
156
  * This overload is designed for all RPC methods except for
76
157
  * `eth_getBlockByNumber`, which are expected to return a `result` of the
@@ -1 +1 @@
1
- {"version":3,"file":"rpc-service-chain.d.mts","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,cAAc,EACd,eAAe,EAChB,wBAAwB;AAEzB,OAAO,EAAE,UAAU,EAAE,0BAAsB;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,0BAAsB;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,sCAAkC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAiB;AAE7C;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;;IAG3D;;;;;;OAMG;gBAED,wBAAwB,EAAE,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE;IAKxE;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAYtD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAYtD;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;;;IAY5D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG;QACjD,MAAM,EAAE,sBAAsB,CAAC;KAChC,EACD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CAiCpC"}
1
+ {"version":3,"file":"rpc-service-chain.d.mts","sourceRoot":"","sources":["../../src/rpc-service/rpc-service-chain.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,cAAc,EACd,eAAe,EAChB,wBAAwB;AAEzB,OAAO,EAAE,UAAU,EAAE,0BAAsB;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,0BAAsB;AACvD,OAAO,KAAK,EACV,qCAAqC,EACrC,yBAAyB,EACzB,yBAAyB,EACzB,YAAY,EACb,qBAAiB;AAoBlB;;;;;GAKG;AACH,qBAAa,eAAe;;IA8C1B;;;;;;OAMG;gBAED,wBAAwB,EAAE,CAAC,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAkDvE;;;;;;;;OAQG;IACH,cAAc,CACZ,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;OAaG;IACH,OAAO,CACL,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAChD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;OASG;IACH,cAAc,CACZ,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CACR,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EACnD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CACf,QAAQ,EAAE,qCAAqC,CAC7C,UAAU,CAAC,YAAY,CAAC,EACxB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;;;IAkBH;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CACT,QAAQ,EAAE,CACR,IAAI,EAAE,yBAAyB,CAC7B,yBAAyB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,EACpD,aAAa,CACd,KACE,IAAI;IAKX;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG;QACjD,MAAM,EAAE,sBAAsB,CAAC;KAChC,EACD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,MAAM,SAAS,aAAa,EAAE,MAAM,SAAS,IAAI,EAC7D,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAChD,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;CA8FpC"}