uas

Documentation

Overview

Package uas registers inbound (UAS) SIP method handlers on stack.Endpoint.

Handler wiring

Handlers is a struct of typed callbacks (InviteHandler, SimpleHandler, AckHandler). Attach registers them on stack.Endpoint; AttachWithTransaction also chains the transaction layer (retransmissions, CANCEL, ACK, BeginInviteServer).

Inbound INVITE flow (with transaction binding)

1. UDP datagram → stack.Endpoint parses INVITE
2. ChainInviteServerTx: duplicate INVITE → resend stored final (if any)
3. InviteHandler runs → returns 100/180/200 (or nil to suppress auto-send)
4. stack.Endpoint sends response on UDP
5. OnResponseSent → AfterResponseSentBeginServerTx → transaction.BeginInviteServer
6. ACK arrives → ChainAckServerTx → transaction.HandleAck (stops 2xx retransmit)

CANCEL before final:

WrapHandlersWithTransaction replaces Cancel handler → HandleCancelRequest (200 to CANCEL)
TU must still answer INVITE with 487 (or similar).

Building responses

Use NewResponse / ErrorResponse — they copy stack.CorrelationHeaders from the request and set stack.HeaderContentLength. Provisional responses should add To ;tag= via dialog.AppendTagAfterNameAddr.

Helpers (server_tx.go)

• ChainInviteServerTx / ChainNonInviteServerTx — absorb retransmissions
• AfterResponseSentBeginServerTx — register server transaction after final on wire
• ChainAckServerTx — match ACK to pending INVITE server tx
• WithOnResponseSentAppended — compose OnResponseSent hooks

Media (RTP/codec) lives in protocol/sipmedia; dialog tags in protocol/sip/dialog.

Index

• func AfterResponseSentBeginInviteServer(mgr *transaction.Manager, srvCtx context.Context, send transaction.SendFunc) func(*stack.Message, *stack.Message, *net.UDPAddr)
• func AfterResponseSentBeginServerTx(mgr *transaction.Manager, srvCtx context.Context, send transaction.SendFunc) func(*stack.Message, *stack.Message, *net.UDPAddr)
• func ErrorResponse(req *stack.Message, status int, reason string) (*stack.Message, error)
• func FormatContact(host string, port int, user string) string
• func NewResponse(req *stack.Message, status int, reason, body, contentType string) (*stack.Message, error)
• func WithOnResponseSentAppended(cfg stack.EndpointConfig, ...) stack.EndpointConfig
• type AckHandler
  • func ChainAckServerTx(mgr *transaction.Manager, inner AckHandler) AckHandler
• type Handlers
  • func WrapHandlersWithTransaction(h Handlers, b TransactionBinding) Handlers
  • func (h Handlers) Attach(ep *stack.Endpoint) error
  • func (h Handlers) AttachWithTransaction(ep *stack.Endpoint, b TransactionBinding) error
• type InviteHandler
  • func ChainInviteServerTx(mgr *transaction.Manager, inner InviteHandler) InviteHandler
• type SimpleHandler
  • func ChainNonInviteServerTx(mgr *transaction.Manager, inner SimpleHandler) SimpleHandler
• type TransactionBinding

Functions

func AfterResponseSentBeginInviteServer

func AfterResponseSentBeginInviteServer(mgr *transaction.Manager, srvCtx context.Context, send transaction.SendFunc) func(*stack.Message, *stack.Message, *net.UDPAddr)

AfterResponseSentBeginInviteServer is equivalent to AfterResponseSentBeginServerTx for INVITE-only setups.

func AfterResponseSentBeginServerTx

func AfterResponseSentBeginServerTx(mgr *transaction.Manager, srvCtx context.Context, send transaction.SendFunc) func(*stack.Message, *stack.Message, *net.UDPAddr)

AfterResponseSentBeginServerTx registers the correct UAS server transaction after a final response is on the wire: INVITE → BeginInviteServer; other methods (OPTIONS, REGISTER, BYE, …) → BeginNonInviteServer.

func ErrorResponse

func ErrorResponse(req *stack.Message, status int, reason string) (*stack.Message, error)

ErrorResponse returns a minimal final error response (3xx–6xx) with optional Reason header text in StatusText.

func FormatContact

func FormatContact(host string, port int, user string) string

FormatContact builds a SIP Contact header field value. user may be empty for the host-only form <sip:host:port>.

func NewResponse

func NewResponse(req *stack.Message, status int, reason, body, contentType string) (*stack.Message, error)

NewResponse builds a SIP response with common headers copied from the request (From, To, Call-ID, CSeq, Via). body and contentType may be empty for no body (Content-Length: 0).

func WithOnResponseSentAppended

func WithOnResponseSentAppended(cfg stack.EndpointConfig, fn func(*stack.Message, *stack.Message, *net.UDPAddr)) stack.EndpointConfig

WithOnResponseSentAppended returns a copy of cfg with fn chained after the previous OnResponseSent (if any).

Types

type AckHandler

type AckHandler func(req *stack.Message, addr *net.UDPAddr) error

AckHandler handles inbound ACK (no response is sent on the same socket for ACK).

func ChainAckServerTx

func ChainAckServerTx(mgr *transaction.Manager, inner AckHandler) AckHandler

ChainAckServerTx invokes mgr.HandleAck before the application handler (dialog teardown, media stop, etc.).

type Handlers

type Handlers struct {
	Invite    InviteHandler
	Ack       AckHandler
	Bye       SimpleHandler
	Cancel    SimpleHandler
	Options   SimpleHandler
	Register  SimpleHandler
	Info      SimpleHandler
	Prack     SimpleHandler
	Subscribe SimpleHandler
	Notify    SimpleHandler
	Publish   SimpleHandler
	Refer     SimpleHandler
	Message   SimpleHandler
	Update    SimpleHandler
}

Handlers lists optional UAS callbacks. Nil fields are not registered. Register with (*stack.Endpoint).RegisterHandler via Handlers.Attach.

func WrapHandlersWithTransaction

func WrapHandlersWithTransaction(h Handlers, b TransactionBinding) Handlers

WrapHandlersWithTransaction returns a copy of h with INVITE / non-INVITE / CANCEL / ACK hooks chained in front of the transaction layer. If Mgr or Send is nil, h is returned unchanged.

func (Handlers) Attach

func (h Handlers) Attach(ep *stack.Endpoint) error

Attach registers all non-nil handlers on ep. If Options is nil, a default OPTIONS 200 handler is installed.

func (Handlers) AttachWithTransaction

func (h Handlers) AttachWithTransaction(ep *stack.Endpoint, b TransactionBinding) error

AttachWithTransaction appends AfterResponseSentBeginServerTx then registers wrapped handlers. Use when building a UAS: pass the same Manager and Send used for HandleInviteRequest / HandleCancelRequest.

type InviteHandler

type InviteHandler func(req *stack.Message, addr *net.UDPAddr) (*stack.Message, error)

InviteHandler handles an inbound INVITE. Return nil, nil to send nothing (rare); return an error to answer 500.

func ChainInviteServerTx

func ChainInviteServerTx(mgr *transaction.Manager, inner InviteHandler) InviteHandler

ChainInviteServerTx wraps an INVITE handler: duplicate INVITE retransmissions are absorbed by mgr (final resent inside HandleInviteRequest). If mgr is nil, inner is returned unchanged.

type SimpleHandler

type SimpleHandler func(req *stack.Message, addr *net.UDPAddr) (*stack.Message, error)

SimpleHandler handles a request that typically answers with a small final response (BYE, CANCEL, …).

func ChainNonInviteServerTx

func ChainNonInviteServerTx(mgr *transaction.Manager, inner SimpleHandler) SimpleHandler

ChainNonInviteServerTx absorbs duplicate non-INVITE requests (OPTIONS, REGISTER, BYE, …) before inner runs.

type TransactionBinding

type TransactionBinding struct {
	Mgr *transaction.Manager
	// Send must send requests/responses on the same UDP socket as ep (typically ep.Send).
	Send transaction.SendFunc
	// Ctx bounds background server timers; if nil, context.Background is used.
	Ctx context.Context
}

TransactionBinding wires a transaction.Manager and signaling Send path for UAS server-tx behavior.