Allow agent to claim custom networks

[aryanjassal]

Description

The Polykey agent needs a way to join a network. The target network can either be a public or a private one. he network join can be triggered at any time in the agent's lifecycle. First, when starting, the --network flag should be able to change the network to one created by PKE as well as the testnet and mainnet. The second should be a RPC handler which will allow the network switching logic to happen while the agent is still running.

Issues Fixed

• Addresses Allow agent to join a network using network access tokens #923 (REF ENG-643)

Tasks

• 1. Update network access claim to prevent making duplicate claims for the same network
• 2. Update syncNodeGraph to claim the network if a claim does not exist, otherwise switch the network to the target network
• 3. Create a RPC handler wrapping this network switching behaviour

Final checklist

• Domain specific tests
• Full tests
• Updated inline-comment documentation
• Lint fixed
• Squash and rebased
• Sanity check the final build

[linear]

ENG-643

[aryanjassal]

After discussing this issue in our sprint, we have highlighted some behavioural questions regarding network switching. This issue is only relevant for when the network is switched in the middle of the agent's lifecycle.

If we start the agent on a network, then we can start with creating new connections to the nodes in that network. There is no issues in this case. However, if we are switching from a network to another one, then how should the agent behave? The agent will need to end old connections and start new connections in the new network. What if a peer has a stream open to our node? If we choose to reject new connections and wait for the previous stream to end, then wouldn't it also suffer from similar issues that sometimes the agent shutdown suffers with, when some tasks or streams just refuse to cancel?

The tests might be able to catch some of these issues. We also need to plan for the behaviour of this function properly to avoid some of these hidden issues or make the system more brittle.

[aryanjassal]

Brian and I ran into another question when working on this PR. The network at the startup is provided by an option in the polykey agent. However, this option has a type of string | undefined. The network is expected to always be a string. Thus, how do we want to handle an undefined network in this case? Do we disable the network claiming? Or do we prevent undefined values and instead force this to be a valid string, throwing if it is undefined when the agent is starting up?

Currently, I have just disabled the network claiming logic when the network is undefined, but I feel that this is not the optimal behaviour. I believe raising an error when starting the agent if the network is unpopulated seems to be the optimal solution here.

[aryanjassal]

This PR is ready for merging. I will start working on the PKCLI side of this issue now before merging them both.

[CMCDragonkai]

Brian and I ran into another question when working on this PR. The network at the startup is provided by an option in the polykey agent. However, this option has a type of string | undefined. The network is expected to always be a string. Thus, how do we want to handle an undefined network in this case? Do we disable the network claiming? Or do we prevent undefined values and instead force this to be a valid string, throwing if it is undefined when the agent is starting up?

Currently, I have just disabled the network claiming logic when the network is undefined, but I feel that this is not the optimal behaviour. I believe raising an error when starting the agent if the network is unpopulated seems to be the optimal solution here.

Why is the network allowed to be undefined? Perhaps it means there is no network it's part of. In which case claiming a network means setting that network option.