Skip to content

feat(dht): add browser transport addresses and shared iterative lookup - #158

Draft
mickvandijke wants to merge 9 commits into
mainfrom
web-support
Draft

feat(dht): add browser transport addresses and shared iterative lookup#158
mickvandijke wants to merge 9 commits into
mainfrom
web-support

Conversation

@mickvandijke

@mickvandijke mickvandijke commented Sep 1, 2026

Copy link
Copy Markdown
Member

Summary

Adds the transport-independent address and lookup foundations needed by direct browser clients while keeping native DHT behavior on the same implementation.

This PR introduces canonical WebRTC Direct transport addresses, a versioned extensible address-publication plane, and a small runtime-independent Kademlia lookup crate shared by native Saorsa and browser/WASM clients.

What changes

Canonical transport addresses

  • Adds WebRTC Direct multiaddresses carrying the literal IP, UDP port, DTLS certificate multihash, and expected peer ID.
  • Retains the earlier WebTransport address representation as a generic transport variant.
  • Centralizes parsing, validation, serialization, and reachability classification in Saorsa types rather than browser-specific JavaScript.

Versioned address publication

  • Freezes the existing V1 PublishAddressSet wire representation as its QUIC-only projection.
  • Adds a V2 transport-address record with numeric transport/reachability discriminants.
  • Adds V2 publish/find-node handling and identity capability negotiation.
  • Keeps one canonical in-memory address set while returning the appropriate V1 or V2 projection to each peer.
  • Allows browser endpoints to propagate through the authenticated DHT without changing the legacy enum.

Shared iterative lookup

  • Adds the saorsa-dht-lookup workspace crate with no Tokio or transport dependency.
  • Extracts candidate ordering, alpha batching, failure state, bounded candidate retention, grace collection, and convergence into one generic engine.
  • Refactors native DhtNetworkManager to use that engine.
  • Makes the same lookup policy consumable from ant-core WASM instead of reimplementing Kademlia traversal in JavaScript.
  • Documents the decision in ADR-016.

Compatibility

  • V1 address publication remains byte-compatible and QUIC-only.
  • V2 is capability-selected; older peers continue using V1.
  • Existing native lookup still supplies transport authentication, consensus, trust updates, and failure-cache behavior around the shared policy engine.
  • No stored-data format or payment changes.
  • Depends on saorsa-transport#160, pinned by commit SHA for draft CI reproducibility.

Test evidence

  • cargo check --workspace
  • cargo test -p saorsa-dht-lookup
    • 10 tests passed.
    • Covers XOR ordering, alpha limits, bounded eviction, multi-round traversal, failure-state monotonicity, grace collection, straggler cancellation, and top-K convergence.
  • cargo fmt --all -- --check
  • git diff --check
  • The shared runner is additionally exercised from generated ant-core WASM and the live Chromium/node integration test.

Risk and review focus

  • The V2 address plane and native lookup refactor affect DHT behavior and deserve protocol/routing review.
  • Review should focus on V1 wire preservation, capability negotiation, convergence equivalence, and failure-state handling.
  • Linear issue: TBD before the stack is marked ready.
  • This branch started from saorsa-core v0.26.4 and currently needs rebasing onto latest main.

Rollback

Revert V2 publication and the native lookup adapter. V1 QUIC address publication remains the compatibility baseline.

Coordinated draft stack

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant