Write up plans for API compatibility and strategy to deal with breakage

[iand]

ETA: 2023-08-17

[dennis-tra]

This is the public API of go-libp2p-kad-dht (the top-level dht package)

func GetDefaultBootstrapPeerAddrInfos() []peer.AddrInfo
func NewRTPeerDiversityFilter(h host.Host, maxPerCpl, maxForTable int) *rtPeerIPGroupFilter
func PrivateQueryFilter(_ interface{}, ai peer.AddrInfo) bool
func PrivateRoutingTableFilter(dht interface{}, p peer.ID) bool
func PublicQueryFilter(_ interface{}, ai peer.AddrInfo) bool
func PublicRoutingTableFilter(dht interface{}, p peer.ID) bool
func PublishLookupEvent(ctx context.Context, ev *LookupEvent)
func Quorum(n int) routing.Option
func RegisterForLookupEvents(ctx context.Context) (context.Context, <-chan *LookupEvent)
type IpfsDHT
    func New(ctx context.Context, h host.Host, options ...Option) (*IpfsDHT, error)
    func NewDHT(ctx context.Context, h host.Host, dstore ds.Batching) *IpfsDHT
    func NewDHTClient(ctx context.Context, h host.Host, dstore ds.Batching) *IpfsDHT
    func (dht *IpfsDHT) Bootstrap(ctx context.Context) error
    func (dht *IpfsDHT) Close() error
    func (dht *IpfsDHT) Context() context.Context
    func (dht *IpfsDHT) FindLocal(ctx context.Context, id peer.ID) peer.AddrInfo
    func (dht *IpfsDHT) FindPeer(ctx context.Context, id peer.ID) (_ peer.AddrInfo, err error)
    func (dht *IpfsDHT) FindProviders(ctx context.Context, c cid.Cid) ([]peer.AddrInfo, error)
    func (dht *IpfsDHT) FindProvidersAsync(ctx context.Context, key cid.Cid, count int) <-chan peer.AddrInfo
    func (dht *IpfsDHT) ForceRefresh() <-chan error
    func (dht *IpfsDHT) GetClosestPeers(ctx context.Context, key string) ([]peer.ID, error)
    func (dht *IpfsDHT) GetPublicKey(ctx context.Context, p peer.ID) (ci.PubKey, error)
    func (dht *IpfsDHT) GetRoutingTableDiversityStats() []peerdiversity.CplDiversityStats
    func (dht *IpfsDHT) GetValue(ctx context.Context, key string, opts ...routing.Option) (_ []byte, err error)
    func (dht *IpfsDHT) Host() host.Host
    func (dht *IpfsDHT) Mode() ModeOpt
    func (dht *IpfsDHT) NetworkSize() (int32, error)
    func (dht *IpfsDHT) PeerID() peer.ID
    func (dht *IpfsDHT) PeerKey() []byte
    func (dht *IpfsDHT) Ping(ctx context.Context, p peer.ID) error
    func (dht *IpfsDHT) Provide(ctx context.Context, key cid.Cid, brdcst bool) (err error)
    func (dht *IpfsDHT) ProviderStore() providers.ProviderStore
    func (dht *IpfsDHT) PutValue(ctx context.Context, key string, value []byte, opts ...routing.Option) (err error)
    func (dht *IpfsDHT) RefreshRoutingTable() <-chan error
    func (dht *IpfsDHT) RoutingTable() *kb.RoutingTable
    func (dht *IpfsDHT) SearchValue(ctx context.Context, key string, opts ...routing.Option) (<-chan []byte, error)
type KeyKadID
    func NewKeyKadID(k string) *KeyKadID
type LookupEvent
    func NewLookupEvent(node peer.ID, id uuid.UUID, key string, request *LookupUpdateEvent, response *LookupUpdateEvent, terminate *LookupTerminateEvent) *LookupEvent
type LookupTerminateEvent
    func NewLookupTerminateEvent(reason LookupTerminationReason) *LookupTerminateEvent
type LookupTerminationReason
    func (r LookupTerminationReason) MarshalJSON() ([]byte, error)
    func (r LookupTerminationReason) String() string
type LookupUpdateEvent
    func NewLookupUpdateEvent(cause peer.ID, source peer.ID, heard []peer.ID, waiting []peer.ID, queried []peer.ID, unreachable []peer.ID) *LookupUpdateEvent
type ModeOpt
type Option
    func AddressFilter(f func([]ma.Multiaddr) []ma.Multiaddr) Option
    func BootstrapPeers(bootstrappers ...peer.AddrInfo) Option
    func BootstrapPeersFunc(getBootstrapPeers func() []peer.AddrInfo) Option
    func BucketSize(bucketSize int) Option
    func Concurrency(alpha int) Option
    func Datastore(ds ds.Batching) Option
    func DisableAutoRefresh() Option
    func DisableProviders() Option
    func DisableValues() Option
    func EnableOptimisticProvide() Option
    func LookupCheckConcurrency(n int) Option
    func MaxRecordAge(maxAge time.Duration) Option
    func Mode(m ModeOpt) Option
    func NamespacedValidator(ns string, v record.Validator) Option
    func OptimisticProvideJobsPoolSize(size int) Option
    func ProtocolExtension(ext protocol.ID) Option
    func ProtocolPrefix(prefix protocol.ID) Option
    func ProviderStore(ps providers.ProviderStore) Option
    func QueryFilter(filter QueryFilterFunc) Option
    func Resiliency(beta int) Option
    func RoutingTableFilter(filter RouteTableFilterFunc) Option
    func RoutingTableLatencyTolerance(latency time.Duration) Option
    func RoutingTablePeerDiversityFilter(pg peerdiversity.PeerIPGroupFilter) Option
    func RoutingTableRefreshPeriod(period time.Duration) Option
    func RoutingTableRefreshQueryTimeout(timeout time.Duration) Option
    func V1ProtocolOverride(proto protocol.ID) Option
    func Validator(v record.Validator) Option
type PeerKadID
    func NewPeerKadID(p peer.ID) *PeerKadID
    func NewPeerKadIDSlice(p []peer.ID) []*PeerKadID
    func OptPeerKadID(p peer.ID) *PeerKadID
type QueryFilterFunc
type RouteTableFilterFunc

routing.Routing interface

Some must-haves due to the routing.Routing interface. Changing this one is probably out of question because many other subsystems depend on it?

func (d *IpfsDHT) Provide(ctx context.Context, cid cid.Cid, b bool) error
func (d *IpfsDHT) FindProvidersAsync(ctx context.Context, cid cid.Cid, i int) <-chan peer.AddrInfo
func (d *IpfsDHT) FindPeer(ctx context.Context, id peer.ID) (peer.AddrInfo, error)
func (d *IpfsDHT) PutValue(ctx context.Context, s string, bytes []byte, option ...routing.Option) error
func (d *IpfsDHT) GetValue(ctx context.Context, s string, option ...routing.Option) ([]byte, error)
func (d *IpfsDHT) SearchValue(ctx context.Context, s string, option ...routing.Option) (<-chan []byte, error)
func (d *IpfsDHT) Bootstrap(ctx context.Context) error

Option style configuration

If we wanted to go the same route as in https://github.com/plprobelab/go-kademlia/issues/64, all the Option functions would go away.