feat: add ping option to fallback transport (#2642)

* adding rankMethod parameter to fallback transport

* chore: tweaks

* chore: tweaks

* chore: tweaks

* chore: tweaks

* chore: changeset

---------

Co-authored-by: jxom <[email protected]>

.changeset/new-papayas-draw.md

@@ -0,0 +1,5 @@
+---
+"viem": patch
+---
+
+Added `ping` option to `fallback` Transport.

site/pages/docs/clients/transports/fallback.md

@@ -114,6 +114,27 @@ const transport = fallback([alchemy, infura], {
 })
 ```
 
+### rank.ping (optional)
+
+- **Type:** `({ transport }: { transport: Transport }) => Promise<unknown>`
+- **Default:** `({ transport }) => transport.request({ method: 'net_listening' })`
+
+Function to call to ping the Transport. Defaults to calling the `net_listening` method to check if the Transport is online.
+
+```ts twoslash
+// @noErrors
+import { createPublicClient, fallback, http } from 'viem'
+import { mainnet } from 'viem/chains'
+const alchemy = http('') 
+const infura = http('') 
+// ---cut---
+const transport = fallback([alchemy, infura], {
+  rank: { // [!code focus:3]
+    ping: ({ transport }) => transport.request({ method: 'eth_blockNumber' })
+  },
+})
+```
+
 ### rank.sampleCount (optional)
 
 - **Type:** `number`

src/clients/transports/fallback.test.ts

@@ -828,4 +828,42 @@ describe('rankTransports', () => {
       ]
     `)
   })
+
+  test('behavior: custom ping', async () => {
+    const results: { method: string }[] = []
+
+    const server = await createHttpServer((req, res) => {
+      req.setEncoding('utf8')
+      req.on('data', (body) => {
+        results.push(JSON.parse(body))
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ result: '0x1' }))
+      })
+    })
+
+    const transport1 = http(server.url, { key: '1' })
+
+    let count = 0
+    rankTransports({
+      chain: localhost,
+      interval: 10,
+      transports: [transport1],
+      onTransports() {},
+      ping({ transport }) {
+        count++
+        return transport.request({
+          method: count % 2 === 0 ? 'eth_blockNumber' : 'eth_getBlockByNumber',
+        })
+      },
+    })
+
+    await wait(20)
+
+    expect(results.map((r) => r.method)).toMatchInlineSnapshot(`
+      [
+        "eth_getBlockByNumber",
+        "eth_blockNumber",
+      ]
+    `)
+  })
 })

src/clients/transports/fallback.ts

@@ -38,6 +38,12 @@ type RankOptions = {
    * @default client.pollingInterval
    */
   interval?: number | undefined
+  /**
+   * Ping method to determine latency.
+   */
+  ping?: (parameters: { transport: ReturnType<Transport> }) =>
+    | Promise<unknown>
+    | undefined
   /**
    * The number of previous samples to perform ranking on.
    * @default 10
@@ -173,6 +179,7 @@ export function fallback<const transports extends readonly Transport[]>(
         chain,
         interval: rankOptions.interval ?? pollingInterval,
         onTransports: (transports_) => (transports = transports_ as transports),
+        ping: rankOptions.ping,
         sampleCount: rankOptions.sampleCount,
         timeout: rankOptions.timeout,
         transports,
@@ -200,6 +207,7 @@ export function rankTransports({
   chain,
   interval = 4_000,
   onTransports,
+  ping,
   sampleCount = 10,
   timeout = 1_000,
   transports,
@@ -208,6 +216,7 @@ export function rankTransports({
   chain?: Chain | undefined
   interval: RankOptions['interval']
   onTransports: (transports: readonly Transport[]) => void
+  ping?: RankOptions['ping'] | undefined
   sampleCount?: RankOptions['sampleCount'] | undefined
   timeout?: RankOptions['timeout'] | undefined
   transports: readonly Transport[]
@@ -230,7 +239,9 @@ export function rankTransports({
         let end: number
         let success: number
         try {
-          await transport_.request({ method: 'net_listening' })
+          await (ping
+            ? ping({ transport: transport_ })
+            : transport_.request({ method: 'net_listening' }))
           success = 1
         } catch {
           success = 0