From 9ee76915d2b8298d99557e105c4f71d585e97e7d Mon Sep 17 00:00:00 2001
From: Alex Potsides <alex@achingbrain.net>
Date: Thu, 27 Apr 2023 09:01:24 +0100
Subject: [PATCH] feat: add routing symbols (#388)

When libp2p is [configured with arbitrary services](https://github.com/libp2p/js-libp2p/pull/1563)
some of those services may be content routers or peer routers or
both.  An example of this is the `@libp2p/kad-dht` module.

In order to communicate to libp2p that they can provide content/peer
routing cabapiliy, add well-known symbols that libp2p can use to
get references to the routing implementations.
---
 .../interface-content-routing/src/index.ts    | 21 +++++++++++++++++++
 .../interface-peer-discovery/src/index.ts     | 21 +++++++++++++++++++
 packages/interface-peer-routing/src/index.ts  | 21 +++++++++++++++++++
 3 files changed, 63 insertions(+)

diff --git a/packages/interface-content-routing/src/index.ts b/packages/interface-content-routing/src/index.ts
index 0a191d55e..e782df635 100644
--- a/packages/interface-content-routing/src/index.ts
+++ b/packages/interface-content-routing/src/index.ts
@@ -2,6 +2,27 @@ import type { CID } from 'multiformats/cid'
 import type { AbortOptions } from '@libp2p/interfaces'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
 
+/**
+ * Any object that implements this Symbol as a property should return a
+ * ContentRouting instance as the property value, similar to how
+ * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ *
+ * @example
+ *
+ * ```js
+ * import { contentRouting, ContentRouting } from '@libp2p/content-routing'
+ *
+ * class MyContentRouter implements ContentRouting {
+ *   get [contentRouting] () {
+ *     return this
+ *   }
+ *
+ *   // ...other methods
+ * }
+ * ```
+ */
+export const contentRouting = Symbol.for('@libp2p/content-routing')
+
 export interface ContentRouting {
   /**
    * The implementation of this method should ensure that network peers know the
diff --git a/packages/interface-peer-discovery/src/index.ts b/packages/interface-peer-discovery/src/index.ts
index 4a2c22a44..bcb738542 100644
--- a/packages/interface-peer-discovery/src/index.ts
+++ b/packages/interface-peer-discovery/src/index.ts
@@ -1,6 +1,27 @@
 import type { PeerInfo } from '@libp2p/interface-peer-info'
 import type { EventEmitter } from '@libp2p/interfaces/events'
 
+/**
+ * Any object that implements this Symbol as a property should return a
+ * PeerDiscovery instance as the property value, similar to how
+ * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ *
+ * @example
+ *
+ * ```js
+ * import { peerDiscovery, PeerDiscovery } from '@libp2p/peer-discovery'
+ *
+ * class MyPeerDiscoverer implements PeerDiscovery {
+ *   get [peerDiscovery] () {
+ *     return this
+ *   }
+ *
+ *   // ...other methods
+ * }
+ * ```
+ */
+export const peerDiscovery = Symbol.for('@libp2p/peer-discovery')
+
 export const symbol = Symbol.for('@libp2p/peer-discovery')
 
 export interface PeerDiscoveryEvents {
diff --git a/packages/interface-peer-routing/src/index.ts b/packages/interface-peer-routing/src/index.ts
index 0f13e8d3f..d4bbef25c 100644
--- a/packages/interface-peer-routing/src/index.ts
+++ b/packages/interface-peer-routing/src/index.ts
@@ -2,6 +2,27 @@ import type { PeerId } from '@libp2p/interface-peer-id'
 import type { PeerInfo } from '@libp2p/interface-peer-info'
 import type { AbortOptions } from '@libp2p/interfaces'
 
+/**
+ * Any object that implements this Symbol as a property should return a
+ * PeerRouting instance as the property value, similar to how
+ * `Symbol.Iterable` can be used to return an `Iterable` from an `Iterator`.
+ *
+ * @example
+ *
+ * ```js
+ * import { peerRouting, PeerRouting } from '@libp2p/peer-routing'
+ *
+ * class MyPeerRouter implements PeerRouting {
+ *   get [peerRouting] () {
+ *     return this
+ *   }
+ *
+ *   // ...other methods
+ * }
+ * ```
+ */
+export const peerRouting = Symbol.for('@libp2p/peer-routing')
+
 export interface PeerRouting {
   /**
    * Searches the network for peer info corresponding to the passed peer id.