@metamask-previews/network-controller 25.0.0-preview-4cd9da8d → 26.0.0-preview-e3eb8eca

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 +32 -2
  2. package/dist/NetworkController.cjs +37 -10
  3. package/dist/NetworkController.cjs.map +1 -1
  4. package/dist/NetworkController.d.cts +146 -11
  5. package/dist/NetworkController.d.cts.map +1 -1
  6. package/dist/NetworkController.d.mts +146 -11
  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 +115 -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 +115 -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 +255 -39
  41. package/dist/rpc-service/rpc-service-chain.cjs.map +1 -1
  42. package/dist/rpc-service/rpc-service-chain.d.cts +117 -25
  43. package/dist/rpc-service/rpc-service-chain.d.cts.map +1 -1
  44. package/dist/rpc-service/rpc-service-chain.d.mts +117 -25
  45. package/dist/rpc-service/rpc-service-chain.d.mts.map +1 -1
  46. package/dist/rpc-service/rpc-service-chain.mjs +255 -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 +63 -33
  55. package/dist/rpc-service/rpc-service.cjs.map +1 -1
  56. package/dist/rpc-service/rpc-service.d.cts +35 -24
  57. package/dist/rpc-service/rpc-service.d.cts.map +1 -1
  58. package/dist/rpc-service/rpc-service.d.mts +35 -24
  59. package/dist/rpc-service/rpc-service.d.mts.map +1 -1
  60. package/dist/rpc-service/rpc-service.mjs +64 -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 +30 -3
  64. package/dist/rpc-service/shared.d.cts.map +1 -1
  65. package/dist/rpc-service/shared.d.mts +30 -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 +7 -6
@@ -1,15 +1,15 @@
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, FetchOptions } from "./shared.cjs";
5
+ type RpcServiceConfiguration = Omit<RpcServiceOptions, 'failoverService'>;
6
6
  /**
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.
7
+ * This class constructs and manages requests to a chain of RpcService objects
8
+ * which represent RPC endpoints with which to access a particular network. The
9
+ * first service in the chain is intended to be the primary way of hitting the
10
+ * network and the remaining services are used as failovers.
11
11
  */
12
- export declare class RpcServiceChain implements RpcServiceRequestable {
12
+ export declare class RpcServiceChain {
13
13
  #private;
14
14
  /**
15
15
  * Constructs a new RpcServiceChain object.
@@ -18,38 +18,129 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
18
18
  * that you want to construct. Each object in this array is the same as
19
19
  * {@link RpcServiceOptions}.
20
20
  */
21
- constructor(rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[]);
21
+ constructor(rpcServiceConfigurations: [
22
+ RpcServiceConfiguration,
23
+ ...RpcServiceConfiguration[]
24
+ ]);
22
25
  /**
23
- * Listens for when any of the RPC services retry a request.
26
+ * Calls the provided callback when any of the RPC services is retried.
24
27
  *
25
- * @param listener - The callback to be called when the retry occurs.
26
- * @returns What {@link RpcService.onRetry} returns.
28
+ * This is mainly useful for tests.
29
+ *
30
+ * @param listener - The callback to be called.
31
+ * @returns An object with a `dispose` method which can be used to unregister
32
+ * the event listener.
27
33
  */
28
- onRetry(listener: Parameters<RpcService['onRetry']>[0]): {
34
+ onServiceRetry(listener: CockatielEventToEventListenerWithData<RpcService['onRetry'], {
35
+ primaryEndpointUrl: string;
36
+ }>): {
29
37
  dispose(): void;
30
38
  };
31
39
  /**
32
- * Listens for when any of the RPC services retry the request too many times
33
- * in a row.
40
+ * Calls the provided callback only when the maximum number of failed
41
+ * consecutive attempts to receive a 2xx response has been reached for all
42
+ * RPC services in the chain, and all services' underlying circuits have
43
+ * broken.
44
+ *
45
+ * The callback will not be called if a service's circuit breaks but its
46
+ * failover does not. Use `onServiceBreak` if you'd like a lower level of
47
+ * granularity.
48
+ *
49
+ * @param listener - The callback to be called.
50
+ * @returns An object with a `dispose` method which can be used to unregister
51
+ * the callback.
52
+ */
53
+ onBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
54
+ primaryEndpointUrl: string;
55
+ }>): import("cockatiel").IDisposable;
56
+ /**
57
+ * Calls the provided callback each time when, for *any* of the RPC services
58
+ * in this chain, the maximum number of failed consecutive attempts to receive
59
+ * a 2xx response has been reached and the underlying circuit has broken. A
60
+ * more granular version of `onBreak`.
34
61
  *
35
- * @param listener - The callback to be called when the retry occurs.
36
- * @returns What {@link RpcService.onBreak} returns.
62
+ * @param listener - The callback to be called.
63
+ * @returns An object with a `dispose` method which can be used to unregister
64
+ * the callback.
37
65
  */
38
- onBreak(listener: Parameters<RpcService['onBreak']>[0]): {
66
+ onServiceBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
67
+ primaryEndpointUrl: string;
68
+ }>): {
39
69
  dispose(): void;
40
70
  };
41
71
  /**
42
- * Listens for when any of the RPC services send a slow request.
72
+ * Calls the provided callback if no requests have been initiated yet or
73
+ * all requests to RPC services in this chain have responded successfully in a
74
+ * timely fashion, and then one of the two conditions apply:
43
75
  *
44
- * @param listener - The callback to be called when the retry occurs.
45
- * @returns What {@link RpcService.onRetry} returns.
76
+ * 1. When a retriable error is encountered making a request to an RPC
77
+ * service, and the request is retried until a set maximum is reached.
78
+ * 2. When a RPC service responds successfully, but the request takes longer
79
+ * than a set number of seconds to complete.
80
+ *
81
+ * Note that the callback will be called even if there are local connectivity
82
+ * issues which prevent requests from being initiated. This is intentional.
83
+ *
84
+ * Also note this callback will only be called if the RPC service chain as a
85
+ * whole is in a "degraded" state, and will then only be called once (e.g., it
86
+ * will not be called if a failover service falls into a degraded state, then
87
+ * the primary comes back online, but it is slow). Use `onServiceDegraded` if
88
+ * you'd like a lower level of granularity.
89
+ *
90
+ * @param listener - The callback to be called.
91
+ * @returns An object with a `dispose` method which can be used to unregister
92
+ * the callback.
46
93
  */
47
- onDegraded(listener: Parameters<RpcService['onDegraded']>[0]): {
94
+ onDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
95
+ primaryEndpointUrl: string;
96
+ }>): import("cockatiel").IDisposable;
97
+ /**
98
+ * Calls the provided callback each time one of the two conditions apply:
99
+ *
100
+ * 1. When a retriable error is encountered making a request to an RPC
101
+ * service, and the request is retried until a set maximum is reached.
102
+ * 2. When a RPC service responds successfully, but the request takes longer
103
+ * than a set number of seconds to complete.
104
+ *
105
+ * Note that the callback will be called even if there are local connectivity
106
+ * issues which prevent requests from being initiated. This is intentional.
107
+ *
108
+ * This is a more granular version of `onDegraded`. The callback will be
109
+ * called for each slow request to an RPC service. It may also be called again
110
+ * if a failover service falls into a degraded state, then the primary comes
111
+ * back online, but it is slow.
112
+ *
113
+ * @param listener - The callback to be called.
114
+ * @returns An object with a `dispose` method which can be used to unregister
115
+ * the callback.
116
+ */
117
+ onServiceDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
118
+ primaryEndpointUrl: string;
119
+ }>): {
48
120
  dispose(): void;
49
121
  };
50
122
  /**
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.
123
+ * Calls the provided callback in one of the following two conditions:
124
+ *
125
+ * 1. The first time that a 2xx request is made to any of the RPC services in
126
+ * this chain.
127
+ * 2. When requests to any the failover RPC services in this chain were
128
+ * failing such that they were degraded or their underyling circuits broke,
129
+ * but the first request to the primary succeeds again.
130
+ *
131
+ * Note this callback will only be called if the RPC service chain as a whole
132
+ * is in an "available" state.
133
+ *
134
+ * @param listener - The callback to be called.
135
+ * @returns An object with a `dispose` method which can be used to unregister
136
+ * the callback.
137
+ */
138
+ onAvailable(listener: CockatielEventToEventListenerWithData<RpcService['onAvailable'], {
139
+ primaryEndpointUrl: string;
140
+ }>): import("cockatiel").IDisposable;
141
+ /**
142
+ * Uses the RPC services in the chain to make a request, using each service
143
+ * after the first as a fallback to the previous one as necessary.
53
144
  *
54
145
  * This overload is specifically designed for `eth_getBlockByNumber`, which
55
146
  * can return a `result` of `null` despite an expected `Result` being
@@ -69,8 +160,8 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
69
160
  method: 'eth_getBlockByNumber';
70
161
  }, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
71
162
  /**
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.
163
+ * Uses the RPC services in the chain to make a request, using each service
164
+ * after the first as a fallback to the previous one as necessary.
74
165
  *
75
166
  * This overload is designed for all RPC methods except for
76
167
  * `eth_getBlockByNumber`, which are expected to return a `result` of the
@@ -88,4 +179,5 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
88
179
  */
89
180
  request<Params extends JsonRpcParams, Result extends Json>(jsonRpcRequest: Readonly<JsonRpcRequest<Params>>, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result>>;
90
181
  }
182
+ export {};
91
183
  //# sourceMappingURL=rpc-service-chain.d.cts.map
@@ -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,EAEV,qCAAqC,EAGrC,YAAY,EACb,qBAAiB;AAoBlB,KAAK,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,qBAAa,eAAe;;IAwC1B;;;;;;OAMG;gBAED,wBAAwB,EAAE;QACxB,uBAAuB;QACvB,GAAG,uBAAuB,EAAE;KAC7B;IA4CH;;;;;;;;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,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;IAKH;;;;;;;;;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,qCAAqC,CAC7C,UAAU,CAAC,YAAY,CAAC,EACxB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;IAKH;;;;;;;;;;;;;;;;;;;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,qCAAqC,CAC7C,UAAU,CAAC,aAAa,CAAC,EACzB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;IAKH;;;;;;;;;;;;;;;;;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;CAyGpC"}
@@ -1,15 +1,15 @@
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, FetchOptions } from "./shared.mjs";
5
+ type RpcServiceConfiguration = Omit<RpcServiceOptions, 'failoverService'>;
6
6
  /**
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.
7
+ * This class constructs and manages requests to a chain of RpcService objects
8
+ * which represent RPC endpoints with which to access a particular network. The
9
+ * first service in the chain is intended to be the primary way of hitting the
10
+ * network and the remaining services are used as failovers.
11
11
  */
12
- export declare class RpcServiceChain implements RpcServiceRequestable {
12
+ export declare class RpcServiceChain {
13
13
  #private;
14
14
  /**
15
15
  * Constructs a new RpcServiceChain object.
@@ -18,38 +18,129 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
18
18
  * that you want to construct. Each object in this array is the same as
19
19
  * {@link RpcServiceOptions}.
20
20
  */
21
- constructor(rpcServiceConfigurations: Omit<RpcServiceOptions, 'failoverService'>[]);
21
+ constructor(rpcServiceConfigurations: [
22
+ RpcServiceConfiguration,
23
+ ...RpcServiceConfiguration[]
24
+ ]);
22
25
  /**
23
- * Listens for when any of the RPC services retry a request.
26
+ * Calls the provided callback when any of the RPC services is retried.
24
27
  *
25
- * @param listener - The callback to be called when the retry occurs.
26
- * @returns What {@link RpcService.onRetry} returns.
28
+ * This is mainly useful for tests.
29
+ *
30
+ * @param listener - The callback to be called.
31
+ * @returns An object with a `dispose` method which can be used to unregister
32
+ * the event listener.
27
33
  */
28
- onRetry(listener: Parameters<RpcService['onRetry']>[0]): {
34
+ onServiceRetry(listener: CockatielEventToEventListenerWithData<RpcService['onRetry'], {
35
+ primaryEndpointUrl: string;
36
+ }>): {
29
37
  dispose(): void;
30
38
  };
31
39
  /**
32
- * Listens for when any of the RPC services retry the request too many times
33
- * in a row.
40
+ * Calls the provided callback only when the maximum number of failed
41
+ * consecutive attempts to receive a 2xx response has been reached for all
42
+ * RPC services in the chain, and all services' underlying circuits have
43
+ * broken.
44
+ *
45
+ * The callback will not be called if a service's circuit breaks but its
46
+ * failover does not. Use `onServiceBreak` if you'd like a lower level of
47
+ * granularity.
48
+ *
49
+ * @param listener - The callback to be called.
50
+ * @returns An object with a `dispose` method which can be used to unregister
51
+ * the callback.
52
+ */
53
+ onBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
54
+ primaryEndpointUrl: string;
55
+ }>): import("cockatiel").IDisposable;
56
+ /**
57
+ * Calls the provided callback each time when, for *any* of the RPC services
58
+ * in this chain, the maximum number of failed consecutive attempts to receive
59
+ * a 2xx response has been reached and the underlying circuit has broken. A
60
+ * more granular version of `onBreak`.
34
61
  *
35
- * @param listener - The callback to be called when the retry occurs.
36
- * @returns What {@link RpcService.onBreak} returns.
62
+ * @param listener - The callback to be called.
63
+ * @returns An object with a `dispose` method which can be used to unregister
64
+ * the callback.
37
65
  */
38
- onBreak(listener: Parameters<RpcService['onBreak']>[0]): {
66
+ onServiceBreak(listener: CockatielEventToEventListenerWithData<RpcService['onBreak'], {
67
+ primaryEndpointUrl: string;
68
+ }>): {
39
69
  dispose(): void;
40
70
  };
41
71
  /**
42
- * Listens for when any of the RPC services send a slow request.
72
+ * Calls the provided callback if no requests have been initiated yet or
73
+ * all requests to RPC services in this chain have responded successfully in a
74
+ * timely fashion, and then one of the two conditions apply:
43
75
  *
44
- * @param listener - The callback to be called when the retry occurs.
45
- * @returns What {@link RpcService.onRetry} returns.
76
+ * 1. When a retriable error is encountered making a request to an RPC
77
+ * service, and the request is retried until a set maximum is reached.
78
+ * 2. When a RPC service responds successfully, but the request takes longer
79
+ * than a set number of seconds to complete.
80
+ *
81
+ * Note that the callback will be called even if there are local connectivity
82
+ * issues which prevent requests from being initiated. This is intentional.
83
+ *
84
+ * Also note this callback will only be called if the RPC service chain as a
85
+ * whole is in a "degraded" state, and will then only be called once (e.g., it
86
+ * will not be called if a failover service falls into a degraded state, then
87
+ * the primary comes back online, but it is slow). Use `onServiceDegraded` if
88
+ * you'd like a lower level of granularity.
89
+ *
90
+ * @param listener - The callback to be called.
91
+ * @returns An object with a `dispose` method which can be used to unregister
92
+ * the callback.
46
93
  */
47
- onDegraded(listener: Parameters<RpcService['onDegraded']>[0]): {
94
+ onDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
95
+ primaryEndpointUrl: string;
96
+ }>): import("cockatiel").IDisposable;
97
+ /**
98
+ * Calls the provided callback each time one of the two conditions apply:
99
+ *
100
+ * 1. When a retriable error is encountered making a request to an RPC
101
+ * service, and the request is retried until a set maximum is reached.
102
+ * 2. When a RPC service responds successfully, but the request takes longer
103
+ * than a set number of seconds to complete.
104
+ *
105
+ * Note that the callback will be called even if there are local connectivity
106
+ * issues which prevent requests from being initiated. This is intentional.
107
+ *
108
+ * This is a more granular version of `onDegraded`. The callback will be
109
+ * called for each slow request to an RPC service. It may also be called again
110
+ * if a failover service falls into a degraded state, then the primary comes
111
+ * back online, but it is slow.
112
+ *
113
+ * @param listener - The callback to be called.
114
+ * @returns An object with a `dispose` method which can be used to unregister
115
+ * the callback.
116
+ */
117
+ onServiceDegraded(listener: CockatielEventToEventListenerWithData<RpcService['onDegraded'], {
118
+ primaryEndpointUrl: string;
119
+ }>): {
48
120
  dispose(): void;
49
121
  };
50
122
  /**
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.
123
+ * Calls the provided callback in one of the following two conditions:
124
+ *
125
+ * 1. The first time that a 2xx request is made to any of the RPC services in
126
+ * this chain.
127
+ * 2. When requests to any the failover RPC services in this chain were
128
+ * failing such that they were degraded or their underyling circuits broke,
129
+ * but the first request to the primary succeeds again.
130
+ *
131
+ * Note this callback will only be called if the RPC service chain as a whole
132
+ * is in an "available" state.
133
+ *
134
+ * @param listener - The callback to be called.
135
+ * @returns An object with a `dispose` method which can be used to unregister
136
+ * the callback.
137
+ */
138
+ onAvailable(listener: CockatielEventToEventListenerWithData<RpcService['onAvailable'], {
139
+ primaryEndpointUrl: string;
140
+ }>): import("cockatiel").IDisposable;
141
+ /**
142
+ * Uses the RPC services in the chain to make a request, using each service
143
+ * after the first as a fallback to the previous one as necessary.
53
144
  *
54
145
  * This overload is specifically designed for `eth_getBlockByNumber`, which
55
146
  * can return a `result` of `null` despite an expected `Result` being
@@ -69,8 +160,8 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
69
160
  method: 'eth_getBlockByNumber';
70
161
  }, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result> | JsonRpcResponse<null>>;
71
162
  /**
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.
163
+ * Uses the RPC services in the chain to make a request, using each service
164
+ * after the first as a fallback to the previous one as necessary.
74
165
  *
75
166
  * This overload is designed for all RPC methods except for
76
167
  * `eth_getBlockByNumber`, which are expected to return a `result` of the
@@ -88,4 +179,5 @@ export declare class RpcServiceChain implements RpcServiceRequestable {
88
179
  */
89
180
  request<Params extends JsonRpcParams, Result extends Json>(jsonRpcRequest: Readonly<JsonRpcRequest<Params>>, fetchOptions?: FetchOptions): Promise<JsonRpcResponse<Result>>;
90
181
  }
182
+ export {};
91
183
  //# sourceMappingURL=rpc-service-chain.d.mts.map
@@ -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,EAEV,qCAAqC,EAGrC,YAAY,EACb,qBAAiB;AAoBlB,KAAK,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,qBAAa,eAAe;;IAwC1B;;;;;;OAMG;gBAED,wBAAwB,EAAE;QACxB,uBAAuB;QACvB,GAAG,uBAAuB,EAAE;KAC7B;IA4CH;;;;;;;;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,qCAAqC,CAC7C,UAAU,CAAC,SAAS,CAAC,EACrB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;IAKH;;;;;;;;;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,qCAAqC,CAC7C,UAAU,CAAC,YAAY,CAAC,EACxB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;IAKH;;;;;;;;;;;;;;;;;;;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,qCAAqC,CAC7C,UAAU,CAAC,aAAa,CAAC,EACzB;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,CAC/B;IAKH;;;;;;;;;;;;;;;;;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;CAyGpC"}