mirror of
https://github.com/fluencelabs/js-libp2p
synced 2025-03-16 15:40:49 +00:00
doc: add initial dialer readme
This commit is contained in:
parent
ce8e60bb0d
commit
2329ef3ea3
36
doc/DIALER.md
Normal file
36
doc/DIALER.md
Normal file
@ -0,0 +1,36 @@
|
||||
# js-libp2p Dialer
|
||||
|
||||
**Synopsis**
|
||||
* All Dial Requests in js-libp2p must request a token(s) from the Dialer.
|
||||
* The number of tokens requested should be between 1 and the PER_PEER_LIMIT max set in the Dialer.
|
||||
* If the number of available tokens is less than requested, the Dialer may return less than requested.
|
||||
* The number of tokens a DialRequest obtains reflects the maximum number of parallel Multiaddr Dials it can make.
|
||||
* If no tokens are available a DialRequest should immediately end and throw. This deviates from the existing queue system to avoid queue congestion and provide more visibility to users.
|
||||
* As tokens are limited, DialRequests should be given a prioritized list of Multiaddrs to minimize the potential request time.
|
||||
* Once a single Multiaddr Dial has succeeded, all pending dials in that Dial Request should be aborted. All tokens should be immediately released to the Dialer.
|
||||
* If all Multiaddr Dials fail, or the DIAL_TIMEOUT max is reached for the entire DialRequest, all in progress dials for that DialRequest should be aborted. All tokens should immediately be released to the Dialer.
|
||||
|
||||
## Multiaddr Confidence
|
||||
|
||||
**Not Yet Implemented**
|
||||
|
||||
An effective dialing system should involve the inclusion of a Confidence system for Multiaddrs. This enables ranking of Multiaddrs so that a prioritized list can be passed to DialRequests to maximize usage of Dialer Tokens.
|
||||
|
||||
* All Multiaddrs SHOULD start with a confidence of 1 (give it some trust by default)
|
||||
* A failed dial SHOULD lower the confidence by 1, to a min of 0.
|
||||
* A successful dial SHOULD increase the confidence of a multiaddr by 1, to a max of 10.
|
||||
* Multiaddrs of confidence 0 MAY be pruned if higher confidence addresses exist. If this is done, it should be done an an actual failure. Aborted dials SHOULD NOT be considered failures, but timeouts SHOULD.
|
||||
|
||||
## Notes
|
||||
|
||||
* A DialRequest gets a set of tokens from the Dialer, up to the PER_PEER_LIMIT max.
|
||||
* A DialRequest SHOULD release its tokens after the DIAL_TIMEOUT has expired. This ensures that a peer with a large set of hanging addresses, does not block future dials.
|
||||
* Upon releasing the tokens, the Dialer may allocate them to another DialRequest.
|
||||
* A DialRequest SHOULD fail if no dial tokens are available. The DialRequest MAY proceed without tokens, but this should be reserved for High Priority actions and should be rare.
|
||||
* A DialRequest MUST NOT request more tokens than it has addresses to dial. Example: If the PER_PEER_LIMIT max is 4 and a DialRequest has 1 address, it should only request 1 token.
|
||||
* A DialRequest MUST execute parallel dials for each of its addresses up the total number of tokens it has.
|
||||
* On a successful dial, the DialRequest MUST abort any other in progress dials, return the successful connection and release all tokens.
|
||||
* A new DialRequest SHOULD be given a descending list of prioritized Multiaddrs, based on their confidence. Having higher confidence Multiaddrs first can help minimize the time a DialRequest is active.
|
||||
* A failed dial to a Multiaddr SHOULD add that Multiaddr to a temporary denyList.
|
||||
* A failed dial to a Multiaddr SHOULD lower the confidence of that Multiaddr.
|
||||
* A successful dial to a Multiaddr SHOULD increase the confidence of that Multiaddr.
|
Loading…
x
Reference in New Issue
Block a user