Test subscription-based APIs

[elmattic]

Summary

We want to validate that subscription APIs are working correctly.

Right now, our api-compare tool isn’t sufficient to properly test these APIs. We would like to create simple integration scripts that run WebSocket clients connecting directly to the node.

Filecoin.ChainNotify

First, we want to test that the channel mechanism itself is functioning correctly. We can use the existing data-flow diagram as a reference to test different message payloads for creating and closing channels. It’s very important to ensure that multiple channels can be active simultaneously.

Then, we need to test the different types of notifications that ChainNotify can emit:

• "current": the current head tipset
• "apply": a new tipset added to the chain
• "revert": a chain reorganization occurred, and a tipset was reverted

To validate the responses:

• Mine new blocks using the devnet/miner.
• Force a reorg by stopping one miner and modifying weight rules.
• Simulate null rounds by briefly disabling mining.

We can start by writing integration tests on calibnet to cover channel creation/closing.

For the specific types of notifications, we can choose the most practical testing approach. Same for the scripting language (hint: Ruby is a good pick).

eth_subscribe / eth_unsubscribe

Similarly, we want to test opening and closing subscriptions, and then focus on testing the different event types:

• "newHeads"
• "newPendingTransactions"
• "logs" (with and without filter parameters)

We need to ensure that performance scales well with the number of WebSocket clients (around 100s).

✅ Note

We should ensure that #5793 is completed first, as we might want to leverage the internal EthEventHandler type to factor out and reuse filtering logic across these endpoints.

Also, these scripts should ideally be written to also work against Lotus, the reference implementation. This way, we can first validate correctness on Lotus, then run them against Forest to ensure compatibility.

Completion Criteria

All integration tests and unit tests (if necessary) are passing.

Additional Links & Resources

[LesnyRumcajs]

@elmattic Is this done via the stateful tests?

[elmattic]

No, not yet, but those kinds of subscription tests should be part of the stateful tests.