Gossipper build

gossipper-build — SIP Scenario Authoring

Author valid Gossipper XML scenarios. Pinned to Gossipper 0.1.60-rtcpmuxpatch2 (sipcapture/gossipper on main, audited 2026-05-18).

When to use this skill

• Write a new XML scenario for a specific SIP call flow.
• Modify an existing scenario.
• Port a SIPp scenario to Gossipper.
• Answer "is feature X supported / how do I express Y in Gossipper XML?"

When NOT to use this skill

Task	Owner
Invoking gossipper, picking transport/rate, deployment	gossipper-run
Interpreting summary JSON / trace CSVs / call records	gossipper-analyze
Authoring the 3PCC peer file (CSV name;host:port)	gossipper-run (deployment artifact)
Running gossipper pcap2scenario to convert a PCAP	gossipper-run

If the user hands you a PCAP and asks for an XML scenario, the right move is: have gossipper-run invoke pcap2scenario first, then this skill cleans up the produced XML.

Authoring workflow

1. Clarify intent: UAC vs UAS (vs 3PCC). Sequence, expected response codes, auth requirements, media expectations, branching, retries.
2. Check built-ins first. If a -sn <name> covers the case, no XML is needed. See the built-ins table below.
3. Pick the closest file in examples/ as a starting point.
4. Declare any needed <Global> and <User> variables up front.
5. Write SIP flows inside <![CDATA[ ... ]]>. Use keywords liberally.
6. Add rtd="name" / start_rtd="name" on the steps that matter for latency measurement.
7. Add counter="name" on steps that should aggregate into summary JSON.
8. Add the top-of-file comment block (see "Output contract" below).
9. Validate XML well-formedness (see "Validation").
10. Hand off to gossipper-run with: scenario path, optional injection CSV path, intended role, required runtime vars.

Built-in scenarios (no XML needed)

-sn <name>	Role	Behavior
uac (default)	client	INVITE → 200 → ACK → BYE
uas	server	UAS answering INVITE → 180 → 200, BYE handler
management	server	UAS with HTTP API + hot-reload
invite_media	client	INVITE with RTP media
invite_media_early	client	Early media via 183 + SDP
invite_media_early_180	client	Early media variant signaled with 180

Built-ins are hard-coded — they cannot be PUT via /api/v1/scenario. To override the shape, write a custom XML.

File skeleton

<?xml version="1.0" encoding="UTF-8" ?>
<!--
  Scenario: <name>
  Role: <UAC | UAS | 3PCC-master | 3PCC-slave>
  Intent: <one-paragraph description of what this scenario tests>
  Partial-support features used: <list, or "none">
  Required runtime vars: <list, or "none">
-->
<scenario name="descriptive-name">
  <Global variables="g1,g2"/>
  <User variables="u1,u2"/>

  <init>
    <!-- pre-call setup if needed -->
  </init>

  <send retrans="500"><![CDATA[
    INVITE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
    ...
    Content-Length: [len]

  ]]></send>

  <recv response="100" optional="true"/>
  <recv response="180" optional="true"/>
  <recv response="200" rtd="invite"/>

  <!-- ... -->

  <timewait milliseconds="4000"/>
</scenario>

Top-level commands

Command	Purpose
<send>	Emit a SIP message. UDP retrans via retrans="<ms>".
<recv>	Expect a SIP message. request="METHOD" OR response="N".
<pause>	Wait. milliseconds="N", optional distribution.
<nop>	No-op container for actions / branching.
<label>	Jump target. id="name".
<timewait>	Post-call linger.
<sendCmd> / <recvCmd>	3PCC peer coordination.
<init>	Pre-call setup block.

Full attribute reference (timers, counters, branching, auth=true, rrs=true, etc.) and the action catalog → references/xml-reference.md.

Always-remember gotchas

These bite on first authoring. Burn them in.

1. Every SIP body lives in <![CDATA[ ... ]]>. Bare <, >, & in SDP otherwise break XML parsing.
2. Every message with a body needs Content-Length: [len]. Missing it doesn't fail loudly — peers parse oddly.
3. retrans="<ms>" is UDP-only. Silently ignored on TCP/TLS.
4. Line endings: author with \n. Gossipper inserts \r\n on the wire.
5. [tdmmap] is a stub — always renders 0.0.0/0. Don't use it.
6. setdest works only on u1 / ui / server-UDP. Don't author dynamic destination switching for TCP/TLS scenarios — split into multiple scenarios instead.
7. -t s1 / sn are UDP aliases, not TLS despite the "s" prefix. TLS server modes are l1 / sl. Affects what the scenario can rely on at runtime.

Full partial-support inventory (lookup, exec command, rtpcheck, sample, insert, replace, video/image PCAP forwarding) → references/xml-reference.md.

Going deeper

Read these on demand:

• references/xml-reference.md — full commands and attributes, full action catalog with support status, full keyword/template vocabulary, variable scopes, transport mode authoring constraints, comprehensive gotchas.
• references/patterns.md — specialized authoring patterns:
  • Auth: UAC handling 401/407, UAS validating digest via verifyauth, TLS mutual auth (runtime-controlled).
  • 3PCC: master entry, slave entry, init-block coordination, Call-ID adoption rules.
  • Media/RTP: codec table, stream sources, DTMF, recording, SRTP/ICE caveats.

Canonical examples (start by copying one)

Intent	Example file
Vanilla UAC: INVITE → 200 → ACK → BYE	examples/uac_basic.xml
REGISTER with digest 401/407 challenge	examples/uac_register_with_auth.xml
Simple UAS answering INVITE → BYE	examples/uas_basic.xml
UAC with RTP audio stream attached	examples/uac_invite_with_media.xml
3PCC master entry pattern	examples/3pcc_master.xml
3PCC slave entry (first step recvCmd)	examples/3pcc_slave.xml

These are educational reference scenarios. The authoritative example corpus lives in gossipper's testdata/scenarios/ directory at the pinned version — point users there when they want every variant.

Validation

Required before handing off: XML must be well-formed.

python3 -c "import xml.etree.ElementTree as ET; ET.parse('scenario.xml'); print('OK')"

This catches CDATA misuse, attribute typos, unclosed tags. It does NOT validate Gossipper-specific semantics (e.g., that setdest is only used in compatible transport modes) — those failures surface at runtime with classification scenario_error.

Optional (gossipper-run's job): loopback smoke run. gossipper -sf scenario.xml -sn uas on the same host validates that the scenario parses through gossipper's stricter XML loader.

Output contract

Every scenario produced by this skill includes:

1. Top-of-file XML comment with: name, role, one-paragraph intent, list of partial-support features used (or "none"), required runtime vars (or "none").
2. Explicit Content-Length: [len] on every message with a body.
3. CDATA-wrapped SIP message bodies.
4. No [tdmmap] and no setdest outside u1 / ui / server-UDP.
5. Well-formed XML — passes the validation command above.

Handoff to gossipper-run

When done, hand over:

Item	Why run needs it
Scenario file path(s)	-sf flag
Companion injection CSV path(s), if any	-inf flag
Intended role (UAC / UAS / 3PCC-master / 3PCC-slave)	Picks transport mode, bind, peer file
Required template vars	Maps to -s / -au / -ap / -sip_from / etc.
Partial-support features used	Run-skill may warn or adjust flags