relay

type Config struct {
	// Listen is the UDP address to serve STUN and TURN on. Use a zero port to
	// let the kernel choose one, then read [Server.Addr].
	Listen string

	// ListenTCP, when set, is a TCP address on which TURN is also served for
	// clients behind UDP-hostile firewalls. STUN over TCP is answered too.
	ListenTCP string

	// Realm is the TURN realm. It defaults to [DefaultRealm].
	Realm string

	// Users maps TURN username to credential and plan for static
	// authentication.
	Users map[string]User

	// AuthSecret, when set, enables ephemeral credentials in the TURN REST API
	// format: the username is "<unix expiry>:<user id>" and the password is
	// the base64 HMAC-SHA1 of the username under the secret. Issue them with
	// [Server.IssueCredentials] or [IssueCredentials]. Static Users still work
	// alongside.
	AuthSecret string

	// Plans are the named budgets users may be assigned to.
	Plans map[string]Plan

	// DefaultPlan applies to users without a plan. Its zero value means an
	// unlimited relay.
	DefaultPlan Plan

	// PlanFor, when set, chooses the plan name for an authenticated user ID.
	// The default looks the ID up in Users, then treats a "name@plan" ID as
	// selecting plan, and otherwise uses DefaultPlan. Ephemeral credentials
	// carry the plan in the user ID that way: "alice@paid".
	PlanFor func(userID string) string

	// RelayIP is the address handed to clients as their relay address. It
	// defaults to the IP of the resolved listen address, which is what a local
	// example wants. A server behind NAT must set its public address here.
	RelayIP net.IP

	// MinPort and MaxPort, when both set, restrict relay sockets to that
	// inclusive range, which is what a firewall or a Docker port mapping needs.
	// When zero, the kernel picks ephemeral ports.
	MinPort, MaxPort uint16

	// Logger receives lifecycle events. Credentials are never logged.
	Logger *slog.Logger
}

type Plan struct {
	// Rate limits each allocated relay socket, in bytes per second per
	// direction. Zero means unlimited.
	Rate int64

	// Burst is the token bucket depth in bytes. It defaults to a tenth of a
	// second of Rate, and is never smaller than 64 KiB.
	Burst int64

	// MaxDelay bounds how long an inbound relayed packet may be held waiting for
	// budget. Packets that would wait longer are dropped, which is how a
	// congested link behaves. It defaults to [DefaultMaxDelay]; a zero-length
	// delay is expressed as a negative value.
	MaxDelay time.Duration

	// MaxAllocations bounds the relay sockets one user may hold at a time. A
	// pipe connection uses one allocation per side. Zero means unlimited.
	MaxAllocations int
}

type Server struct {
	// contains filtered or unexported fields
}

type Stats struct {
	// Allocations counts relay sockets created since startup.
	Allocations int64

	// Active counts relay sockets open right now.
	Active int64

	// SentBytes and SentPackets count traffic from a client toward a peer.
	SentBytes, SentPackets int64

	// ReceivedBytes and ReceivedPackets count traffic from a peer toward a
	// client.
	ReceivedBytes, ReceivedPackets int64

	// DroppedBytes and DroppedPackets count traffic discarded because it
	// exceeded the throughput budget.
	DroppedBytes, DroppedPackets int64

	// DelayedPackets counts packets held to stay inside the budget.
	DelayedPackets int64

	// Users breaks the counters down by authenticated user ID.
	Users map[string]UserStats
}

type User struct {
	// Password is the long-term credential. It is digested at startup and
	// never kept in memory afterwards.
	Password string

	// Plan names an entry in [Config.Plans]. Empty selects
	// [Config.DefaultPlan].
	Plan string
}

type UserStats struct {
	// Plan is the plan name the user resolved to.
	Plan string

	// Allocations counts relay sockets created for the user; Active counts
	// the ones open right now.
	Allocations, Active int64

	// SentBytes and ReceivedBytes count relayed traffic in each direction.
	SentBytes, ReceivedBytes int64

	// DroppedBytes and DroppedPackets count traffic over the plan's budget.
	DroppedBytes, DroppedPackets int64

	// RejectedAllocations counts Allocate requests refused by the plan's
	// MaxAllocations quota.
	RejectedAllocations int64
}