Skip to content

Commit f24a06e

Browse files
achingbrainachingbrain
committed
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
1 parent 944935f commit f24a06e

File tree

34 files changed

+160
-111
lines changed

34 files changed

+160
-111
lines changed

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

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ const echoService = (components: EchoServiceComponents): unknown => {
9090
stream, stream
9191
)
9292
}, {
93-
runOnTransientConnection: true
93+
runOnLimitedConnection: true
9494
})
9595
},
9696
stop () {}
@@ -560,7 +560,7 @@ describe('circuit-relay', () => {
560560
561561
// open hop stream and try to connect to remote
562562
const stream = await local.dialProtocol(ma, RELAY_V2_HOP_CODEC, {
563-
runOnTransientConnection: true
563+
runOnLimitedConnection: true
564564
})
565565
566566
const hopStream = pbStream(stream).pb(HopMessage)
@@ -671,7 +671,7 @@ describe('circuit-relay', () => {
671671
// connection from local through relay should be marked transient
672672
const connections = remote.getConnections(local.peerId)
673673
expect(connections).to.have.lengthOf(1)
674-
expect(connections).to.have.nested.property('[0].transient', true)
674+
expect(connections).to.have.nested.property('[0].limits').that.is.not.null()
675675
})
676676

677677
it('should not open streams on a transient connection', async () => {
@@ -697,7 +697,7 @@ describe('circuit-relay', () => {
697697
await remote.handle(protocol, ({ stream }) => {
698698
void pipe(stream, stream)
699699
}, {
700-
runOnTransientConnection: false
700+
runOnLimitedConnection: false
701701
})
702702

703703
// discover relay and make reservation
@@ -712,7 +712,7 @@ describe('circuit-relay', () => {
712712
expect(connection).to.have.property('transient', true)
713713

714714
await expect(connection.newStream('/my-protocol/1.0.0', {
715-
runOnTransientConnection: false
715+
runOnLimitedConnection: false
716716
}))
717717
.to.eventually.be.rejected.with.property('code', 'ERR_TRANSIENT_CONNECTION')
718718
})
@@ -724,7 +724,7 @@ describe('circuit-relay', () => {
724724
await remote.handle(protocol, ({ stream }) => {
725725
void pipe(stream, stream)
726726
}, {
727-
runOnTransientConnection: true
727+
runOnLimitedConnection: true
728728
})
729729

730730
// discover relay and make reservation
@@ -739,7 +739,7 @@ describe('circuit-relay', () => {
739739
expect(connection).to.have.property('transient', true)
740740

741741
await expect(connection.newStream('/my-protocol/1.0.0', {
742-
runOnTransientConnection: true
742+
runOnLimitedConnection: true
743743
}))
744744
.to.eventually.be.ok()
745745
})
@@ -912,15 +912,15 @@ describe('circuit-relay', () => {
912912
} catch {}
913913
})
914914
}, {
915-
runOnTransientConnection: true
915+
runOnLimitedConnection: true
916916
})
917917

918918
// dial the remote from the local through the relay
919919
const ma = getRelayAddress(remote)
920920

921921
try {
922922
const stream = await local.dialProtocol(ma, protocol, {
923-
runOnTransientConnection: true
923+
runOnLimitedConnection: true
924924
})
925925

926926
await stream.sink(async function * () {
@@ -1056,7 +1056,7 @@ describe('circuit-relay', () => {
10561056
const ma = getRelayAddress(remote)
10571057

10581058
const stream = await local.dialProtocol(ma, ECHO_PROTOCOL, {
1059-
runOnTransientConnection: true
1059+
runOnLimitedConnection: true
10601060
})
10611061

10621062
// write more than the default data limit
@@ -1075,7 +1075,7 @@ describe('circuit-relay', () => {
10751075
const ma = getRelayAddress(remote)
10761076

10771077
const stream = await local.dialProtocol(ma, ECHO_PROTOCOL, {
1078-
runOnTransientConnection: true
1078+
runOnLimitedConnection: true
10791079
})
10801080

10811081
let finished = false
@@ -1107,21 +1107,21 @@ describe('circuit-relay', () => {
11071107
expect(finish - start).to.be.greaterThan(defaultDurationLimit)
11081108
})
11091109

1110-
it('should not mark an outgoing connection as transient', async () => {
1110+
it('should not mark an outgoing connection as limited', async () => {
11111111
const ma = getRelayAddress(remote)
11121112

11131113
const connection = await local.dial(ma)
1114-
expect(connection).to.have.property('transient', false)
1114+
expect(connection).to.not.have.property('limits')
11151115
})
11161116

1117-
it('should not mark an incoming connection as transient', async () => {
1117+
it('should not mark an incoming connection as limited', async () => {
11181118
const ma = getRelayAddress(remote)
11191119

11201120
await local.dial(ma)
11211121

11221122
const connections = remote.getConnections(local.peerId)
11231123
expect(connections).to.have.lengthOf(1)
1124-
expect(connections).to.have.nested.property('[0].transient', false)
1124+
expect(connections).to.not.have.nested.property('[0].limits')
11251125
})
11261126
})
11271127
})

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ describe('dcutr', () => {
2424
async function waitForOnlyDirectConnections (): Promise<void> {
2525
await pRetry(async () => {
2626
const connections = libp2pA.getConnections(libp2pB.peerId)
27-
const onlyDirect = connections.filter(conn => !conn.transient)
27+
const onlyDirect = connections.filter(conn => conn.limits == null)
2828

2929
if (onlyDirect.length === connections.length) {
3030
// all connections are direct
@@ -109,8 +109,8 @@ describe('dcutr', () => {
109109
const relayedAddress = multiaddr(`/ip4/127.0.0.1/tcp/${RELAY_PORT}/p2p/${relay.peerId}/p2p-circuit/p2p/${libp2pB.peerId}`)
110110
const connection = await libp2pA.dial(relayedAddress)
111111

112-
// connection should be transient
113-
expect(connection).to.have.property('transient', true)
112+
// connection should be limited
113+
expect(connection).to.have.property('limited', true)
114114

115115
// wait for DCUtR unilateral upgrade
116116
await waitForOnlyDirectConnections()
@@ -166,8 +166,8 @@ describe('dcutr', () => {
166166
const relayedAddress = multiaddr(`/ip4/127.0.0.1/tcp/${RELAY_PORT}/p2p/${relay.peerId}/p2p-circuit/p2p/${libp2pB.peerId}`)
167167
const connection = await libp2pA.dial(relayedAddress)
168168

169-
// connection should be transient
170-
expect(connection).to.have.property('transient', true)
169+
// connection should be limited
170+
expect(connection).to.have.property('limited', true)
171171

172172
// wait for DCUtR unilateral upgrade
173173
await waitForOnlyDirectConnections()

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ describe('ping', () => {
7676
stream
7777
)
7878
}, {
79-
runOnTransientConnection: true
79+
runOnLimitedConnection: true
8080
})
8181

8282
const latency = await nodes[0].services.ping.ping(nodes[1].getMultiaddrs())

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { Uint8ArrayList } from 'uint8arraylist'
99
import { mockMultiaddrConnection } from './multiaddr-connection.js'
1010
import { mockMuxer } from './muxer.js'
1111
import { mockRegistrar } from './registrar.js'
12-
import type { AbortOptions, ComponentLogger, Logger, MultiaddrConnection, Connection, Stream, Direction, ConnectionTimeline, ConnectionStatus, PeerId, StreamMuxer, StreamMuxerFactory, NewStreamOptions } from '@libp2p/interface'
12+
import type { AbortOptions, ComponentLogger, Logger, MultiaddrConnection, Connection, Stream, Direction, ConnectionTimeline, ConnectionStatus, PeerId, StreamMuxer, StreamMuxerFactory, NewStreamOptions, ConnectionLimits } from '@libp2p/interface'
1313
import type { Registrar } from '@libp2p/interface-internal'
1414
import type { Multiaddr } from '@multiformats/multiaddr'
1515
import type { Duplex, Source } from 'it-stream-types'
@@ -41,7 +41,7 @@ class MockConnection implements Connection {
4141
public status: ConnectionStatus
4242
public streams: Stream[]
4343
public tags: string[]
44-
public transient: boolean
44+
public limits?: ConnectionLimits
4545
public log: Logger
4646

4747
private readonly muxer: StreamMuxer
@@ -64,7 +64,6 @@ class MockConnection implements Connection {
6464
this.tags = []
6565
this.muxer = muxer
6666
this.maConn = maConn
67-
this.transient = false
6867
this.logger = logger
6968
this.log = logger.forComponent(this.id)
7069
}

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,11 @@ export interface StreamHandlerOptions {
3030
/**
3131
* If true, allow this protocol to run on limited connections (e.g.
3232
* connections with data or duration limits such as circuit relay
33-
* connections) (default: false)
33+
* connections)
34+
*
35+
* @default false
3436
*/
35-
runOnTransientConnection?: boolean
37+
runOnLimitedConnection?: boolean
3638
}
3739

3840
export interface StreamHandlerRecord {

‎packages/interface/src/connection/index.ts

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -185,12 +185,16 @@ export interface NewStreamOptions extends AbortOptions {
185185
maxOutboundStreams?: number
186186

187187
/**
188-
* Opt-in to running over a transient connection - one that has time/data limits
189-
* placed on it.
188+
* Opt-in to running over a limited connection - one that has restrictions
189+
* on the amount of data that may be transferred or how long it may be open for.
190+
*
191+
* These limits are typically enforced by a relay server, if the protocol
192+
* will be transferring a lot of data or the stream will be open for a long time
193+
* consider upgrading to a direct connection before opening the stream.
190194
*
191195
* @default false
192196
*/
193-
runOnTransientConnection?: boolean
197+
runOnLimitedConnection?: boolean
194198

195199
/**
196200
* By default when negotiating a protocol the dialer writes then protocol name
@@ -222,6 +226,11 @@ export interface NewStreamOptions extends AbortOptions {
222226

223227
export type ConnectionStatus = 'open' | 'closing' | 'closed'
224228

229+
export interface ConnectionLimits {
230+
bytes?: number
231+
seconds?: number
232+
}
233+
225234
/**
226235
* A Connection is a high-level representation of a connection
227236
* to a remote peer that may have been secured by encryption and
@@ -280,12 +289,11 @@ export interface Connection {
280289
status: ConnectionStatus
281290

282291
/**
283-
* A transient connection is one that is not expected to be open for very long
284-
* or one that cannot transfer very much data, such as one being used as a
285-
* circuit relay connection. Protocols need to explicitly opt-in to being run
286-
* over transient connections.
292+
* If present, this connection has limits applied to it, perhaps by an
293+
* intermediate relay. Once the limits have been reached the connection will
294+
* be closed by the relay.
287295
*/
288-
transient: boolean
296+
limits?: ConnectionLimits
289297

290298
/**
291299
* Create a new stream on this connection and negotiate one of the passed protocols

‎packages/interface/src/index.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,7 @@ export interface IsDialableOptions extends AbortOptions {
331331
* because that protocol would not be allowed to run over a data/time limited
332332
* connection.
333333
*/
334-
runOnTransientConnection?: boolean
334+
runOnLimitedConnection?: boolean
335335
}
336336

337337
export type TransportManagerDialProgressEvents =

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@ export interface StreamHandlerOptions {
2121
maxOutboundStreams?: number
2222

2323
/**
24-
* Opt-in to running over a transient connection - one that has time/data limits
25-
* placed on it.
24+
* Opt-in to running over connections with limits on how much data can be
25+
* transferred or how long it can be open for.
2626
*/
27-
runOnTransientConnection?: boolean
27+
runOnLimitedConnection?: boolean
2828
}
2929

3030
export interface StreamHandlerRecord {

‎packages/interface/src/topology/index.ts

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,13 @@ export interface Topology {
2727
filter?: TopologyFilter
2828

2929
/**
30-
* If true, invoke `onConnect` for this topology on transient (e.g. short-lived
31-
* and/or data-limited) connections
30+
* If true, invoke `onConnect` for this topology on limited connections, e.g.
31+
* ones with limits on how much data can be transferred or how long they can
32+
* be open for.
3233
*
3334
* @default false
3435
*/
35-
notifyOnTransient?: boolean
36+
notifyOnLimitedConnection?: boolean
3637

3738
/**
3839
* Invoked when a new connection is opened to a peer that supports the

‎packages/interface/src/transport/index.ts

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { Connection, MultiaddrConnection } from '../connection/index.js'
1+
import type { Connection, ConnectionLimits, MultiaddrConnection } from '../connection/index.js'
22
import type { TypedEventTarget } from '../event-target.js'
33
import type { AbortOptions } from '../index.js'
44
import type { StreamMuxerFactory } from '../stream-muxer/index.js'
@@ -104,12 +104,7 @@ export interface UpgraderOptions<ConnectionUpgradeEvents extends ProgressEvent =
104104
skipEncryption?: boolean
105105
skipProtection?: boolean
106106
muxerFactory?: StreamMuxerFactory
107-
108-
/**
109-
* The passed MultiaddrConnection has limits place on duration and/or data
110-
* transfer amounts so is not expected to be open for very long.
111-
*/
112-
transient?: boolean
107+
limits?: ConnectionLimits
113108
}
114109

115110
export type InboundConnectionUpgradeEvents =

0 commit comments

Comments
 (0)