Add AllocationHandler

[stv0g]

We should think about adding support for an AllocationHandler in a similar fashion like we already have for the PermissionHandler.

My motiviation behind it is the following:

We could use such a AllocationHandler to redirect clients via a ALTERNATE-SERVER response to other TURN servers.
However, we should give some flexibility to the user when and which alternate servers are signaled to the client.
This allows the user to define its own schemes to detect an overloaded server, or cycle through different available alternate servers.

[rg0now]

Seems like a useful thing to add. Can you be a bit more specific though? What's the API? Where would we call the allocation handler, inside server.CreateAllocation? What would our allocation handler receive as argument and what to return?

[stv0g]

Where would we call the allocation handler, inside server.CreateAllocation?

This would be in internal/server.Server.handleAllocate().
Actually, the function already contains a comment:

turn/internal/server/turn.go

Lines 112 to 122 in f880e55

	// 7. At any point, the server MAY choose to reject the request with a
	// 486 (Allocation Quota Reached) error if it feels the client is
	// trying to exceed some locally defined allocation quota. The
	// server is free to define this allocation quota any way it wishes,
	// but SHOULD define it based on the username used to authenticate
	// the request, and not on the client's transport address.
	// 8. Also at any point, the server MAY choose to reject the request
	// with a 300 (Try Alternate) error if it wishes to redirect the
	// client to a different server. The use of this error code and
	// attribute follow the specification in [RFC5389].

What would our allocation handler receive as argument and what to return?

Good question. What about the following (just a first proposal):

// AllocationHandler is a callback to ...
type AllocationHandler func(clientAddr net.Addr) (alternateServer *net.UDPAddr, stun.ErrorCode)

[rg0now]

Do you also want to handle the allocation quota case (as per point 7 above) in the same AllocationHandler callback, or it is intended only for signaling the ALTERNATE-SERVER response?

Why I'm asking this is that every now and then our users complain about the lack of allocation quotas. So far, I failed to find sane API to support this: should we limit allocations per source IP? Or per TURN username/credential? Total allocations?

I guess coturn implements the first approach and the third one:

# consider whether you want to limit the quota of relayed streams per user (or total) to avoid risk of DoS.
user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user.
total-quota=1200

If we follow this course then I think your AllocationHandler API could also be used to support user quotas and total quotas. Wdyt?

[stv0g]

Hi @rg0now,

yes this was my plan to also cover quotas with this handler. The whole logic about which quotas are enforced should be user customizable with the handler. We could event provide a few generic handlers for covering the easy cases like you mentioned.

It would also be nice to have the TURN credentials as an argument for the handler to cover per-user quotas.
Hence, we must probably include the TURN credentials as an argument.

I initially also thought about using the handler for implementing custom authentication logic. However we already have the AuthHandler for this..