Initial Commit

packages/networking/network/network-discovery-webtorrent/README.md

@@ -0,0 +1,114 @@
+# @suaveplan/network-discovery-webtorrent - Browser-tier WebTorrent DiscoveryStrategy: WebTorrent-tracker-driven WebRTC peer discovery via p2pt. Tracker list REQUIRED — no public-tracker fallback. AbortSignal + EventBusLike + ServiceRegistry + OTel + Zod boundaries.
+
+## Summary
+
+Browser-tier `DiscoveryStrategy` for `@suaveplan/network-bootstrap` chains.
+Wraps a [`p2pt`](https://github.com/subins2000/p2pt) instance —
+WebTorrent-tracker-driven WebRTC peer discovery — and exposes a deduped,
+capped peer set to the bootstrap pipeline.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [webtorrent-discovery](./src/core/webtorrent-discovery/webtorrent-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [webtorrent-discovery](./src/core/webtorrent-discovery/webtorrent-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+<!-- end:auto-docs -->  - [webtorrent-discovery](./src/core/webtorrent-discovery/webtorrent-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [webtorrent-discovery](./src/core/webtorrent-discovery/webtorrent-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [webtorrent-discovery](./src/core/webtorrent-discovery/webtorrent-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [webtorrent-discovery](./src/core/webtorrent-discovery/webtorrent-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_  - [errors](./src/errors/errors.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_  - [otel](./src/otel/otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_  - [plugin](./src/plugin/plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_  - [transport](./src/transport/transport.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_
+## Why this package
+
+- Plug-and-play `DiscoveryStrategy` slot for network bootstrap
+  chains. Works alongside `@suaveplan/network-discovery-peerjs`,
+  `@suaveplan/network-discovery-trystero`, and
+  `@suaveplan/network-discovery-crdt`.
+- **Tracker list REQUIRED.** Upstream's hard-coded public-tracker fallback
+  was removed. Callers must supply their own tracker infrastructure.
+- Injectable `p2ptFactory` — production wires the real `p2pt`; tests bind
+  a deterministic `P2PTLike` fake (no `vi.mock` ever used).
+- Typed `EventBusLike<WebTorrentEventMap>` integration.
+- Optional `@suaveplan/service-discovery` `ServiceRegistry` mirroring.
+- OTel surface: `disc_webtorrent.start` span;
+  `peers_discovered_total{outcome}`, `tracker_errors_total{tracker}`,
+  `tracker_announce_duration_ms` instruments.
+- AbortSignal honoured on every async public method.
+- 100% test + branch + function + line coverage.
+
+## Basic example
+
+```ts
+import { WebTorrentDiscovery } from "@suaveplan/network-discovery-webtorrent";
+
+const discovery = new WebTorrentDiscovery({
+    trackers: ["wss://my-tracker.example.com"],
+    p2ptFactory: async (trackers, announceId) => {
+        const { default: P2PT } = await import("p2pt");
+        return new P2PT(trackers as string[], announceId);
+    },
+});
+
+await discovery.start();
+const peers = await discovery.discover(5_000);
+console.log(`found ${peers.length} peers`);
+await discovery.stop();
+```
+
+## Advanced example
+
+```ts
+import { EventBus } from "@suaveplan/events";
+import { ServiceRegistry } from "@suaveplan/service-discovery";
+import { DiscoveryChain } from "@suaveplan/network-bootstrap";
+import {
+    WebTorrentDiscovery,
+    type WebTorrentEventMap,
+} from "@suaveplan/network-discovery-webtorrent";
+
+const bus = new EventBus<WebTorrentEventMap>();
+const registry = new ServiceRegistry();
+
+bus.on("webtorrent:peer-discovered", ({ peer }) => {
+    console.log("peer:", peer.id, peer.addresses);
+});
+bus.on("webtorrent:tracker-error", ({ reason }) => {
+    console.warn("tracker:", reason);
+});
+
+const discovery = new WebTorrentDiscovery({
+    trackers: [
+        "wss://my-tracker-a.example.com",
+        "wss://my-tracker-b.example.com",
+    ],
+    announceId: "my-app/v1",
+    maxPeers: 256,
+    p2ptFactory: async (trackers, id) => {
+        const { default: P2PT } = await import("p2pt");
+        return new P2PT(trackers as string[], id);
+    },
+    bus,
+    registry,
+});
+
+const chain = new DiscoveryChain([discovery]);
+const peers = await chain.discover(5_000);
+```
+
+## API
+
+See sibling co-located markdown:
+
+- [`src/types/types.md`](./src/types/types.md)
+- [`src/errors/errors.md`](./src/errors/errors.md)
+- [`src/otel/otel.md`](./src/otel/otel.md)
+- [`src/core/webtorrent-discovery/webtorrent-discovery.md`](./src/core/webtorrent-discovery/webtorrent-discovery.md)
+
+## License
+
+MIT