fix!: rename "transient" connections to "limited" (#2645)

To better align with [[email protected]](https://github.com/libp2p/go-libp2p/releases/tag/v0.34.0)
rename "transient" connections to "limited".

BREAKING CHANGE: There are three breaking API changes:
  * Connections have an optional `.limits` property
  * The `runOnTransientConnection` property of `libp2p.handle` and `libp2p.dialProtocol` has been renamed to `runOnLimitedConnection`
  * The `notifyOnTransient` property of `libp2p.register` has been renamed `notifyOnLimitedConnection`

Refs: #2622

Author: achingbrain

packages/integration-tests/test/circuit-relay.node.ts

@@ -90,7 +90,7 @@ const echoService = (components: EchoServiceComponents): unknown => {
           stream, stream
         )
       }, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
     },
     stop () {}
@@ -560,7 +560,7 @@ describe('circuit-relay', () => {
 
       // open hop stream and try to connect to remote
       const stream = await local.dialProtocol(ma, RELAY_V2_HOP_CODEC, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
 
       const hopStream = pbStream(stream).pb(HopMessage)
@@ -638,43 +638,43 @@ describe('circuit-relay', () => {
       expect(circuitListener[0].relayStore.listenerCount('relay:removed')).to.equal(1)
     })
 
-    it('should mark an outgoing relayed connection as transient', async () => {
+    it('should mark an outgoing relayed connection as limited', async () => {
       // discover relay and make reservation
       const connectionToRelay = await remote.dial(relay1.getMultiaddrs()[0])
 
-      // connection to relay should not be marked transient
-      expect(connectionToRelay).to.have.property('transient', false)
+      // connection to relay should not be limited
+      expect(connectionToRelay).to.have.property('limits').that.is.undefined()
 
       await usingAsRelay(remote, relay1)
 
       // dial the remote through the relay
       const ma = getRelayAddress(remote)
       const connection = await local.dial(ma)
 
-      // connection to remote through relay should be marked transient
-      expect(connection).to.have.property('transient', true)
+      // connection to remote through relay should be limited
+      expect(connection).to.have.property('limits').that.is.ok()
     })
 
-    it('should mark an incoming relayed connection as transient', async () => {
+    it('should mark an incoming relayed connection as limited', async () => {
       // discover relay and make reservation
       const connectionToRelay = await remote.dial(relay1.getMultiaddrs()[0])
 
-      // connection to relay should not be marked transient
-      expect(connectionToRelay).to.have.property('transient', false)
+      // connection to relay should not be limited
+      expect(connectionToRelay).to.have.property('limits').that.is.undefined()
 
       await usingAsRelay(remote, relay1)
 
       // dial the remote through the relay
       const ma = getRelayAddress(remote)
       await local.dial(ma)
 
-      // connection from local through relay should be marked transient
+      // connection from local through relay should be limited
       const connections = remote.getConnections(local.peerId)
       expect(connections).to.have.lengthOf(1)
-      expect(connections).to.have.nested.property('[0].transient', true)
+      expect(connections).to.have.nested.property('[0].limits').that.is.ok()
     })
 
-    it('should not open streams on a transient connection', async () => {
+    it('should not open streams on a limited connection', async () => {
       // discover relay and make reservation
       await remote.dial(relay1.getMultiaddrs()[0])
       await usingAsRelay(remote, relay1)
@@ -683,21 +683,21 @@ describe('circuit-relay', () => {
       const ma = getRelayAddress(remote)
       const connection = await local.dial(ma)
 
-      // connection should be marked transient
-      expect(connection).to.have.property('transient', true)
+      // connection should be marked limited
+      expect(connection).to.have.property('limits').that.is.ok()
 
       await expect(connection.newStream('/my-protocol/1.0.0'))
-        .to.eventually.be.rejected.with.property('code', 'ERR_TRANSIENT_CONNECTION')
+        .to.eventually.be.rejected.with.property('code', 'ERR_LIMITED_CONNECTION')
     })
 
-    it('should not allow incoming streams on a transient connection', async () => {
+    it('should not allow incoming streams on a limited connection', async () => {
       const protocol = '/my-protocol/1.0.0'
 
-      // remote registers handler, disallow running over transient streams
+      // remote registers handler, disallow running over limited connections
       await remote.handle(protocol, ({ stream }) => {
         void pipe(stream, stream)
       }, {
-        runOnTransientConnection: false
+        runOnLimitedConnection: false
       })
 
       // discover relay and make reservation
@@ -708,23 +708,23 @@ describe('circuit-relay', () => {
       const ma = getRelayAddress(remote)
       const connection = await local.dial(ma)
 
-      // connection should be marked transient
-      expect(connection).to.have.property('transient', true)
+      // connection should be marked limited
+      expect(connection).to.have.property('limits').that.is.ok()
 
       await expect(connection.newStream('/my-protocol/1.0.0', {
-        runOnTransientConnection: false
+        runOnLimitedConnection: false
       }))
-        .to.eventually.be.rejected.with.property('code', 'ERR_TRANSIENT_CONNECTION')
+        .to.eventually.be.rejected.with.property('code', 'ERR_LIMITED_CONNECTION')
     })
 
-    it('should open streams on a transient connection when told to do so', async () => {
+    it('should open streams on a limited connection when told to do so', async () => {
       const protocol = '/my-protocol/1.0.0'
 
-      // remote registers handler, allow running over transient streams
+      // remote registers handler, allow running over limited streams
       await remote.handle(protocol, ({ stream }) => {
         void pipe(stream, stream)
       }, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
 
       // discover relay and make reservation
@@ -735,11 +735,11 @@ describe('circuit-relay', () => {
       const ma = getRelayAddress(remote)
       const connection = await local.dial(ma)
 
-      // connection should be marked transient
-      expect(connection).to.have.property('transient', true)
+      // connection should be marked limited
+      expect(connection).to.have.property('limits').that.is.ok()
 
       await expect(connection.newStream('/my-protocol/1.0.0', {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       }))
         .to.eventually.be.ok()
     })
@@ -912,15 +912,15 @@ describe('circuit-relay', () => {
           } catch {}
         })
       }, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
 
       // dial the remote from the local through the relay
       const ma = getRelayAddress(remote)
 
       try {
         const stream = await local.dialProtocol(ma, protocol, {
-          runOnTransientConnection: true
+          runOnLimitedConnection: true
         })
 
         await stream.sink(async function * () {
@@ -1056,7 +1056,7 @@ describe('circuit-relay', () => {
       const ma = getRelayAddress(remote)
 
       const stream = await local.dialProtocol(ma, ECHO_PROTOCOL, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
 
       // write more than the default data limit
@@ -1075,7 +1075,7 @@ describe('circuit-relay', () => {
       const ma = getRelayAddress(remote)
 
       const stream = await local.dialProtocol(ma, ECHO_PROTOCOL, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
 
       let finished = false
@@ -1107,21 +1107,21 @@ describe('circuit-relay', () => {
       expect(finish - start).to.be.greaterThan(defaultDurationLimit)
     })
 
-    it('should not mark an outgoing connection as transient', async () => {
+    it('should not mark an outgoing connection as limited', async () => {
       const ma = getRelayAddress(remote)
 
       const connection = await local.dial(ma)
-      expect(connection).to.have.property('transient', false)
+      expect(connection).to.have.property('limits').that.is.undefined()
     })
 
-    it('should not mark an incoming connection as transient', async () => {
+    it('should not mark an incoming connection as limited', async () => {
       const ma = getRelayAddress(remote)
 
       await local.dial(ma)
 
       const connections = remote.getConnections(local.peerId)
       expect(connections).to.have.lengthOf(1)
-      expect(connections).to.have.nested.property('[0].transient', false)
+      expect(connections).to.have.nested.property('[0].limits').that.is.undefined()
     })
   })
 })

packages/integration-tests/test/dcutr.node.ts

@@ -24,7 +24,7 @@ describe('dcutr', () => {
   async function waitForOnlyDirectConnections (): Promise<void> {
     await pRetry(async () => {
       const connections = libp2pA.getConnections(libp2pB.peerId)
-      const onlyDirect = connections.filter(conn => !conn.transient)
+      const onlyDirect = connections.filter(conn => conn.limits == null)
 
       if (onlyDirect.length === connections.length) {
         // all connections are direct
@@ -109,8 +109,8 @@ describe('dcutr', () => {
       const relayedAddress = multiaddr(`/ip4/127.0.0.1/tcp/${RELAY_PORT}/p2p/${relay.peerId}/p2p-circuit/p2p/${libp2pB.peerId}`)
       const connection = await libp2pA.dial(relayedAddress)
 
-      // connection should be transient
-      expect(connection).to.have.property('transient', true)
+      // connection should be limited
+      expect(connection).to.have.property('limits').that.is.ok()
 
       // wait for DCUtR unilateral upgrade
       await waitForOnlyDirectConnections()
@@ -166,8 +166,8 @@ describe('dcutr', () => {
       const relayedAddress = multiaddr(`/ip4/127.0.0.1/tcp/${RELAY_PORT}/p2p/${relay.peerId}/p2p-circuit/p2p/${libp2pB.peerId}`)
       const connection = await libp2pA.dial(relayedAddress)
 
-      // connection should be transient
-      expect(connection).to.have.property('transient', true)
+      // connection should be limited
+      expect(connection).to.have.property('limits').that.is.ok()
 
       // wait for DCUtR unilateral upgrade
       await waitForOnlyDirectConnections()

packages/integration-tests/test/fetch.spec.ts

@@ -21,7 +21,7 @@ async function createNode (): Promise<Libp2p<{ fetch: Fetch }>> {
 
 describe('fetch', () => {
   if (isWebWorker) {
-    it.skip('tests are skipped because WebWorkers can only have transient connections', () => {
+    it.skip('tests are skipped because WebWorkers can only have limited connections', () => {
 
     })
     return

packages/integration-tests/test/ping.spec.ts

@@ -76,7 +76,7 @@ describe('ping', () => {
         stream
       )
     }, {
-      runOnTransientConnection: true
+      runOnLimitedConnection: true
     })
 
     const latency = await nodes[0].services.ping.ping(nodes[1].getMultiaddrs())

packages/interface-compliance-tests/src/mocks/connection.ts

@@ -9,7 +9,7 @@ import { Uint8ArrayList } from 'uint8arraylist'
 import { mockMultiaddrConnection } from './multiaddr-connection.js'
 import { mockMuxer } from './muxer.js'
 import { mockRegistrar } from './registrar.js'
-import type { AbortOptions, ComponentLogger, Logger, MultiaddrConnection, Connection, Stream, Direction, ConnectionTimeline, ConnectionStatus, PeerId, StreamMuxer, StreamMuxerFactory, NewStreamOptions } from '@libp2p/interface'
+import type { AbortOptions, ComponentLogger, Logger, MultiaddrConnection, Connection, Stream, Direction, ConnectionTimeline, ConnectionStatus, PeerId, StreamMuxer, StreamMuxerFactory, NewStreamOptions, ConnectionLimits } from '@libp2p/interface'
 import type { Registrar } from '@libp2p/interface-internal'
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { Duplex, Source } from 'it-stream-types'
@@ -41,7 +41,7 @@ class MockConnection implements Connection {
   public status: ConnectionStatus
   public streams: Stream[]
   public tags: string[]
-  public transient: boolean
+  public limits?: ConnectionLimits
   public log: Logger
 
   private readonly muxer: StreamMuxer
@@ -64,7 +64,6 @@ class MockConnection implements Connection {
     this.tags = []
     this.muxer = muxer
     this.maConn = maConn
-    this.transient = false
     this.logger = logger
     this.log = logger.forComponent(this.id)
   }

packages/interface-internal/src/registrar/index.ts

@@ -30,9 +30,11 @@ export interface StreamHandlerOptions {
   /**
    * If true, allow this protocol to run on limited connections (e.g.
    * connections with data or duration limits such as circuit relay
-   * connections) (default: false)
+   * connections)
+   *
+   * @default false
    */
-  runOnTransientConnection?: boolean
+  runOnLimitedConnection?: boolean
 }
 
 export interface StreamHandlerRecord {

packages/interface/src/connection/index.ts

@@ -185,12 +185,16 @@ export interface NewStreamOptions extends AbortOptions {
   maxOutboundStreams?: number
 
   /**
-   * Opt-in to running over a transient connection - one that has time/data limits
-   * placed on it.
+   * Opt-in to running over a limited connection - one that has restrictions
+   * on the amount of data that may be transferred or how long it may be open for.
+   *
+   * These limits are typically enforced by a relay server, if the protocol
+   * will be transferring a lot of data or the stream will be open for a long time
+   * consider upgrading to a direct connection before opening the stream.
    *
    * @default false
    */
-  runOnTransientConnection?: boolean
+  runOnLimitedConnection?: boolean
 
   /**
    * By default when negotiating a protocol the dialer writes then protocol name
@@ -222,6 +226,29 @@ export interface NewStreamOptions extends AbortOptions {
 
 export type ConnectionStatus = 'open' | 'closing' | 'closed'
 
+/**
+ * Connection limits are present on connections that are only allowed to
+ * transfer a certain amount of bytes or be open for a certain number
+ * of seconds.
+ *
+ * These limits are applied by Circuit Relay v2 servers, for example and
+ * the connection will normally be closed abruptly if the limits are
+ * exceeded.
+ */
+export interface ConnectionLimits {
+  /**
+   * If present this is the number of bytes remaining that may be
+   * transferred over this connection
+   */
+  bytes?: bigint
+
+  /**
+   * If present this is the number of seconds that this connection will
+   * remain open for
+   */
+  seconds?: number
+}
+
 /**
  * A Connection is a high-level representation of a connection
  * to a remote peer that may have been secured by encryption and
@@ -280,12 +307,11 @@ export interface Connection {
   status: ConnectionStatus
 
   /**
-   * A transient connection is one that is not expected to be open for very long
-   * or one that cannot transfer very much data, such as one being used as a
-   * circuit relay connection. Protocols need to explicitly opt-in to being run
-   * over transient connections.
+   * If present, this connection has limits applied to it, perhaps by an
+   * intermediate relay. Once the limits have been reached the connection will
+   * be closed by the relay.
    */
-  transient: boolean
+  limits?: ConnectionLimits
 
   /**
    * The time in milliseconds it takes to make a round trip to the remote peer.

packages/interface/src/index.ts

@@ -331,7 +331,7 @@ export interface IsDialableOptions extends AbortOptions {
    * because that protocol would not be allowed to run over a data/time limited
    * connection.
    */
-  runOnTransientConnection?: boolean
+  runOnLimitedConnection?: boolean
 }
 
 export type TransportManagerDialProgressEvents =

packages/interface/src/stream-handler/index.ts

@@ -21,10 +21,10 @@ export interface StreamHandlerOptions {
   maxOutboundStreams?: number
 
   /**
-   * Opt-in to running over a transient connection - one that has time/data limits
-   * placed on it.
+   * Opt-in to running over connections with limits on how much data can be
+   * transferred or how long it can be open for.
    */
-  runOnTransientConnection?: boolean
+  runOnLimitedConnection?: boolean
 }
 
 export interface StreamHandlerRecord {