Documentation
¶
Overview ¶
Package fakepbx provides an in-process SIP server for testing.
It wraps sipgo to create a real SIP server bound to 127.0.0.1 on an ephemeral port. Tests get full programmatic control over SIP call flows — INVITE, REGISTER, BYE, CANCEL, REFER, OPTIONS, INFO, MESSAGE, SUBSCRIBE — without Docker, external processes, or hardcoded ports.
FakePBX works as both UAS (receiving calls) and UAC (initiating calls):
pbx := fakepbx.NewFakePBX(t)
// UAS: handle incoming INVITEs from the device under test
pbx.OnInvite(func(inv *fakepbx.Invite) {
inv.Trying()
inv.Ringing()
inv.Answer(fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU))
})
// UAC: send an INVITE to the device under test
call, err := pbx.SendInvite(ctx, "sip:alice@127.0.0.1:5060",
fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU))
The server is stopped automatically via testing.TB.Cleanup.
Index ¶
- Variables
- func SDP(ip string, port int, codecs ...Codec) []byte
- func SDPWithDirection(ip string, port int, direction string, codecs ...Codec) []byte
- type Ack
- type ActiveCall
- type Bye
- type Cancel
- type Codec
- type FakePBX
- func (pbx *FakePBX) AckCount() int
- func (pbx *FakePBX) Addr() string
- func (pbx *FakePBX) AutoAnswer(sdp []byte)
- func (pbx *FakePBX) AutoBusy()
- func (pbx *FakePBX) AutoReject(code int, reason string)
- func (pbx *FakePBX) ByeCount() int
- func (pbx *FakePBX) CancelCount() int
- func (pbx *FakePBX) InfoCount() int
- func (pbx *FakePBX) InviteCount() int
- func (pbx *FakePBX) LastInvite() *sip.Request
- func (pbx *FakePBX) LastRegister() *sip.Request
- func (pbx *FakePBX) MessageCount() int
- func (pbx *FakePBX) OnAck(h func(*Ack))
- func (pbx *FakePBX) OnBye(h func(*Bye))
- func (pbx *FakePBX) OnCancel(h func(*Cancel))
- func (pbx *FakePBX) OnInfo(h func(*Info))
- func (pbx *FakePBX) OnInvite(h func(*Invite))
- func (pbx *FakePBX) OnMessage(h func(*Message))
- func (pbx *FakePBX) OnOptions(h func(*Options))
- func (pbx *FakePBX) OnRefer(h func(*Refer))
- func (pbx *FakePBX) OnRegister(h func(*Register))
- func (pbx *FakePBX) OnSubscribe(h func(*Subscribe))
- func (pbx *FakePBX) OptionsCount() int
- func (pbx *FakePBX) ReferCount() int
- func (pbx *FakePBX) RegisterCount() int
- func (pbx *FakePBX) Requests(method sip.RequestMethod) []RecordedRequest
- func (pbx *FakePBX) SIPAddr() string
- func (pbx *FakePBX) SendInvite(ctx context.Context, target string, sdp []byte) (*OutboundCall, error)
- func (pbx *FakePBX) SendMessage(ctx context.Context, target string, contentType string, body []byte) error
- func (pbx *FakePBX) SendOptions(ctx context.Context, target string) (*sip.Response, error)
- func (pbx *FakePBX) SubscribeCount() int
- func (pbx *FakePBX) URI(extension string) string
- func (pbx *FakePBX) WaitForAck(n int, timeout time.Duration) bool
- func (pbx *FakePBX) WaitForBye(n int, timeout time.Duration) bool
- func (pbx *FakePBX) WaitForCancel(n int, timeout time.Duration) bool
- func (pbx *FakePBX) WaitForInvite(n int, timeout time.Duration) bool
- func (pbx *FakePBX) WaitForRegister(n int, timeout time.Duration) bool
- type Info
- type Invite
- func (inv *Invite) Answer(sdp []byte) *ActiveCall
- func (inv *Invite) AnswerWithCode(code int, sdp []byte) *ActiveCall
- func (inv *Invite) EarlyMedia(sdp []byte)
- func (inv *Invite) From() string
- func (inv *Invite) Reject(code int, reason string)
- func (inv *Invite) Request() *sip.Request
- func (inv *Invite) Respond(code int, reason string, hdrs ...sip.Header)
- func (inv *Invite) Ringing()
- func (inv *Invite) SDP() []byte
- func (inv *Invite) To() string
- func (inv *Invite) Trying()
- func (inv *Invite) WaitForCancel(timeout time.Duration) bool
- type Message
- type Option
- type Options
- type OutboundCall
- func (c *OutboundCall) Request() *sip.Request
- func (c *OutboundCall) Response() *sip.Response
- func (c *OutboundCall) SendBye(ctx context.Context) error
- func (c *OutboundCall) SendNotify(ctx context.Context, eventType, body string) error
- func (c *OutboundCall) SendReInvite(ctx context.Context, sdp []byte) error
- func (c *OutboundCall) SendRefer(ctx context.Context, referTo string) error
- type RecordedRequest
- type Refer
- type Register
- type Subscribe
Constants ¶
This section is empty.
Variables ¶
var ( PCMU = Codec{PayloadType: 0, Name: "PCMU", ClockRate: 8000} PCMA = Codec{PayloadType: 8, Name: "PCMA", ClockRate: 8000} G722 = Codec{PayloadType: 9, Name: "G722", ClockRate: 8000} )
Common codecs.
Functions ¶
Types ¶
type Ack ¶
type Ack struct {
// contains filtered or unexported fields
}
Ack is the handle passed to OnAck handlers.
type ActiveCall ¶
type ActiveCall struct {
// contains filtered or unexported fields
}
ActiveCall is returned by Invite.Answer. It lets tests simulate PBX-side mid-call actions (BYE, re-INVITE, NOTIFY).
func (*ActiveCall) SendNotify ¶
SendNotify sends a NOTIFY within the dialog (e.g., transfer status after REFER).
func (*ActiveCall) SendReInvite ¶
SendReInvite sends a re-INVITE with new SDP (hold, codec change, etc.).
type Bye ¶
type Bye struct {
// contains filtered or unexported fields
}
Bye is the handle passed to OnBye handlers.
type Cancel ¶
type Cancel struct {
// contains filtered or unexported fields
}
Cancel is the handle passed to OnCancel handlers.
Cancel handlers are notification-only: the SIP stack automatically sends 200 OK to the CANCEL and 487 Request Terminated to the original INVITE. The handler lets tests observe that cancellation occurred but cannot influence the response.
type FakePBX ¶
type FakePBX struct {
// contains filtered or unexported fields
}
FakePBX is an in-process SIP server for testing.
func NewFakePBX ¶
NewFakePBX creates and starts a FakePBX on 127.0.0.1:0 (UDP). The server is stopped automatically via t.Cleanup.
func (*FakePBX) AutoAnswer ¶
AutoAnswer makes the PBX answer all INVITEs with: 100 -> 180 -> 200 OK + SDP.
func (*FakePBX) AutoBusy ¶
func (pbx *FakePBX) AutoBusy()
AutoBusy makes the PBX reject all INVITEs with: 100 -> 486 Busy Here.
func (*FakePBX) AutoReject ¶
AutoReject makes the PBX reject all INVITEs with the given code and reason.
func (*FakePBX) CancelCount ¶
CancelCount returns the number of CANCEL requests received.
func (*FakePBX) InviteCount ¶
InviteCount returns the number of INVITE requests received.
func (*FakePBX) LastInvite ¶
LastInvite returns the most recent INVITE request, or nil.
func (*FakePBX) LastRegister ¶
LastRegister returns the most recent REGISTER request, or nil.
func (*FakePBX) MessageCount ¶
MessageCount returns the number of MESSAGE requests received.
func (*FakePBX) OnRegister ¶
OnRegister sets the handler for incoming REGISTER requests.
func (*FakePBX) OnSubscribe ¶
OnSubscribe sets the handler for incoming SUBSCRIBE requests.
func (*FakePBX) OptionsCount ¶
OptionsCount returns the number of OPTIONS requests received.
func (*FakePBX) ReferCount ¶
ReferCount returns the number of REFER requests received.
func (*FakePBX) RegisterCount ¶
RegisterCount returns the number of REGISTER requests received.
func (*FakePBX) Requests ¶
func (pbx *FakePBX) Requests(method sip.RequestMethod) []RecordedRequest
Requests returns all recorded requests of the given SIP method.
func (*FakePBX) SendInvite ¶ added in v0.2.0
func (pbx *FakePBX) SendInvite(ctx context.Context, target string, sdp []byte) (*OutboundCall, error)
SendInvite initiates an outbound call from the PBX to the given SIP URI. It sends an INVITE with the provided SDP, collects responses, and on 2xx sends ACK automatically. Returns an OutboundCall for mid-call control, or an error if the call was rejected or failed.
func (*FakePBX) SendMessage ¶ added in v0.2.0
func (pbx *FakePBX) SendMessage(ctx context.Context, target string, contentType string, body []byte) error
SendMessage sends an out-of-dialog SIP MESSAGE to the given target URI.
func (*FakePBX) SendOptions ¶ added in v0.2.0
SendOptions sends an out-of-dialog SIP OPTIONS to the given target URI. Returns the response so callers can inspect capabilities (Allow, Supported, etc.).
func (*FakePBX) SubscribeCount ¶
SubscribeCount returns the number of SUBSCRIBE requests received.
func (*FakePBX) WaitForAck ¶
WaitForAck blocks until at least n ACKs are received or timeout elapses.
func (*FakePBX) WaitForBye ¶
WaitForBye blocks until at least n BYEs are received or timeout elapses.
func (*FakePBX) WaitForCancel ¶
WaitForCancel blocks until at least n CANCELs are received or timeout elapses.
func (*FakePBX) WaitForInvite ¶
WaitForInvite blocks until at least n INVITEs are received or timeout elapses.
type Info ¶
type Info struct {
// contains filtered or unexported fields
}
Info is the handle passed to OnInfo handlers.
type Invite ¶
type Invite struct {
// contains filtered or unexported fields
}
Invite is the handle passed to OnInvite handlers. It controls each step of call setup.
func (*Invite) Answer ¶
func (inv *Invite) Answer(sdp []byte) *ActiveCall
Answer sends a 200 OK with SDP and returns an ActiveCall handle. Must be called at most once per Invite.
func (*Invite) AnswerWithCode ¶
func (inv *Invite) AnswerWithCode(code int, sdp []byte) *ActiveCall
AnswerWithCode sends a 2xx response with SDP. For non-200 success codes.
func (*Invite) EarlyMedia ¶
EarlyMedia sends 183 Session Progress with SDP body.
func (*Invite) Respond ¶
Respond sends a SIP response with the given status code, reason, and optional headers. For provisional responses (1xx), this can be called multiple times. For final responses (>=200), this is guarded by sync.Once — only the first final response (via Respond, Answer, or Reject) takes effect.
type Message ¶
type Message struct {
// contains filtered or unexported fields
}
Message is the handle passed to OnMessage handlers.
type Option ¶
type Option func(*config)
Option configures FakePBX.
func WithAuth ¶
WithAuth sets digest auth credentials the PBX expects. If not set, REGISTER is accepted unconditionally.
func WithTransport ¶
WithTransport sets the SIP transport. Default: "udp".
func WithUserAgent ¶
WithUserAgent sets the User-Agent header. Default: "FakePBX/test".
type Options ¶
type Options struct {
// contains filtered or unexported fields
}
Options is the handle passed to OnOptions handlers.
type OutboundCall ¶ added in v0.2.0
type OutboundCall struct {
// contains filtered or unexported fields
}
OutboundCall represents a call initiated by the PBX (UAC side). It is returned by FakePBX.SendInvite when the remote answers with 2xx.
func (*OutboundCall) Request ¶ added in v0.2.0
func (c *OutboundCall) Request() *sip.Request
Request returns the INVITE request that was sent.
func (*OutboundCall) Response ¶ added in v0.2.0
func (c *OutboundCall) Response() *sip.Response
Response returns the 2xx response received from the remote.
func (*OutboundCall) SendNotify ¶ added in v0.2.0
SendNotify sends a NOTIFY within the dialog (e.g., transfer status after REFER).
func (*OutboundCall) SendReInvite ¶ added in v0.2.0
SendReInvite sends a re-INVITE with new SDP (hold, codec change, etc.).
type RecordedRequest ¶
RecordedRequest holds a captured SIP request with timestamp.
type Refer ¶
type Refer struct {
// contains filtered or unexported fields
}
Refer is the handle passed to OnRefer handlers.
func (*Refer) ReferTo ¶
ReferTo returns the value of the Refer-To header. Angle brackets are stripped if present.
type Register ¶
type Register struct {
// contains filtered or unexported fields
}
Register is the handle passed to OnRegister handlers.