fix!: rename "transient" connections to "limited"

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)
@@ -671,7 +671,7 @@ describe('circuit-relay', () => {
       // connection from local through relay should be marked transient
       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.not.null()
     })
 
     it('should not open streams on a transient connection', async () => {
@@ -697,7 +697,7 @@ describe('circuit-relay', () => {
       await remote.handle(protocol, ({ stream }) => {
         void pipe(stream, stream)
       }, {
-        runOnTransientConnection: false
+        runOnLimitedConnection: false
       })
 
       // discover relay and make reservation
@@ -712,7 +712,7 @@ describe('circuit-relay', () => {
       expect(connection).to.have.property('transient', true)
 
       await expect(connection.newStream('/my-protocol/1.0.0', {
-        runOnTransientConnection: false
+        runOnLimitedConnection: false
       }))
         .to.eventually.be.rejected.with.property('code', 'ERR_TRANSIENT_CONNECTION')
     })
@@ -724,7 +724,7 @@ describe('circuit-relay', () => {
       await remote.handle(protocol, ({ stream }) => {
         void pipe(stream, stream)
       }, {
-        runOnTransientConnection: true
+        runOnLimitedConnection: true
       })
 
       // discover relay and make reservation
@@ -739,7 +739,7 @@ describe('circuit-relay', () => {
       expect(connection).to.have.property('transient', true)
 
       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.not.have.property('limits')
     })
 
-    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.not.have.nested.property('[0].limits')
     })
   })
 })

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('limited', true)
 
       // 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('limited', true)
 
       // wait for DCUtR unilateral upgrade
       await waitForOnlyDirectConnections()

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,11 @@ export interface NewStreamOptions extends AbortOptions {
 
 export type ConnectionStatus = 'open' | 'closing' | 'closed'
 
+export interface ConnectionLimits {
+  bytes?: number
+  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 +289,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
 
   /**
    * Create a new stream on this connection and negotiate one of the passed protocols

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 {

packages/interface/src/topology/index.ts

@@ -27,12 +27,13 @@ export interface Topology {
   filter?: TopologyFilter
 
   /**
-   * If true, invoke `onConnect` for this topology on transient (e.g. short-lived
-   * and/or data-limited) connections
+   * If true, invoke `onConnect` for this topology on limited connections, e.g.
+   * ones with limits on how much data can be transferred or how long they can
+   * be open for.
    *
    * @default false
    */
-  notifyOnTransient?: boolean
+  notifyOnLimitedConnection?: boolean
 
   /**
    * Invoked when a new connection is opened to a peer that supports the

packages/interface/src/transport/index.ts

@@ -1,4 +1,4 @@
-import type { Connection, MultiaddrConnection } from '../connection/index.js'
+import type { Connection, ConnectionLimits, MultiaddrConnection } from '../connection/index.js'
 import type { TypedEventTarget } from '../event-target.js'
 import type { AbortOptions } from '../index.js'
 import type { StreamMuxerFactory } from '../stream-muxer/index.js'
@@ -104,12 +104,7 @@ export interface UpgraderOptions<ConnectionUpgradeEvents extends ProgressEvent =
   skipEncryption?: boolean
   skipProtection?: boolean
   muxerFactory?: StreamMuxerFactory
-
-  /**
-   * The passed MultiaddrConnection has limits place on duration and/or data
-   * transfer amounts so is not expected to be open for very long.
-   */
-  transient?: boolean
+  limits?: ConnectionLimits
 }
 
 export type InboundConnectionUpgradeEvents =