fix!: rename "transient" connections to "limited"

[achingbrain]

To better align with [email protected] rename "transient" connections to "limited".

BREAKING CHANGE: There are three breaking API changes:

• The .transient boolean property has been replaced with a .limits object that may be undefined or may have .bytes and/or .seconds properties - the value of these properties decreases as the limits are used up
• The runOnTransientConnection property of libp2p.handle and libp2p.dialProtocol has been renamed to runOnLimitedConnection
• The notifyOnTransient property of libp2p.register has been renamed notifyOnLimitedConnection

Refs: #2622

Change checklist

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation if necessary (this includes comments as well)
• I have added tests that prove my fix is effective or that my feature works

[achingbrain]

I've backed away from removing runLimitedConnection and notifyOnLimitedConnection because there are cases when you cannot make the decision ahead of time, such as:

const stream = await libp2p.dialProcotol(peerId, '/my/protocol/1.0.0')

In the above since you're dialing the protocol on the remote peer and not a multiaddr, you don't know ahead of time if you are connected or if the connection is relayed/direct/limited so the runLimitedConnection option provides an escape hatch.

Happy to discuss further if anyone has a better idea for the API.

[maschad]

Nice work.

1. A minor comment adjustment here

2. we don't really have any docs around this but I suppose we still should have a migration guide correct?

[SgtPooki]

I've backed away from removing runLimitedConnection and notifyOnLimitedConnection because there are cases when you cannot make the decision ahead of time, such as:

const stream = await libp2p.dialProcotol(peerId, '/my/protocol/1.0.0')

In the above since you're dialing the protocol on the remote peer and not a multiaddr, you don't know ahead of time if you are connected or if the connection is relayed/direct/limited so the runLimitedConnection option provides an escape hatch.

Happy to discuss further if anyone has a better idea for the API.

I think your rationale is sound. Though I'm not sure where the "removing" work was happening or what that consisted of. I'm guessing you were thinking of removing

js-libp2p/packages/interface/src/connection/index.ts

Line 193 in c5dba70

runOnTransientConnection?: boolean

?

Do we have a best practice or prior art for whether we default API decisions to a "try, analyze, retry" vs "config for goal success" ?

I know we don't like to "config all the things" but it seems like js-libp2p likes to go the "config for goal success" route: i.e. when we make a function call, we want devs to pass whatever they need to ensure they can achieve their ideal outcome on first try. so.. for dialProtocol, having a runOnLimitedConnection option available that devs can configure would be good.

[achingbrain]

Though I'm not sure where the "removing" work was happening or what that consisted of.

See the linked issue mentioned in the op.

Do we have a best practice or prior art for whether we default API decisions to a "try, analyze, retry" vs "config for goal success" ?

Best practice is generally to avoid network operations wherever possible as I/O is the death of performance. In this case to make two attempts at opening a stream (and potentially a connection) could be very expensive so should be avoided.