[RFC] Simplified Client API

[rg0now]

With the upcoming addition of TURN/TCP allocations, the mental complexity of working with the client API is becoming unwieldy. As pion/turn gains adoption in areas beyond WebRTC (VPNs, P2P networks, tunneling), this complexity may become a barrier to entry. This PR proposes a simplified client API that mimics the familiar Dialer and Listener interfaces, even at the cost of hiding some TURN complexity. For simple use cases this API should be easier to pick up, while the current client API remains available for users that want full control.

This is just a humble PR to raise some discussion, definitely not production ready.

The Problem

With TCP allocations, we now have two fundamentally different workflows for connecting to peers:

• UDP: Call client.Allocate() -> returns net.PacketConn -> use WriteTo/ReadFrom
• TCP: Call client.AllocateTCP() -> returns *client.TCPAllocation -> call DialTCP() -> returns net.Conn

Likewise for "accepting" peer connections:

• UDP: ReadFrom on the net.PacketConn returned by client.Allocate()
• TCP: Accept on the *client.TCPAllocation returned from client.AllocateTCP()

Plus there's the complexity of managing peer permissions and client.Listen() that users often forget to call.

Proposal

A unified Allocation interface that works like a combined Dialer + Listener:

type Allocation interface {
    Dial(network, address string) (net.Conn, error)
    Accept() (net.Conn, error)
    Addr() net.Addr
    Close() error
    CreatePermission(addr net.Addr) error
}

Key simplifications:

• Single constructor (NewAllocation) for both UDP and TCP
• Dial() handles permission creation internally
• Accept() works uniformly across both transport types
• Returns standard net.Conn instead of protocol-specific types

Usage

Create UDP allocation:

alloc, _ := turn.NewAllocation("udp", &turn.ClientConfig{
    Conn:           turnConn,
    TURNServerAddr: "turn.example.com:3478",
    Username:       "user",
    Password:       "pass",
    Realm:          "example.com",
})
defer alloc.Close()

For TCP, just set the network type to "tcp" and pass in a TCP TURN socket.

Dial a peer

Dial creates permission automatically and returns a net.Conn bound to the peer both for UDP and TCP.

conn, _ := alloc.Dial("udp", "192.0.2.1:5000")
conn.Write([]byte("hello"))

Accept incoming connections from permitted peers

Note that Dial automatically calls CreatePermission, but for listeners CreatePermission must be called explicitly.

_ = alloc.CreatePermission(peer)
incoming, _ := alloc.Accept()
// handle incoming...

[codecov]

Codecov Report

❌ Patch coverage is 69.76744% with 52 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.16%. Comparing base (27f733c) to head (e924e07).

Files with missing lines	Patch %	Lines
allocation.go	69.41%	42 Missing and 10 partials ⚠️

❌ Your patch check has failed because the patch coverage (69.76%) is below the target coverage (70.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #526      +/-   ##
==========================================
- Coverage   81.72%   81.16%   -0.56%     
==========================================
  Files          46       47       +1     
  Lines        3157     3329     +172     
==========================================
+ Hits         2580     2702     +122     
- Misses        375      416      +41     
- Partials      202      211       +9     

Flag	Coverage Δ
go	81.16% <69.76%> (-0.56%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Sean-Der]

I am all for it @rg0now as long as we drop the previous API!

• Could we be making a mistake doing UDP traffic over a net.Conn? If each Read/Write is one datagram seems ok?
• Does CreatePermission need to exist? Could Accept(addr net.Addr) be a thing? Would I ever need to a create a Permission if I didn't intend to accept traffic upon it? If a user wants to Accept anything pass a nil address?

@jech @JoTurk what's your take?

[rg0now]

I am all for it @rg0now as long as we drop the previous API!

Huhh, that's a tough call. I'm afraid this would be a massive rewrite burden on people using pion/turn. Plus the this PR merely calls into the existing API so we cannot remove it right now anyway. And then there's the issue that this API hides some features (like PerformTransaction, HandleInbound, Connect and BindConnection, etc.) that people may rely on. Plus the code should really really get some testing...

Could we be making a mistake doing UDP traffic over a net.Conn? If each Read/Write is one datagram seems ok?

The net.Conn that Dial("udp", peer) returns is merely a wrapper on top of the existing UDPConn, just with binding automatically calling WriteTo/ReadFrom with peer as the destination address. So everything that applies to UDPConn applies to our net.Conn too.

Does CreatePermission need to exist? Could Accept(addr net.Addr) be a thing? Would I ever need to a create a Permission if I didn't intend to accept traffic upon it? If a user wants to Accept anything pass a nil address?

I was hesitating whether to do this but eventually decided to go with CreatePermission/Accept. The problem is that there can be more than one peer that may request a connection over the allocation at any instance of time and it would be difficult to orchestrate multiple parallel blocking Accept(peer) calls.

Note that you only need to call CreatePermission if you call Accept before/without a Dial (Dial automatically manages permissions), but I think this is the rare case for TURN. The more I think about it the more I feel this is the right thing to do not just for TURN but maybe also for plain old UDP: it is a natural thing to want to decide who can send on a connectionless channel.

[JoTurk]

I agree with the permissions API comment, maybe we just need a higher-level API?

Thank you, this is a really cool API.

[JoTurk]

Am i missing something or why we don't return Allocation seems more straightforward to keep the details private?

[JoTurk]

Should we lock before checking closed?

[JoTurk]

How do we handle this? do we enqueue it somewhere else? i couldn't find it.

[rg0now]

The idea is that when the accept queue is full we just drop the connection. E.g., TCP does some 3way handshake magic in such cases that we cannot reproduce here. However I think we'd better unregister the dropped call first. We should probably also emit a log at some point...

[JoTurk]

Maybe if we accept network we should take udp4/udp6/tcp4/tcp6 too.

[rg0now]

Very true. We'll get back to this once #528 is merged