feat(contact_player): initial planned_contacts support

[axodentally]

Rationale

The CCSDS reference scenarios make a destinction between planned contacts and actual contacts. The planned contacts are those, that should theoretically happen between two nodes, based on their orbital properties.

The actual contacts are a subset of those, removing some of the planned contact entries to simulate unforseen events, that made it not possible to establish a connection.

This allows to test the behavior of software, when it is believed to have contact to a peer, but the data will never arrive.

Therefor, nse2 should enable/disable contacts based on the actual_contacts.csv contact plan. But then, software inside each node should be informed about changes to contacts based on the believed planned_contacts.csv contact plan.

Implementation

This PR implements this feature, by allowing the contact_player class to own more than one contact plans (here: actually ContactHandler, that then own a ContactPlan). The player owns the timing loop and waits for upcoming events in the plans. When an event happens at a given time (i.e. a contact changes state from active->inactive), the player calls the process_time(self, time:int) -> None function on all ContactHandlers, that then independently decide what do to at that time.

And here, the TcNetemContactHandler, which applies the actual contact changes to the docker interfaces and inherits from ContactHandler abstract base class, executes its tc-netem commands on the network interfaces.
While the CommandContactHandler executes a user-specified script or command for each event, with environment variables giving the needed context (like the type of event, being setup, cleanup, activate or deactivate and contact information like source and destination node, properties, etc)

That way, the python implementation remains modular for future usecases and changes. While the usage of a user-defined script/command gives users the broadest possible freedom to react to events in their nodes, without needing to change any python code. The script is just added or mounted to each node in the docker image/container, possibly even different scripts for different nodes.

[axodentally]

This change is part of the following stack:

• refactor(contact_player.py): part1: basic refactoring, move functionality to main() function #20
  • refactor(contact_player.py): part2: improve type hints, add docstrings #21
    • refactor(contact_player.py): part3: Introduction of a new data model and addition of some level of abstraction #22
      • feat(contact_player): initial planned_contacts support #23 ◀
        • tests: add unittests #24
          • Introduce pyproject.toml, restructure installation #25

_{Change managed by git-spice.}

[axodentally]

AI generated flowchart, with a simplified view of the new model. Irrelevant parts like RawContactPlan and the scenario.py file are left out for simplicity.

flowchart TD
    %% ── Domain model (unchanged) ──
    subgraph ccp["ccp.py"]
        LinkProperties["LinkProperties\n{bandwidth, loss,\ndelay, jitter}"]
        Contact["Contact\n{src: Node, dst: Node,\nnetwork, begin, end, props}"]
        ContactPlan["ContactPlan\n{contacts: dict[Contact,\nContactState], loop}"]
    end

    subgraph player["contact_player.py"]
        ContactHandler["ContactHandler\n(ABC)\n{plan, nodes}"]
        TcNetemHandler["TcNetemContactHandler\n{plan, nodes}\nApplies tc/netem to\nDocker interfaces"]
        CommandHandler["CommandContactHandler\n{plan, nodes, command}\nRuns user script in\nsource container"]

        ContactPlayer["ContactPlayer\n{handlers: list[ContactHandler],\nscenario_path, netmap_path}"]
    end

    %% ── Relationships ──
    Contact -->|"props"| LinkProperties
    ContactPlan -->|"from_ccp_file()\nwraps"| Contact
    
    TcNetemHandler -->|"inherits from"| ContactHandler
    CommandHandler -->|"inherits from"| ContactHandler
    
    ContactHandler-->|"holds"| ContactPlan
    
    ContactPlayer -->|"owns list of"| ContactHandler

Loading

Rationale:

• ContactHandler Abstract Base Class introduced as a base class, allowing multiple child classes with different contact plans to apply side effects in parallel.
• TcNetemContactHandler(ContactHandler) handles the "actual" contacts — applies tc/netem commands to Docker interfaces to simulate link properties (what ContactPlayer used to do directly).
• CommandContactHandler(ContactHandler) handles the "planned" contacts — executes a user-defined command inside the source container for each contact event, passing metadata via environment variables.
• ContactPlayer now owns a list of handlers instead of a single plan, driving the timing loop and delegating contact-specific effects to each handler's process_time(time) method.
• run_in_container extended to support environment variables, enabling the command handler to pass contact context to user scripts.

[sylvesterkaczmarek]

TcNetemContactHandler.setup() no longer deduplicates by source interface: unique_contact_links includes the destination, so multiple contacts over the same network can generate duplicate parallel tc qdisc add commands for the same device. Please deduplicate the tc setup/cleanup paths by (src, interface) and add a multi-peer/same-network regression test.