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:

https://github.com/pion/turn/blob/f880e55089ad0e0cdb53c5a0e6b89954512dada6/internal/server/turn.go#L112-L122

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..