Documentation
¶
Overview ¶
Package stunner contains the public API for l7mp/stunner, a Kubernetes ingress gateway for WebRTC.
Index ¶
- Constants
- Variables
- func GenerateSelfSignedKey() ([]byte, []byte, error)
- func NewDefaultConfig(uri string) (*stnrv2.StunnerConfig, error)
- type LogOptions
- type Options
- type Stunner
- func (s *Stunner) AllocationCount() int
- func (s *Stunner) Close()
- func (s *Stunner) GetActiveConnections() int64
- func (s *Stunner) GetAdmin() *object.Admin
- func (s *Stunner) GetAuth(name string) *object.Auth
- func (s *Stunner) GetCluster(name string) *object.Cluster
- func (s *Stunner) GetConfig() *stnrv2.StunnerConfig
- func (s *Stunner) GetId() string
- func (s *Stunner) GetListener(name string) *object.Listener
- func (s *Stunner) GetListeners() []*object.Listener
- func (s *Stunner) GetLogger() logging.LoggerFactory
- func (s *Stunner) GetServer(name string) runtime.Object
- func (s *Stunner) GetServers() []runtime.Object
- func (s *Stunner) GetStatus() stnrv2.Status
- func (s *Stunner) GetVersion() string
- func (s *Stunner) IsReady() bool
- func (s *Stunner) LoadConfig(origin string) (*stnrv2.StunnerConfig, error)
- func (s *Stunner) Reconcile(req *stnrv2.StunnerConfig) error
- func (s *Stunner) SetLogLevel(levelSpec string)
- func (s *Stunner) Shutdown()
- func (s *Stunner) WatchConfig(ctx context.Context, origin string, ch chan<- *stnrv2.StunnerConfig, ...) error
Constants ¶
const DefaultLogLevel = "all:WARN"
DefaultLogLevel indicates the default log level.
Variables ¶
var DefaultInstanceId = fmt.Sprintf("default/stunnerd-%s", uuid.New().String())
DefaultInstanceId is the default instance id for stunnerd processes.
var LogBurst = 50
LogBurst is the default burst size of a rate-limited logger.
var LogRateLimit rate.Limit = 5.0
LogRateLimit is the default number of log events per second of a rate-limited logger, at every level: the loggers a client can make log per packet, see LogRateLimitedScopes.
var LogRateLimitedScopes = []string{"listener-", "cluster-", "server-", "turn"}
LogRateLimitedScopes are the prefixes of the rate-limited logger scopes: the listeners, the clusters, the servers and the TURN machinery, each scope with a token bucket of its own.
Functions ¶
func GenerateSelfSignedKey ¶
GenerateSelfSignedKey is a rudimentary hack to generate self-signed certificates used to bootstrap the default config for TLS/DTLS listeners and for testing. Use for testing purposes only!
func NewDefaultConfig ¶
func NewDefaultConfig(uri string) (*stnrv2.StunnerConfig, error)
NewDefaultConfig builds a default configuration from a TURN server URI. Example: the URI `turn://user:pass@127.0.0.1:3478?transport=udp` will be parsed into a STUNner configuration with a TURN server listening at UDP port 3478 on every address and advertising its relays at 127.0.0.1, with plain-text authentication using the username/password pair `user:pass`, relaying to every peer. Health-checking is enabled at the default endpoint, metric scraping is disabled.
Types ¶
type LogOptions ¶
LogOptions configures logging behavior for STUNner.
type Options ¶
type Options struct {
// Name is the identifier of this stunnerd daemon instance. Defaults to hostname.
Name string
// DryRun suppresses sideeffects: STUNner will not initialize listener sockets and bring up
// the TURN server, and it will not fire up the health-check and the metrics
// servers. Intended for testing, default is false.
DryRun bool
// SuppressRollback controls whether to rollback to the last working configuration after a
// failed reconciliation request. Default is false, which means to always do a rollback.
SuppressRollback bool
// LogOptions controls logger settings (level, optional rate limiter settings).
LogOptions LogOptions
// Resolver swaps the internal DNS resolver with a custom implementation. Intended for
// testing.
Resolver resolver.DnsResolver
// NodeName is the name of the Kubernetes node the TURN server is running on (if any).
NodeName string
// Net will switch on testing mode, using a vnet.Net instance to run STUNner over an
// emulated data-plane.
Net transport.Net
// BuildInfo is the version of the binary, reported in the admin status and the build info
// metric.
BuildInfo buildinfo.BuildInfo
}
Options defines various options for the STUNner server.
type Stunner ¶
type Stunner struct {
// contains filtered or unexported fields
}
Stunner is an instance of the STUNner daemon.
func NewStunner ¶
NewStunner creates a new STUNner daemon for the specified Options. Call Reconcile to reconcile the daemon for a new configuration. The daemon is "alive" once the main object is initialized, and "ready" after the first successful reconciliation.
func (*Stunner) AllocationCount ¶
AllocationCount returns the number of live sessions (TURN allocations and L4 flows) summed over all servers.
func (*Stunner) Close ¶
func (s *Stunner) Close()
Close stops the STUNner daemon, cleans up any internal state, and closes all connections.
func (*Stunner) GetActiveConnections ¶
GetActiveConnections returns the number of live sessions: TURN allocations and L4 flows.
func (*Stunner) GetAuth ¶
GetAuth returns the authentication policy of a name, or nil if there is none.
func (*Stunner) GetCluster ¶
GetCluster returns a Cluster by name, or nil if not found.
func (*Stunner) GetConfig ¶
func (s *Stunner) GetConfig() *stnrv2.StunnerConfig
GetConfig returns the configuration of the running STUNner daemon. The root Object assembles the StunnerConfig from its descendants, see internal/object/stunner.go.
func (*Stunner) GetListener ¶
GetListener returns a Listener by name, or nil if not found.
func (*Stunner) GetListeners ¶
GetListeners returns every Listener in stable order.
func (*Stunner) GetLogger ¶
func (s *Stunner) GetLogger() logging.LoggerFactory
GetLogger returns the logger factory of the running daemon.
func (*Stunner) GetServers ¶
GetServers returns every Server in stable order.
func (*Stunner) GetStatus ¶
GetStatus returns the status of the daemon: the statuses of its objects, the number of live sessions and the readiness. It is the status the /status endpoint of the health check serves.
func (*Stunner) GetVersion ¶
GetVersion returns the STUNner API version.
func (*Stunner) IsReady ¶
IsReady returns true if the STUNner instance is ready to serve allocation requests.
func (*Stunner) LoadConfig ¶
func (s *Stunner) LoadConfig(origin string) (*stnrv2.StunnerConfig, error)
LoadConfig loads a configuration from an origin, with the environment of this process substituted into it.
func (*Stunner) Reconcile ¶
func (s *Stunner) Reconcile(req *stnrv2.StunnerConfig) error
Reconcile handles updates to the STUNner configuration. The actual walk is delegated to the reconciler engine; this method only manages the readiness bit.
Returns nil if nothing changed in a way that required a restart, stnrv2.ErrRestarted listing any objects that were bounced (safe to ignore), or a non-nil error if the config was rejected, in which case the previous configuration is rolled back unless SuppressRollback is set.
func (*Stunner) SetLogLevel ¶
SetLogLevel sets the loglevel.
func (*Stunner) Shutdown ¶
func (s *Stunner) Shutdown()
Shutdown causes STUNner to fail the readiness check. Meanwhile, it will keep on serving connections. This function should be called after the main program catches a SIGTERM.
func (*Stunner) WatchConfig ¶
func (s *Stunner) WatchConfig(ctx context.Context, origin string, ch chan<- *stnrv2.StunnerConfig, suppressDelete bool) error
WatchConfig watches a configuration from an origin, with the environment of this process substituted into every update.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
icetester
command
|
|
|
mediactl
command
Command mediactl is a media source and sink for testing media gateways: it sends packets and measures what comes back, or answers and echoes, over SIP/RTP, UDP, TCP, TURN and SRT.
|
Command mediactl is a media source and sink for testing media gateways: it sends packets and measures what comes back, or answers and echoes, over SIP/RTP, UDP, TCP, TURN and SRT. |
|
stunnerctl
command
|
|
|
stunnerd
command
|
|
|
internal
|
|
|
api
Package api holds the contracts between the dataplane objects, which refer to each other by name.
|
Package api holds the contracts between the dataplane objects, which refer to each other by name. |
|
dialer
Package dialer implements the transport of a cluster: the conns, relay sockets and relayed listeners towards the peers, tagged and accounted under the cluster's name, and the socket of a dialing listener, which reaches its peer through a dialer of its own, accounted as the listener.
|
Package dialer implements the transport of a cluster: the conns, relay sockets and relayed listeners towards the peers, tagged and accounted under the cluster's name, and the socket of a dialing listener, which reaches its peer through a dialer of its own, accounted as the listener. |
|
filter
Package filter implements the filters of stunnerd: named rules admitting or dropping traffic by address and port.
|
Package filter implements the filters of stunnerd: named rules admitting or dropping traffic by address and port. |
|
netconn
Package netconn tags a conn with its listener or cluster and its wire.
|
Package netconn tags a conn with its listener or cluster and its wire. |
|
netconn/account
Package account is the accounting layer of the conn stack: it counts the traffic of a transport in telemetry under the name of the listener or cluster the transport belongs to, and adds no getter of its own, so what comes out is the same contract that went in.
|
Package account is the accounting layer of the conn stack: it counts the traffic of a transport in telemetry under the name of the listener or cluster the transport belongs to, and adds no getter of its own, so what comes out is the same contract that went in. |
|
object
Package object implements the STUNner dataplane objects (Admin, Auth, Filter, Cluster, Server, Listener, Health, Metrics, Offload) and the declarative object hierarchy (the catalog).
|
Package object implements the STUNner dataplane objects (Admin, Auth, Filter, Cluster, Server, Listener, Health, Metrics, Offload) and the declarative object hierarchy (the catalog). |
|
offload
Package offload implements the kernel offload of relayed UDP flows.
|
Package offload implements the kernel offload of relayed UDP flows. |
|
proto/fifo
Package fifo implements in-process named fifos: a listener makes a fifo under a name and a dialer opens it.
|
Package fifo implements in-process named fifos: a listener makes a fifo under a name and a dialer opens it. |
|
proto/ng
Package ng implements rtpengine's ng control protocol, in bencode or JSON.
|
Package ng implements rtpengine's ng control protocol, in bencode or JSON. |
|
proto/siptx
Package siptx runs SIP transactions over net.Conns, on sipgo's transactions.
|
Package siptx runs SIP transactions over net.Conns, on sipgo's transactions. |
|
reconciler
Package reconciler implements the engine that converges the STUNner object tree to a desired StunnerConfig.
|
Package reconciler implements the engine that converges the STUNner object tree to a desired StunnerConfig. |
|
router
Package router implements the destinations of a cluster: its endpoints, resolved.
|
Package router implements the destinations of a cluster: its endpoints, resolved. |
|
runtime
Package runtime is the kernel of the STUNner object system: it defines the node contracts (Runnable, Reconcilable, Object), the Registry that stores every live node keyed by (type, name) with parent edges, and the Runtime, the single cross-object access point carrying process-wide dependencies, registry-backed config/status lookups, and the readiness/shutdown flags.
|
Package runtime is the kernel of the STUNner object system: it defines the node contracts (Runnable, Reconcilable, Object), the Registry that stores every live node keyed by (type, name) with parent edges, and the Runtime, the single cross-object access point carrying process-wide dependencies, registry-backed config/status lookups, and the readiness/shutdown flags. |
|
server
Package server holds what the TURN and L4 servers (the subpackages) share: the accept queue, the conntrack and ErrNotServing.
|
Package server holds what the TURN and L4 servers (the subpackages) share: the accept queue, the conntrack and ErrNotServing. |
|
server/balancer
Package balancer chooses the peers of a server among the targets of its clusters, by a load-balancing policy.
|
Package balancer chooses the peers of a server among the targets of its clusters, by a load-balancing policy. |
|
server/l4
Package l4 implements the L4 server: every client conn becomes a flow to an endpoint of the server's clusters.
|
Package l4 implements the L4 server: every client conn becomes a flow to an endpoint of the server's clusters. |
|
server/rtp
Package rtp implements the RTP server, a media proxy driven over ng.
|
Package rtp implements the RTP server, a media proxy driven over ng. |
|
server/sip
Package sip implements the SIP server, a transaction-stateful proxy of inbound calls.
|
Package sip implements the SIP server, a transaction-stateful proxy of inbound calls. |
|
server/srt
Package srt implements the SRT server: it routes every SRT flow by the stream it names to the endpoint holding the stream and relays it, the stream's encryption untouched.
|
Package srt implements the SRT server: it routes every SRT flow by the stream it names to the endpoint holding the stream and relays it, the stream's encryption untouched. |
|
server/turn
Package turn implements the TURN server: one pion/turn instance serving the client conns handed to it, relaying through the server's clusters.
|
Package turn implements the TURN server: one pion/turn instance serving the client conns handed to it, relaying through the server's clusters. |
|
pkg
|
|
|
apis/v1
Package v1 is the v1 version of the STUNner API.
|
Package v1 is the v1 version of the STUNner API. |
|
apis/v2
Package v2 is the v2 version of the STUNner API.
|
Package v2 is the v2 version of the STUNner API. |
|
authentication
Package authentication contains the routines a TURN server checks STUNner authentication credentials with; the credentials themselves are generated by the auth policies of the API.
|
Package authentication contains the routines a TURN server checks STUNner authentication credentials with; the credentials themselves are generated by the auth policies of the API. |
|
config/client/api
Package api provides primitives to interact with the openapi HTTP API.
|
Package api provides primitives to interact with the openapi HTTP API. |
|
config/license
Package to handle the licensing status of a client.
|
Package to handle the licensing status of a client. |
|
config/server/api
Package api provides primitives to interact with the openapi HTTP API.
|
Package api provides primitives to interact with the openapi HTTP API. |
|
icetester
Package icetester runs the ICE test of stunnerctl: it installs test Gateways and a WebRTC echo backend in a namespace of its own, then connects to the backend through every test Gateway, over TURN by WHIP, and streams packets to the echo.
|
Package icetester runs the ICE test of stunnerctl: it installs test Gateways and a WebRTC echo backend in a namespace of its own, then connects to the backend through every test Gateway, over TURN by WHIP, and streams packets to the echo. |
|
mediactl
Package mediactl holds the media sources and sinks of the mediactl tool and the tests: packet streams that measure the bitrate, the loss and the round trip, and echo servers, over any net.Conn.
|
Package mediactl holds the media sources and sinks of the mediactl tool and the tests: packet streams that measure the bitrate, the loss and the round trip, and echo servers, over any net.Conn. |
|
mediactl/k8s
Package k8s resolves the k8s:// addresses of mediactl and the stunnerd tunnel from a Kubernetes cluster, through the kubeconfig of the caller:
|
Package k8s resolves the k8s:// addresses of mediactl and the stunnerd tunnel from a Kubernetes cluster, through the kubeconfig of the caller: |
|
mediactl/rtp
Package rtp frames a packet conn as an RTP session: a net.Conn whose writes leave as the payloads of RTP packets and whose reads return the payloads of the RTP packets received.
|
Package rtp frames a packet conn as an RTP session: a net.Conn whose writes leave as the payloads of RTP packets and whose reads return the payloads of the RTP packets received. |
|
mediactl/sip
Package sip is a minimal SIP phone, a dialer and a listener of calls: Dial and DialContext return a call once it is answered, Accept the next call the phone answered.
|
Package sip is a minimal SIP phone, a dialer and a listener of calls: Dial and DialContext return a call once it is answered, Accept the next call the phone answered. |
|
mediactl/srt
Package srt holds the SRT dialer and listener of mediactl: a dialer calls for a stream in a mode, named in the access control syntax of the stream ID, a listener takes the callers of a passphrase, passes every published stream to the readers of the same stream itself and returns the other callers, for mediactl.Serve to echo.
|
Package srt holds the SRT dialer and listener of mediactl: a dialer calls for a stream in a mode, named in the access control syntax of the stream ID, a listener takes the callers of a passphrase, passes every published stream to the readers of the same stream itself and returns the other callers, for mediactl.Serve to echo. |
|
mediactl/turn
Package turn holds the TURN dialer of mediactl: conns to peers relayed through a TURN server, over a UDP allocation or an RFC 6062 TCP connection.
|
Package turn holds the TURN dialer of mediactl: conns to peers relayed through a TURN server, over a UDP allocation or an RFC 6062 TCP connection. |
|
udp
Package udp implements UDP listeners as net.Listeners: every client, identified by its address, gets a conn of its own.
|
Package udp implements UDP listeners as net.Listeners: every client, identified by its address, gets a conn of its own. |
|
utils/discovery
Package discovery finds STUNner's components in a Kubernetes cluster, the config discovery server of the gateway operator, the stunnerd pods of a Gateway and the auth service, and opens port-forwards to them.
|
Package discovery finds STUNner's components in a Kubernetes cluster, the config discovery server of the gateway operator, the stunnerd pods of a Gateway and the auth service, and opens port-forwards to them. |
|
utils/turnclient
Package turnclient opens client sessions on a TURN server over any of the TURN transports (TURN-UDP, TURN-TCP, TURN-TLS, TURN-DTLS).
|
Package turnclient opens client sessions on a TURN server over any of the TURN transports (TURN-UDP, TURN-TCP, TURN-TLS, TURN-DTLS). |
|
whipconn
A simple WHIP client and server that implement a stream connection abstraction on top of a WebRTC data channel published via WHIP.
|
A simple WHIP client and server that implement a stream connection abstraction on top of a WebRTC data channel published via WHIP. |