testprotocols 0.1.0__py3-none-any.whl

testprotocols/sip_phone.py

@@ -0,0 +1,230 @@
+"""Voice / SipPhone template.
+
+Defines the abstract contract for SIP phone operations including call
+state management, dialling, and feature codes.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SipPhone(Protocol):
+    """Abstract contract for SIP phone operations."""
+
+    def phone_start(self) -> None:
+        """Start the SIP phone software."""
+        ...
+
+    def phone_config(self, ipv6_flag: bool, sipserver_fqdn: str = "") -> None:
+        """Configure the SIP phone with the given server FQDN and IP-version flag."""
+        ...
+
+    def phone_kill(self) -> None:
+        """Terminate the SIP phone software."""
+        ...
+
+    def on_hook(self) -> None:
+        """Place the phone on-hook (hang up)."""
+        ...
+
+    def off_hook(self) -> None:
+        """Take the phone off-hook."""
+        ...
+
+    def answer(self) -> bool:
+        """Answer an incoming call.  Returns True if successful."""
+        ...
+
+    def dial(self, sequence: str) -> None:
+        """Dial a DTMF *sequence*."""
+        ...
+
+    def is_idle(self) -> bool:
+        """Return True if the phone is in the idle state."""
+        ...
+
+    def is_dialing(self) -> bool:
+        """Return True if the phone is currently dialling."""
+        ...
+
+    def is_incall_dialing(self) -> bool:
+        """Return True if the phone is dialling while connected to an existing call
+        (e.g. entering a transfer target during hold).
+        """
+        ...
+
+    def is_ringing(self) -> bool:
+        """Return True if the phone is ringing."""
+        ...
+
+    def is_connected(self) -> bool:
+        """Return True if the phone has an active call connection."""
+        ...
+
+    def is_incall_connected(self) -> bool:
+        """Return True if the phone has an in-progress second leg connected during a
+        transfer or consultation.
+        """
+        ...
+
+    def is_onhold(self) -> bool:
+        """Return True if the current primary call is in a hold
+        (re-INVITE sendonly / inactive) state.
+        """
+        ...
+
+    def is_playing_dialtone(self) -> bool:
+        """Return True if the phone is currently playing a dial tone."""
+        ...
+
+    def is_incall_playing_dialtone(self) -> bool:
+        """Return True if the phone is emitting a dial tone during an in-call consultation."""
+        ...
+
+    def is_call_ended(self) -> bool:
+        """Return True if the last call has ended."""
+        ...
+
+    def is_code_ended(self) -> bool:
+        """Return True if the last feature-code dial sequence has finished
+        (no more DTMF digits will be sent).
+        """
+        ...
+
+    def is_call_waiting(self) -> bool:
+        """Return True if a second incoming call is currently waiting while the
+        primary call is connected.
+        """
+        ...
+
+    def is_in_conference(self) -> bool:
+        """Return True if this phone is currently a participant in a three-way or
+        larger conference bridge.
+        """
+        ...
+
+    def has_off_hook_warning(self) -> bool:
+        """Return True if the phone is playing an off-hook warning tone
+        (handset left off-hook without dialling).
+        """
+        ...
+
+    def detect_dialtone(self) -> bool:
+        """Return True if a dial tone is detected on the line."""
+        ...
+
+    def is_line_busy(self) -> bool:
+        """Return True if the line is busy."""
+        ...
+
+    def reply_with_code(self, code: int) -> None:
+        """Reply to an incoming call or event with the given SIP response *code*."""
+        ...
+
+    def is_call_not_answered(self) -> bool:
+        """Return True if the outgoing call was not answered."""
+        ...
+
+    def answer_waiting_call(self) -> None:
+        """Answer the waiting call and place the primary call on hold."""
+        ...
+
+    def toggle_call(self) -> None:
+        """Swap which call is active: place the currently-active call on hold and
+        resume the held call.
+        """
+        ...
+
+    def merge_two_calls(self) -> None:
+        """Merge the active and held calls into a single conference bridge."""
+        ...
+
+    def reject_waiting_call(self) -> None:
+        """Reject the waiting call with 486 Busy Here; the primary call remains connected."""
+        ...
+
+    def place_call_onhold(self) -> None:
+        """Place the active call on hold."""
+        ...
+
+    def place_call_offhold(self) -> None:
+        """Resume the held call."""
+        ...
+
+    def press_R_button(self) -> None:
+        """Press the R (recall/flash) button on the phone."""
+        ...
+
+    def hook_flash(self) -> None:
+        """Send a hook-flash signal."""
+        ...
+
+    def wait_for_state(self, state: str, timeout: int = 10) -> bool:
+        """Wait up to *timeout* seconds for the phone to reach *state*.
+
+        Returns True if the state was reached within the timeout.
+        """
+        ...
+
+    def press_buttons(self, buttons: str) -> None:
+        """Press the DTMF *buttons* sequence on the phone keypad."""
+        ...
+
+    # ------------------------------------------------------------------
+    # MWI / voicemail indicators (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def has_mwi_indicator(self) -> bool:
+        """Return True if the phone's MWI indicator (lamp/display) is active.
+
+        A conformant driver observes the phone's SIP NOTIFY stream for
+        ``message-summary`` events and exposes the current waiting flag here.
+        """
+        ...
+
+    def check_voicemail(self) -> None:
+        """Dial the voicemail-access feature code (e.g. ``*97``)."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Presence (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def is_away(self) -> bool:
+        """Return True if the phone is currently in an away/unavailable presence state."""
+        ...
+
+    def set_presence(self, status: str) -> None:
+        """Publish the local presence *status* for this phone.
+
+        Typical values: ``"online"``, ``"busy"``, ``"away"``, ``"offline"``.
+        Implementers emit a SIP PUBLISH with a ``presence`` event package.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Offline SIP MESSAGE (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def has_pending_offline_message(self) -> bool:
+        """Return True if a stored-while-offline SIP MESSAGE is pending delivery.
+
+        Expected to flip True after a REGISTER that flushes msilo-stored
+        messages, and back to False once the UA has acknowledged them.
+        """
+        ...
+
+
+@runtime_checkable
+class SipPhoneWhiteBox(SipPhone, Protocol):
+    """Deep introspection capabilities for SIP phones."""
+
+    def has_rtp_udp_bindings(self) -> bool:
+        """Return True if the underlying OS has active UDP sockets in the RTP port range.
+
+        This is a diagnostic white-box check, typically used when testing in
+        --null-audio simulated environments where real media analysis is impossible.
+        """
+        ...

testprotocols/sip_server.py

@@ -0,0 +1,205 @@
+"""Voice / SipServer template.
+
+Defines the abstract contract for SIP server operations including user
+management, call tracking and SIP message verification.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SipServer(Protocol):
+    """Abstract contract for SIP server operations."""
+
+    # ------------------------------------------------------------------
+    # Abstract properties
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        """Human-readable name of this SIP server instance."""
+        ...
+
+    @property
+    def ipv4_addr(self) -> str | None:
+        """IPv4 address of the SIP server, or None if not configured."""
+        ...
+
+    @property
+    def ipv6_addr(self) -> str | None:
+        """IPv6 address of the SIP server, or None if not configured."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Abstract methods
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the SIP server process."""
+        ...
+
+    def stop(self) -> None:
+        """Stop the SIP server process."""
+        ...
+
+    def restart(self) -> None:
+        """Restart the SIP server process."""
+        ...
+
+    def get_status(self) -> str:
+        """Return a string describing the current SIP server status."""
+        ...
+
+    def get_online_users(self) -> str:
+        """Return a string listing currently registered/online SIP users."""
+        ...
+
+    def add_user(self, user: str, password: str | None = None) -> None:
+        """Add a SIP *user* account, optionally with a *password*."""
+        ...
+
+    def remove_endpoint(self, endpoint: str) -> None:
+        """Remove the SIP *endpoint* (user or device) from the server."""
+        ...
+
+    def allocate_number(self, number: str | None = None) -> str:
+        """Allocate a DID *number* on the server and return the allocated number."""
+        ...
+
+    def get_expire_timer(self) -> int:
+        """Return the current SIP registration expire timer value (seconds)."""
+        ...
+
+    def set_expire_timer(self, to_timer: int = 60) -> None:
+        """Set the SIP registration expire timer to *to_timer* seconds."""
+        ...
+
+    def get_active_calls(self) -> int:
+        """Return the exact number of currently active dialogs on the server.
+
+        Implementations MUST use a dialog-module backed query (e.g. kamailio
+        ``kamcmd dlg.stats_active``). The pre-v0.2.0 "best-effort heuristic"
+        based on counting registered contacts is no longer acceptable;
+        a driver paired with a v1.3.0+ sipcenter image has access to real
+        dialog state and must use it.
+        """
+        ...
+
+    def get_rtpengine_stats(self) -> dict[str, Any]:
+        """Return RTPEngine statistics as a dictionary."""
+        ...
+
+    def verify_sip_message(
+        self,
+        message_type: str,
+        since: Any = None,
+        timeout: int = 5,
+    ) -> bool:
+        """Verify that a SIP message of *message_type* was received.
+
+        Implementations MUST consult an authoritative log channel (e.g.
+        the sipcenter's ``/var/log/kamailio/kamailio.log`` written by
+        rsyslog, or the merged testbed log at ``raikou/logs/sip-testbed.log``).
+        The pre-v0.2.0 ``journalctl``-based probe is dead — the image does
+        not run systemd — and any driver still relying on it must switch
+        to the authoritative file path.
+
+        Parameters
+        ----------
+        message_type:
+            The SIP method (``INVITE``, ``MESSAGE``, ``NOTIFY``, ...) or
+            response code (``200``, ``486``, ...) to match.
+        since:
+            Optional timestamp or marker; only messages after this point
+            are considered.
+        timeout:
+            Seconds to wait for the expected message.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Voicemail (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def get_voicemail_count(self, user: str) -> int:
+        """Return the number of unheard voicemail messages waiting for *user*.
+
+        Returns 0 if the user exists but has no messages. Raises when *user*
+        has no mailbox provisioned on the server.
+        """
+        ...
+
+    def clear_voicemail(self, user: str) -> None:
+        """Delete all voicemail messages (heard and unheard) for *user*."""
+        ...
+
+    # ------------------------------------------------------------------
+    # MWI — Message Waiting Indication (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def get_mwi_status(self, user: str) -> dict[str, Any]:
+        """Return the current MWI status for *user*.
+
+        Returns a dict with keys:
+            - ``waiting`` (bool): True if the waiting flag is set.
+            - ``new`` (int): count of new (unheard) messages.
+            - ``old`` (int): count of old (heard but retained) messages.
+        """
+        ...
+
+    def set_mwi_status(self, user: str, waiting: bool) -> None:
+        """Set the MWI waiting flag for *user*.
+
+        Implementers should emit a ``message-summary`` NOTIFY to any
+        subscribed UA so the phone's indicator updates immediately.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Presence (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def get_user_presence(self, user: str) -> str:
+        """Return the current presence status string for *user*.
+
+        Typical values: ``"online"``, ``"busy"``, ``"away"``, ``"offline"``.
+        Implementations may return provider-specific extensions.
+        """
+        ...
+
+    def subscribe_to_user(self, watcher: str, watched: str) -> None:
+        """Create a presence subscription from *watcher* to *watched*."""
+        ...
+
+    def notify_presence(self, user: str, status: str) -> None:
+        """Publish presence *status* for *user* to all current subscribers."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Offline SIP MESSAGE (v0.2.0+)
+    # ------------------------------------------------------------------
+
+    def send_offline_message(self, from_user: str, to_user: str, body: str) -> bool:
+        """Store a SIP MESSAGE from *from_user* to the offline *to_user*.
+
+        Returns True if the message was stored for later delivery. The
+        message is expected to flush on the next successful REGISTER from
+        *to_user*.
+        """
+        ...
+
+    def get_offline_messages(self, user: str) -> list[dict[str, Any]]:
+        """Return the list of pending offline messages addressed to *user*.
+
+        Each entry is a dict with keys:
+            - ``from`` (str): sender URI.
+            - ``body`` (str): message body.
+            - ``timestamp`` (str): ISO-8601 timestamp of when stored.
+        """
+        ...
+
+    def clear_offline_messages(self, user: str) -> None:
+        """Delete all pending offline messages addressed to *user*."""
+        ...

testprotocols/site_to_site_vpn.py

@@ -0,0 +1,61 @@
+"""Site-to-site VPN template — managed SD-WAN appliance.
+
+Defines the abstract contract for an appliance's participation in the
+site-to-site VPN overlay: its role (hub / spoke / disabled), the hubs a
+spoke connects to (including whether the default route points into the
+overlay), the local subnets advertised into the overlay, and a read of peer
+reachability.
+
+The configuration is one ``SiteToSiteVpnConfig`` read and replaced whole —
+role and hubs are semantically coupled (hubs are only meaningful for a
+spoke), and a managed appliance exposes overlay participation as a single
+configuration surface. "Point the default route into the overlay" is a
+config edit: get, flip ``use_default_route`` on a hub entry, set.
+
+Mapping pattern — relational role models: on some management planes the
+role is not stored on the device. Hub-ness exists only relationally (an
+edge *is* a hub because other sites' configs reference it), and the
+default-route intent is a backhaul designation rather than a per-hub flag.
+A driver for such a product synthesizes the role on read (referenced as
+hub anywhere → ``HUB``; overlay enabled with hub list → ``SPOKE``) and on
+write registers/dereferences the device in the relevant site configs. The
+round-trip is intent-preserving even where the stored shape differs.
+
+In scope: overlay participation (role, hubs + default route, subnets) and
+peer status.
+
+Out of scope: VPN-scoped firewall rules (see ``l3_firewall``), IPsec crypto
+parameters (no driving test; highly vendor-divergent — add on evidence),
+path steering across the overlay (see ``sdwan_policy_manager``), and
+third-party / non-overlay tunnels (add on evidence).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import SiteToSiteVpnConfig, VpnPeerStatus
+
+
+@runtime_checkable
+class SiteToSiteVpn(Protocol):
+    """Abstract contract for an appliance's site-to-site VPN overlay."""
+
+    def set_vpn_config(self, config: SiteToSiteVpnConfig) -> None:
+        """Replace the appliance's overlay participation with *config*.
+
+        The config is complete — role, hubs (spoke only, priority order),
+        and subnet advertisement — and replaces the previous state whole.
+        """
+        ...
+
+    def get_vpn_config(self) -> SiteToSiteVpnConfig:
+        """Return the current overlay-participation configuration."""
+        ...
+
+    def get_vpn_peers(self) -> list[VpnPeerStatus]:
+        """Return the observed status of every site-to-site VPN peer.
+
+        Empty list when the device participates in no overlay.
+        """
+        ...

testprotocols/snmp_client.py

@@ -0,0 +1,17 @@
+"""SNMP / Client template.
+
+Defines the abstract contract for SNMP client operations.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SnmpClient(Protocol):
+    """Abstract contract for SNMP client operations."""
+
+    def execute_snmp_command(self, snmp_command: str, timeout: int = 30) -> str:
+        """Execute an SNMP command and return the output string."""
+        ...

testprotocols/spanning_tree.py

@@ -0,0 +1,37 @@
+"""Spanning-tree configuration — global mode/priority + per-port guards."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.l2_common import StpMode, StpPortState
+from testprotocols.models.switch import StpPortConfig
+
+
+@runtime_checkable
+class SpanningTree(Protocol):
+    """Abstract contract for spanning-tree configuration and read."""
+
+    def set_mode(self, mode: StpMode) -> None:
+        """Set the global STP mode. RSTP-only products raise unsupported-capability on MSTP."""
+        ...
+
+    def get_mode(self) -> StpMode:
+        """Return the active STP mode."""
+        ...
+
+    def set_bridge_priority(self, priority: int) -> None:
+        """Set the bridge priority (0–61440, in steps of 4096 per IEEE 802.1D)."""
+        ...
+
+    def set_port_config(self, config: StpPortConfig) -> None:
+        """Apply per-port guard/edge/path-cost/priority for ``config.port``."""
+        ...
+
+    def get_port_config(self, port: str) -> StpPortConfig:
+        """Return the per-port STP configuration for *port*."""
+        ...
+
+    def get_port_state(self, port: str) -> StpPortState:
+        """Return the observed STP state for *port*."""
+        ...

testprotocols/static_routes.py

@@ -0,0 +1,47 @@
+"""Static-route template — WAN edge (twin and managed appliance).
+
+Defines the abstract contract for testbed-managed static routes: per-entry
+CRUD keyed by ``StaticRoute.name``, plus a config-view read-back. All
+reviewed management planes store static routes as individual objects, so the
+contract is per-entry CRUD — deliberately not the whole-list-replace shape
+used by the firewall/steering policies.
+
+``list_static_routes`` returns the *configured* entries (config view);
+the *operational* routing table (RIB) read stays on
+``router.Router.get_routing_table``.
+
+In scope: add/update, remove, and list testbed-managed static routes.
+
+Out of scope: RIB reads (see ``router``), dynamic routing — BGP — (deferred
+in GAPS.md), and policy-based routing / steering (see
+``sdwan_policy_manager``).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import StaticRoute
+
+
+@runtime_checkable
+class StaticRoutes(Protocol):
+    """Abstract contract for a WAN edge's testbed-managed static routes."""
+
+    def add_static_route(self, route: StaticRoute) -> None:
+        """Create the route, or update it in place if ``route.name`` exists.
+
+        Idempotent by name — repeating a call converges to the same state.
+        """
+        ...
+
+    def remove_static_route(self, name: str) -> None:
+        """Remove the route named *name*.
+
+        Raises KeyError if no route with that name exists.
+        """
+        ...
+
+    def list_static_routes(self) -> list[StaticRoute]:
+        """Return the configured static routes (config view, not the RIB)."""
+        ...

testprotocols/storm_control.py

@@ -0,0 +1,24 @@
+"""Per-port broadcast/multicast/unknown-unicast storm-control thresholds."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import StormControlConfig
+
+
+@runtime_checkable
+class StormControl(Protocol):
+    """Abstract contract for per-port storm control.
+
+    A product that exposes storm control only in a controller UI (no API) raises
+    unsupported-capability.
+    """
+
+    def set_config(self, config: StormControlConfig) -> None:
+        """Apply storm-control thresholds for ``config.port``."""
+        ...
+
+    def get_config(self, port: str) -> StormControlConfig:
+        """Return storm-control thresholds for *port*."""
+        ...

testprotocols/streaming_server.py

@@ -0,0 +1,32 @@
+"""Streaming origin (HLS/DASH) server template.
+
+Defines the abstract contract for content-origin servers used by
+streaming/QoE test scenarios. Implementations are responsible for
+ensuring named assets are present and serveable; richer surface
+(bitrate enumeration, log inspection, etc.) is intentionally deferred
+until a concrete testbed needs it.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StreamingServer(Protocol):
+    """Abstract contract for HLS/DASH content origins used in test scenarios."""
+
+    def ensure_content_available(self, video_id: str = "default") -> None:
+        """Ensure the named asset is present in the origin.
+
+        Idempotent: returns immediately if the asset is already seeded;
+        otherwise generates and uploads it. Raises if the operation fails.
+
+        Parameters
+        ----------
+        video_id:
+            Identifier of the asset to seed. Implementation decides how
+            this maps to actual content (bucket key, file path, stream
+            name, etc.).
+        """
+        ...

testprotocols/switch_acl.py

@@ -0,0 +1,29 @@
+"""Unified L2 + L3/L4 switch ACL — one ordered rule set per binding + direction.
+
+The reviewed switches use one ACL engine matching MAC/VLAN and IP 5-tuple
+fields, so this is one capability (not separate L2/L3 protocols). Rules reuse
+``RuleAction`` / ``RuleProtocol``; the record is ``SwitchAclRule``. Bindings are
+by port or VLAN, ingress or egress, applied as an ordered whole-list replace.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import AclDirection, SwitchAclRule
+
+
+@runtime_checkable
+class SwitchAcl(Protocol):
+    """Abstract contract for the switch ACL."""
+
+    def set_acl(
+        self, binding: str, direction: AclDirection, rules: list[SwitchAclRule]
+    ) -> None:
+        """Replace the ordered ACL bound to *binding* (a port or ``vlan:<id>``)
+        in *direction*."""
+        ...
+
+    def get_acl(self, binding: str, direction: AclDirection) -> list[SwitchAclRule]:
+        """Return the ordered ACL for *binding* / *direction*."""
+        ...