refactor(contact_player.py): part3: Introduction of a new data model and addition of some level of abstraction

[axodentally]

This PR is a big one with major changes to the code structure.

The contact plan parsing is now done in two steps: first basic parsing into RawCcpContacts and RawCcpContactPlan, which only facilitates the pure parsing of a ccp file.

The second step is converting the raw ccp representation to an abstracted version. The reason being, in the raw ccp file a source node can be a Node name or id and the destination either name, id or the name of a network interface on the source node, that leads to the destination.
That fact makes working with such a contact really hard because every time a function wants to do something in relation to a contact, it needs to account for those different possibilities.
Therefor, the RawCcpContactPlan is converted into a ContactPlan consisting of of Contacts, that now are defined by a source and destination Node, the Network name that connects both and the remaining contact properties.

Besides that, a new scenario.py files handles the parsing of the docker-compose.yml file and importantly owning the definition of the Node class

These introductions then make the logic in the contact_player much simpler, even allowing for a reduction in total lines of code.

For further details have a look at the individual commit messages.

[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 mermaid diagram and summary of changes, which I checked are both correct.

flowchart TD
    subgraph scenario["scenario.py"]
        Node["Node\n{name, id, eid,\ninterfaces}"]
        NetworkInterface["NetworkInterface\n{ip, dev}"]
        Node -->|"1..N"| NetworkInterface
    end

    subgraph ccp["ccp.py"]
        LinkProperties["LinkProperties\n{bandwidth, loss,\ndelay, jitter}"]
        RawCcpContact["RawCcpContact\n{src, dst, begin, end,\nprops, symmetric}"]
        RawCcpContactPlan["RawCcpContactPlan\n{contacts, fixed_contacts,\nloop}"]
        Contact["Contact\n{src: Node, dst: Node,\nnetwork, begin, end, props}"]
        ContactPlan["ContactPlan\n{contacts: dict[Contact,\nContactState], loop}"]

        RawCcpContact -->|"props"| LinkProperties
        RawCcpContactPlan -->|"contains list of"| RawCcpContact
    end

    subgraph player["contact_player.py"]
        ContactPlayer["ContactPlayer\n{plan, nodes,\nscenario_path, netmap_path}"]
    end

    RawCcpContact -->|"resolve + expand\nsymmetric"| Contact
    Contact -->|"src, dst"| Node
    Contact -->|"props"| LinkProperties
    ContactPlan -->|"from_ccp_file()\nwraps"| Contact
    ContactPlayer -->|"holds"| ContactPlan
    ContactPlayer -->|"holds"| Node

Loading

Rationale:

• Core refactor: CoreContact/CoreContactPlan split into a 2-stage pipeline — raw parsing (RawCcpContact/RawCcpContactPlan) then resolution into Contact/ContactPlan with real Node references instead of string tuples.
• Fixed + dynamic contacts unified: both now flow through the same Contact dict in ContactPlan, differentiated only by end=-1 for fixed links.
• Node promoted to a first-class dataclass (from TypedDict), with NetworkInterface carrying both IP and discovered device name.
• ContactPlayer is the new orchestrator that holds the resolved plan and node map, replacing the old procedural main().
• LinkProperties extracted as a shared value object used by both raw and resolved contacts.