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

To better align with [go-libp2p@0.34.0](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 =

packages/libp2p/src/connection-manager/dial-queue.ts

@@ -471,7 +471,7 @@ export class DialQueue {
     try {
       const addresses = await this.calculateMultiaddrs(undefined, new Set(multiaddr.map(ma => ma.toString())), options)
 
-      if (options.runOnTransientConnection === false) {
+      if (options.runOnLimitedConnection === false) {
         // return true if any resolved multiaddrs are not relay addresses
         return addresses.find(addr => {
           return !Circuit.matches(addr.multiaddr)

packages/libp2p/src/connection-manager/index.ts

@@ -505,10 +505,10 @@ export class DefaultConnectionManager implements ConnectionManager, Startable {
     if (peerId != null && options.force !== true) {
       this.log('dial %p', peerId)
       const existingConnection = this.getConnections(peerId)
-        .find(conn => !conn.transient)
+        .find(conn => conn.limits == null)
 
       if (existingConnection != null) {
-        this.log('had an existing non-transient connection to %p', peerId)
+        this.log('had an existing non-limited connection to %p', peerId)
 
         options.onProgress?.(new CustomProgressEvent('dial-queue:already-connected'))
         return existingConnection

packages/libp2p/src/connection/index.ts

@@ -1,5 +1,5 @@
 import { connectionSymbol, CodeError, setMaxListeners } from '@libp2p/interface'
-import type { AbortOptions, Logger, ComponentLogger, Direction, Connection, Stream, ConnectionTimeline, ConnectionStatus, NewStreamOptions, PeerId } from '@libp2p/interface'
+import type { AbortOptions, Logger, ComponentLogger, Direction, Connection, Stream, ConnectionTimeline, ConnectionStatus, NewStreamOptions, PeerId, ConnectionLimits } from '@libp2p/interface'
 import type { Multiaddr } from '@multiformats/multiaddr'
 
 const CLOSE_TIMEOUT = 500
@@ -16,7 +16,7 @@ interface ConnectionInit {
   timeline: ConnectionTimeline
   multiplexer?: string
   encryption?: string
-  transient?: boolean
+  limits?: ConnectionLimits
   logger: ComponentLogger
 }
 
@@ -45,7 +45,7 @@ export class ConnectionImpl implements Connection {
   public multiplexer?: string
   public encryption?: string
   public status: ConnectionStatus
-  public transient: boolean
+  public limits?: ConnectionLimits
   public readonly log: Logger
 
   /**
@@ -86,7 +86,7 @@ export class ConnectionImpl implements Connection {
     this.timeline = init.timeline
     this.multiplexer = init.multiplexer
     this.encryption = init.encryption
-    this.transient = init.transient ?? false
+    this.limits = init.limits
     this.log = init.logger.forComponent(`libp2p:connection:${this.direction}:${this.id}`)
 
     if (this.remoteAddr.getPeerId() == null) {
@@ -127,7 +127,7 @@ export class ConnectionImpl implements Connection {
       protocols = [protocols]
     }
 
-    if (this.transient && options?.runOnTransientConnection !== true) {
+    if (this.limits != null && options?.runOnLimitedConnection !== true) {
       throw new CodeError('Cannot open protocol stream on transient connection', 'ERR_TRANSIENT_CONNECTION')
     }
 

packages/libp2p/src/registrar.ts

@@ -230,7 +230,7 @@ export class DefaultRegistrar implements Registrar {
       }
 
       for (const topology of topologies.values()) {
-        if (connection.transient && topology.notifyOnTransient !== true) {
+        if (connection.limits != null && topology.notifyOnLimitedConnection !== true) {
           continue
         }