Report: Small changes

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "report/AUThReport"]
+	path = report/AUThReport
+	url = ssh://git@git.hoo2.net:222/hoo2/AUThReport.git

Mininet_DSL_Design.md

@@ -0,0 +1,885 @@
+# Mininet Topology JSON Language: Rationale and Reference
+
+## 1. Purpose and design rationale
+
+This document explains why the topology language has its current shape, then
+serves as a reference for its JSON fields, defaults, and semantic constraints.
+The starting point is the assignment: describe hosts, switches, a router, two
+subnets, and DHCP configuration in a form that can also express other valid
+topologies.
+
+### 1.1 Describe network intent
+
+The JSON describes the desired network and its configuration.
+A reader should be able to identify participants, connections, addresses, and
+services without tracing a sequence of Python or shell commands.
+This makes a topology easier to inspect and change independently of the code
+that constructs it.
+
+The design combines top-down modeling with bottom-up implementability.
+We start with the concepts needed to describe the network, while requiring each
+concept to have a clear translation into Mininet and Linux networking
+primitives.
+Nodes, interfaces, links, network-stack settings, and processes provide that
+translation without requiring a separate abstraction for every assignment step.
+
+This is why the language distinguishes a router from a host even though both
+can use similar underlying construction mechanisms.
+Their network roles differ, so the description expresses that distinction.
+Conversely, DHCP is a service on a node rather than a new kind of network node.
+
+### 1.2 Give each property a clear owner
+
+The network structure leads to five core entities:
+
+| Entity | Question it answers |
+| --- | --- |
+| Node | What participates in the network, and what role does it have? |
+| Interface | Where does a node attach, and how is that attachment configured? |
+| Link | Which two interfaces are connected? |
+| Node settings | How should the node's network stack behave? |
+| Service | Which service runs on a node, and where is it bound? |
+
+An interface belongs to its node because addressing, MAC, and MTU describe that
+node's attachment to the network.
+A link references two interfaces and owns connection properties such as delay
+or bandwidth.
+Keeping endpoint configuration out of links gives each property one clear
+place in the description.
+
+The same interface structure works for hosts, routers, and switches.
+An interface is an attachment point even when it has no IP address, which makes
+unaddressed switch ports natural to represent.
+Addressing is therefore optional, while MAC and MTU remain independent fields.
+
+### 1.3 Separate behavior from services
+
+Forwarding and reverse-path filtering describe network-stack behavior and
+belong in node settings.
+A DHCP server is a running service with its own configuration, so it belongs in
+`services`.
+This separation lets a node host a service without changing its node type.
+
+A service's `node` and `interface` fields describe its placement.
+Its `settings` describe its behavior, such as the DHCP address range and
+advertised gateway.
+Keeping placement outside service-specific settings preserves the same shape
+for future service types.
+
+### 1.4 Make identity explicit where it matters
+
+Logical interface tags such as `lan` and `wan` express the meaning of a
+connection without depending on generated operating-system interface names.
+Explicit tags let a topology identify a particular attachment point.
+The `auto` selector avoids unnecessary port naming when only connectivity
+matters, as is often the case for a switch.
+
+An omitted interface set allows automatic allocation as needed.
+An explicitly declared set defines the available ports, so automatic selection
+must stay within that set.
+This distinction preserves both convenience and the ability to express a fixed
+interface limit; an explicit empty set consequently means zero available ports.
+
+### 1.5 Describe configuration without recording runtime state
+
+Static addressing declares a known address and, optionally, a default gateway.
+DHCP addressing declares how configuration will be obtained; the acquired
+address and lease are runtime results.
+The language therefore does not require a DHCP client to contain an address
+that is not yet known.
+
+The same boundary excludes learned ARP entries, packet counters, captures, and
+experimental commands from the topology description.
+Those observations change as the network runs, while the declared topology
+continues to describe its configuration intent.
+
+### 1.6 Keep the language small and predictable
+
+The current assignment needs a static default gateway, rather than a general
+routing-policy language.
+It needs a DHCP service with an address range and an optional advertised
+gateway, rather than arbitrary daemon command lines.
+The chosen fields cover those requirements while leaving settings and services
+as clear places for future extensions.
+
+Unknown fields are rejected so a misspelled setting cannot silently change the
+meaning of a topology.
+The reference below defines the supported vocabulary and the constraints that
+make declarations consistent.
+It proceeds from the entity model through nodes, interfaces, links, and
+services, then collects the grammar and semantic rules before a complete
+example.
+
+For setup and usage, see the [README](README.md).
+Its [Architecture section](README.md#architecture) describes the Python
+processing pipeline, generated code, and execution behavior.
+
+---
+
+## 2. High-level entity model
+
+The current grammar is:
+
+```text
+Network
+├── Nodes
+│   ├── name
+│   ├── type
+│   ├── interfaces
+│   └── settings
+│
+├── Links
+│   ├── name?
+│   ├── endpoints
+│   │   ├── node
+│   │   └── interface
+│   └── settings
+│
+└── Services
+    ├── type
+    ├── node
+    ├── interface
+    └── settings
+```
+
+The actual JSON keys are lowercase: `nodes`, `links`, and `services`.
+Each top-level list may be omitted and defaults to an empty list.
+Node `interfaces` and node/link `settings` are optional.
+Service `settings` must contain the fields required by its type.
+
+The main entities intentionally have different responsibilities.
+
+```text
+Node
+    identifies a network participant
+
+Link
+    connects two network attachment points
+
+Service
+    represents a process or daemon running on a node
+```
+
+Common entities used in these entities are:
+
+```text
+Interface
+    identifies a network attachment point owned by a node
+        
+Settings
+    configure the node/link/service or its networking stack
+```
+
+---
+
+## 3. Nodes
+
+A node represents a logical network participant.
+
+The current structure is:
+
+```text
+Node
+├── name
+├── type
+├── interfaces
+└── settings
+```
+
+### 3.1 Node name
+
+`name` is the logical identifier used by the rest of the topology.
+
+For example:
+
+```json
+{
+  "name": "r0",
+  "type": "router"
+}
+```
+
+Node names are expected to be unique.
+
+Duplicate node names are invalid.
+
+### 3.2 Node type
+
+The currently supported node types are:
+
+```text
+host
+switch
+router
+```
+
+A `host` is an end system.
+A `switch` is an autonomous Layer-2 learning switch.
+A `router` connects IP networks and supports forwarding and reverse-path-filter
+settings.
+Selecting `router` does not implicitly enable forwarding.
+
+### 3.3 Node settings
+
+`settings` contains configuration that changes the behavior of the node itself.
+
+For a router, the currently supported settings are:
+
+```json
+"settings": {
+  "ip_forward": true,
+  "rp_filter": false
+}
+```
+
+These values configure the networking behavior of the node namespace.
+Omitted router settings leave the corresponding behavior unspecified.
+Hosts and switches currently accept only empty settings objects.
+
+They are not modeled as services because they do not represent independent
+user-space processes.
+
+The distinction is:
+
+```text
+Node settings
+    -> properties of the node or its networking stack
+
+Services
+    -> processes or daemons running on the node
+```
+
+Node settings are type-specific.
+
+Unknown settings for the selected node type are invalid.
+
+---
+
+## 4. Interfaces
+
+Interfaces belong to nodes.
+
+This is a deliberate modeling decision.
+
+```text
+Node owns Interfaces
+Link connects Interfaces
+```
+
+An interface is broader than an object that merely owns an IP address.
+
+It is a network attachment point with optional Layer-3 configuration and
+optional interface-level properties.
+
+Conceptually:
+
+```text
+Interface
+=
+network attachment point
++ optional L3 configuration
++ optional interface properties
+```
+
+A host or router interface will commonly have Layer-3 addressing.
+
+A Layer-2 switch port normally will not.
+
+Using one interface abstraction for all node types keeps link endpoints
+uniform.
+
+### 4.1 Logical interface tags
+
+Interfaces are declared as members of the `interfaces` object.
+
+The JSON key is the logical interface tag.
+
+For example:
+
+```json
+"interfaces": {
+  "lan": {
+    "addressing": "static",
+    "address": "192.168.1.1/24"
+  },
+  "wan": {
+    "addressing": "static",
+    "address": "192.168.2.1/24"
+  }
+}
+```
+
+`lan` and `wan` are topology-level identifiers.
+
+They are not required to be the real Linux interface names.
+
+Logical tags identify interfaces within the JSON independently of generated
+operating-system interface names.
+
+The same mechanism may be used for meaningful switch-port names.
+
+For example:
+
+```json
+"interfaces": {
+  "client1": {},
+  "client2": {},
+  "server": {},
+  "uplink": {}
+}
+```
+
+### 4.2 Interface properties
+
+The current interface structure is flat.
+
+There is no nested addressing object.
+
+The currently modeled properties are:
+
+```text
+addressing?     static | dhcp | none
+address?        required with static addressing
+gateway?        optional with static addressing
+mac?            optional interface property
+mtu?            optional interface property
+```
+
+Possible future interface properties can be added at the same level.
+
+### 4.3 Addressing semantics
+
+The supported addressing values are:
+
+```text
+static
+dhcp
+none
+```
+
+The `addressing` field is optional.
+
+Omitting it is semantically equivalent to:
+
+```json
+"addressing": "none"
+```
+
+Therefore these two declarations mean the same thing:
+
+```json
+"p1": {}
+```
+
+```json
+"p1": {
+  "addressing": "none"
+}
+```
+
+Both mean that no Layer-3 addressing configuration is requested.
+
+#### Static addressing
+
+A static interface is written as:
+
+```json
+"net0": {
+  "addressing": "static",
+  "address": "192.168.2.10/24",
+  "gateway": "192.168.2.1"
+}
+```
+
+`address` is required.
+
+`gateway` is optional.
+
+The gateway is kept with static interface configuration because this matches
+the simple configuration model used by traditional Linux network
+configuration.
+
+For the scope of this assignment, this is simpler than introducing a general
+routing language.
+
+#### DHCP addressing
+
+A DHCP interface is written as:
+
+```json
+"net0": {
+  "addressing": "dhcp"
+}
+```
+
+A DHCP interface does not contain a predetermined address or gateway.
+
+Those values are runtime configuration learned from the DHCP server.
+
+The resulting distinction is:
+
+```text
+static
+    address and optional gateway are configured locally
+
+dhcp
+    address and gateway are learned dynamically
+
+none / omitted
+    no L3 configuration is requested
+```
+
+### 4.4 Switch interfaces
+
+Switch ports use the same interface abstraction.
+
+For example, a switch with a fixed set of four logical ports may be written as:
+
+```json
+{
+  "name": "s1",
+  "type": "switch",
+  "interfaces": {
+    "p1": {},
+    "p2": {},
+    "p3": {},
+    "uplink": {}
+  }
+}
+```
+
+This is useful when link placement should refer to specific switch ports.
+
+If exact port identity does not matter, the `interfaces` field may be omitted
+and links may use automatic interface allocation.
+
+### 4.5 Omitted interfaces versus an empty interface set
+
+The distinction between these two forms is intentional.
+
+```json
+{
+  "name": "s1",
+  "type": "switch"
+}
+```
+
+means:
+
+```text
+interface set omitted
+-> dynamic interface set
+```
+
+while:
+
+```json
+{
+  "name": "s1",
+  "type": "switch",
+  "interfaces": {}
+}
+```
+
+means:
+
+```text
+interface set explicitly declared
+-> fixed interface set containing zero interfaces
+```
+
+This distinction is important for the semantics of `auto`.
+
+### 4.6 Connected and unused interfaces
+
+An interface requesting addressing, an address, a gateway, a MAC address, or an
+MTU must be attached to a link.
+Unused empty interface declarations may remain in a fixed interface pool.
+An interface used by a service must also be attached to a link.
+
+---
+
+## 5. Links
+
+A link is a first-class entity connecting exactly two endpoints.
+
+The current structure is:
+
+```text
+Link
+├── name?
+├── endpoints
+│   ├── endpoint A
+│   │   ├── node
+│   │   └── interface
+│   └── endpoint B
+│       ├── node
+│       └── interface
+└── settings
+```
+
+Keeping the `endpoints` wrapper is intentional.
+
+A link may carry properties other than its endpoints, so flattening the link
+into a raw pair would make future link-level configuration awkward.
+
+### 5.1 Explicit interface references
+
+An endpoint may reference an explicitly declared interface.
+
+For example:
+
+```json
+{
+  "node": "r0",
+  "interface": "lan"
+}
+```
+
+The referenced interface tag must exist on that node.
+
+### 5.2 Automatic interface allocation
+
+An endpoint may instead use:
+
+```json
+{
+  "node": "s1",
+  "interface": "auto"
+}
+```
+
+The meaning of `auto` depends on whether the node declared an interface set.
+
+If `interfaces` is omitted:
+
+```text
+dynamic interface set
+-> auto may allocate/create interfaces as needed
+```
+
+If `interfaces` is explicitly declared:
+
+```text
+fixed interface set
+-> auto selects an unused declared interface
+-> auto must not silently create an additional interface
+```
+
+For example:
+
+```json
+"interfaces": {
+  "p1": {},
+  "p2": {},
+  "p3": {},
+  "uplink": {}
+}
+```
+
+allows an explicit link to select:
+
+```json
+"interface": "uplink"
+```
+
+or an automatic link to select one of the remaining unused ports.
+
+Explicit references reserve their interfaces before `auto` selections are made.
+Each `auto` selection consumes the first remaining declared interface in
+interface declaration order, following link and endpoint order.
+If the fixed interface pool is exhausted, the topology is invalid.
+
+### 5.3 Why interfaces remain under nodes
+
+Interfaces remain under nodes because they may carry or receive:
+
+- addressing configuration,
+- MAC configuration,
+- MTU configuration,
+- service bindings,
+- future interface-specific properties.
+
+The selected relationship therefore remains:
+
+```text
+Node owns Interface
+Link references Interface
+```
+
+### 5.4 Link settings
+
+Links contain a `settings` object for provisioning properties.
+
+The supported provisioning fields are:
+
+```text
+bandwidth_mbps?
+delay_ms?
+loss_percent?
+jitter_ms?
+```
+
+Example:
+
+```json
+{
+  "endpoints": [
+    {
+      "node": "h1",
+      "interface": "net0"
+    },
+    {
+      "node": "s1",
+      "interface": "auto"
+    }
+  ],
+  "settings": {
+    "bandwidth_mbps": 100,
+    "delay_ms": 1.5,
+    "loss_percent": 0.1
+  }
+}
+```
+
+Bandwidth is expressed in megabits per second, delay and jitter in milliseconds,
+and loss as a percentage.
+
+The allowed ranges are:
+
+```text
+bandwidth_mbps > 0
+delay_ms >= 0
+jitter_ms >= 0
+0 <= loss_percent <= 100
+```
+
+---
+
+## 6. Services
+
+A service represents a process or daemon running on a topology node.
+
+The generic structure is:
+
+```text
+Service
+├── type
+├── node
+├── interface
+└── settings
+```
+
+The currently supported service type is:
+
+```text
+dhcp-server
+```
+
+Example:
+
+```json
+{
+  "type": "dhcp-server",
+  "node": "r0",
+  "interface": "lan",
+  "settings": {
+    "range": {
+      "start": "192.168.1.100",
+      "end": "192.168.1.200"
+    },
+    "gateway": "192.168.1.1"
+  }
+}
+```
+
+### 6.1 Service binding
+
+`node` and `interface` describe where the service runs and where it is bound.
+
+They therefore remain outside `settings`.
+
+The service interface grammar reserves:
+
+```text
+<tag>
+auto
+all
+```
+
+The validity and meaning of special selectors are service-type-specific.
+
+A DHCP service accepts a specific declared interface tag.
+
+The service also supports `auto` only when exactly one suitable statically
+addressed interface can be selected unambiguously from the declared set.
+
+The DHCP server does not support `all`.
+
+### 6.2 DHCP settings
+
+The current DHCP server settings are:
+
+```text
+range.start
+range.end
+gateway?
+```
+
+The service `gateway` is the gateway advertised to DHCP clients.
+
+This is distinct from a static interface gateway.
+
+```text
+static interface gateway
+    -> locally configured default gateway
+
+DHCP service gateway
+    -> gateway distributed to DHCP clients
+```
+
+---
+
+## 7. Grammar summary
+
+### Node
+
+```text
+name
+    required unique logical node identifier
+
+type
+    host | switch | router
+
+interfaces
+    optional map of logical interface tags to Interface objects
+
+settings
+    optional node-type-specific configuration
+```
+
+### Interface
+
+```text
+<tag>
+    logical interface identifier
+
+addressing
+    optional: static | dhcp | none
+    omission is equivalent to none
+
+address
+    required when addressing = static
+    forbidden otherwise
+
+gateway
+    optional when addressing = static
+    forbidden otherwise
+
+mac
+    optional
+
+mtu
+    optional
+```
+
+### Link
+
+```text
+name
+    optional logical link name
+
+endpoints
+    exactly two endpoints
+
+endpoint.node
+    node name
+
+endpoint.interface
+    declared interface tag | auto
+
+settings.bandwidth_mbps
+    optional
+
+settings.delay_ms
+    optional
+
+settings.loss_percent
+    optional
+
+settings.jitter_ms
+    optional
+```
+
+### Service
+
+```text
+type
+    currently dhcp-server
+
+node
+    node on which the service runs
+
+interface
+    interface tag | auto | all
+    validity depends on service type
+
+settings
+    service-type-specific configuration
+```
+
+---
+
+## 8. Strict grammar
+
+Unknown fields and unsupported tokens are invalid.
+For example, `ip_foward` is not an alias for `ip_forward`, and `bananas` is not
+an addressing mode.
+
+Field names, value types, and closed token sets define the JSON grammar.
+Cross-references and network constraints define semantic validity.
+A recognized `static` addressing mode without an address is therefore a
+semantic error, as is a link referring to an unknown node.
+
+Only the fields described in this reference are currently supported.
+Additional node types, services, or settings require a language extension.
+
+---
+
+## 9. Semantic constraints
+
+A topology must satisfy the following constraints in addition to the JSON
+grammar.
+Invalid configurations include:
+
+- duplicate node names,
+- duplicate explicit link names,
+- empty logical names,
+- reserved interface tags,
+- static interfaces without an address,
+- invalid IPv4/CIDR syntax,
+- invalid gateway syntax,
+- gateways outside the interface subnet,
+- addresses or gateways used with DHCP or no addressing,
+- invalid MAC syntax,
+- invalid MTU values,
+- explicit link references to unknown nodes,
+- explicit link references to unknown interfaces,
+- explicit interface reuse across links,
+- fixed interface-pool exhaustion caused by `auto`,
+- invalid link provisioning ranges,
+- services referencing unknown nodes,
+- services referencing unknown interfaces,
+- DHCP services bound to interfaces without static addressing,
+- invalid DHCP IPv4 ranges,
+- reversed DHCP ranges,
+- DHCP range values outside the bound interface subnet,
+- DHCP network or broadcast addresses,
+- DHCP pools that include the server address,
+- DHCP pools that include the advertised gateway.
+
+Switch interfaces may not request Layer-3 addressing.
+Only one static default gateway is supported per node.
+Configured interfaces and service bindings must be connected as described in
+[Connected and unused interfaces](#46-connected-and-unused-interfaces).
+

README.md

@@ -0,0 +1,476 @@
+# Computer Networks II — Declarative Mininet Topology Builder
+
+This repository implements the programming assignment for Computer Networks II
+using a small declarative JSON topology language and a staged Python build
+pipeline.
+
+The JSON describes the desired network rather than the exact Mininet commands
+used to create it.
+
+The implementation loads that description, parses it into typed Python objects,
+validates its semantics, resolves all abstract interface selections into a
+concrete execution plan, renders executable Mininet Python, and then runs that
+generated artifact.
+
+Start with [Quick start](#quick-start) to generate and run a topology.
+The [topology language overview](#topology-language) introduces the JSON format;
+the [JSON language reference](Mininet_DSL_Design.md)
+defines its fields, defaults, and semantic constraints.
+
+## Project goals
+
+The main goals of the implementation are:
+
+- describe Mininet topologies declaratively in JSON,
+- keep topology intent separate from Mininet implementation details,
+- use typed Python objects throughout the processing pipeline,
+- detect grammar and semantic errors before changing the network,
+- generate an inspectable intermediate Python artifact,
+- execute exactly that generated artifact for normal runs,
+- keep runtime experiments separate from topology construction,
+- clean up services and Mininet state safely after the CLI exits.
+
+The topology language is intentionally small.
+
+Its core semantic entities are:
+
+```text
+Node
+Interface
+Link
+Node Settings
+Service
+```
+
+## Repository layout
+
+```text
+source/
+    build_network.py       CLI coordinator and environment checks
+    topology_loader.py     JSON loading
+    topology_parser.py     Strict parsing and typed semantic model
+    topology_validator.py  Semantic and cross-reference checks
+    topology_plan.py       Fully resolved execution plan
+    topology_renderer.py   Executable Mininet Python generation
+report/                    Assignment report workspace
+exercise/                  Assignment execution files
+Mininet_DSL_Design.md      Mininet JSON domain specific language rules and semantics
+README.md                  Repository's main documentation file
+```
+
+Save a topology source as `topology.json`.
+Normal execution writes `topology.generated.py` beside that source file.
+
+## Requirements
+
+The implementation targets a Linux environment capable of running Mininet.
+
+The current runtime and experiment dependencies are:
+
+```text
+Python Mininet module
+mn
+ovs-vsctl
+ip
+tc
+sysctl
+dnsmasq
+dhclient
+tcpdump
+ping
+```
+
+On Ubuntu, the corresponding packages are typically provided by:
+
+```bash
+sudo apt install \
+    mininet \
+    openvswitch-switch \
+    iproute2 \
+    procps \
+    dnsmasq-base \
+    isc-dhcp-client \
+    tcpdump \
+    iputils-ping
+```
+
+The exact environment can be checked without modifying the system:
+
+```bash
+python3 source/build_network.py --env-check
+```
+
+The check reports each required module or executable as `OK` or `MISSING`.
+
+## Quick start
+
+Run these commands from the repository root.
+Save the [complete assignment example](#complete-assignment-topology-example)
+as `topology.json` first, or use your own topology file.
+
+### 1. Check the environment
+
+Run:
+
+```bash
+python3 source/build_network.py --env-check
+```
+
+### 2. Generate the intermediate Python only
+
+Run:
+
+```bash
+python3 source/build_network.py topology.json --emit
+```
+
+This writes:
+
+```text
+topology.generated.py
+```
+
+and stops without creating a Mininet network.
+
+A custom output path can be supplied:
+
+```bash
+python3 source/build_network.py topology.json --emit gen-test.py
+```
+
+Generation does not require root privileges.
+
+### 3. Generate and execute
+
+Run:
+
+```bash
+sudo python3 source/build_network.py topology.json
+```
+
+The coordinator:
+
+```text
+loads
+parses
+validates
+plans
+renders
+writes topology.generated.py
+executes topology.generated.py
+```
+
+Network execution requires root privileges because Mininet creates namespaces,
+virtual interfaces, Open vSwitch state, and other kernel networking objects.
+
+### 4. Exit the Mininet CLI
+
+When finished, leave the CLI with:
+
+```text
+mininet> exit
+```
+
+The generated script then stops the service processes it started and calls
+`net.stop()`.
+
+## Topology language
+
+The JSON describes `nodes`, their `interfaces`, `links`, and `services`.
+Nodes may be hosts, Layer-2 switches, or routers; interfaces use static, DHCP,
+or no addressing.
+Links connect interfaces, and services describe processes such as a DHCP server.
+
+Use the [JSON language reference](Mininet_DSL_Design.md) for field
+definitions, defaults, interface selection rules, and semantic constraints.
+The following example provides a complete starting point for the assignment.
+
+## Complete assignment topology example
+
+The example [here](exercise/topology.json) describes the required two-subnet topology.
+
+## Configuration versus runtime state
+
+The topology source describes configuration intent.
+
+It does not record all runtime state.
+
+Examples include:
+
+```text
+JSON declaration                 Runtime result
+
+static address          ----->   configured IPv4 address
+static gateway          ----->   configured default route
+DHCP addressing         ----->   dynamically learned address
+DHCP service settings   ----->   dynamically advertised options
+links                    ----->   Mininet/veth interfaces
+services                 ----->   running processes
+```
+
+DHCP leases, ARP entries, packet counters, and packet captures are runtime
+state.
+
+They do not belong in the topology grammar.
+
+## Runtime experiments
+
+After the generated topology enters the Mininet CLI, the assignment experiments
+can be performed with tools such as:
+
+```text
+dhclient
+tcpdump
+ip neigh
+ping
+```
+
+These commands operate on the running network and may create transient runtime
+state.
+
+They do not modify the declarative topology source.
+
+
+### DHCP capture preparation
+
+DHCP clients are intentionally not started by the generated network.
+
+The assignment requires packet capture to begin before the DHCP exchange is
+triggered manually.
+
+A clean client-side DHCP experiment can use a temporary lease and PID file:
+
+```text
+mininet> h1 rm -f /tmp/h1-dhclient.leases /tmp/h1-dhclient.pid
+mininet> h1 dhclient -v \
+    -lf /tmp/h1-dhclient.leases \
+    -pf /tmp/h1-dhclient.pid \
+    h1-eth0
+```
+
+A successful exchange should show the normal DORA sequence:
+
+```text
+DHCPDISCOVER
+DHCPOFFER
+DHCPREQUEST
+DHCPACK
+```
+
+The DHCP server lease file generated by this project is reset before the
+service starts, so stale server-side leases from earlier topology runs do not
+affect a new experiment.
+
+## Architecture
+
+The implementation follows a compiler-like pipeline:
+
+```text
+topology.json
+    → load → parse → validate → plan → render
+    → write generated Python → execute → Mininet CLI → cleanup
+```
+
+The language describes network concepts that map to Mininet and Linux
+primitives: nodes, interfaces, links, network-stack settings, and services.
+Each stage has a separate responsibility so it can be tested independently.
+The generated Python is the only executable Mininet backend.
+
+### Loading and parsing
+
+`topology_loader.py` provides `load_topology(path)`, which reads a JSON file into
+a raw dictionary.
+`topology_parser.py` provides `parse_topology(raw)`, which converts that dictionary
+into a typed `Topology`.
+Neither stage depends on Mininet.
+
+The semantic model uses dataclasses for `Topology`, `Node`, `Interface`, `Link`,
+`LinkEndpoint`, `Service`, and their structured settings.
+Enums represent node types, addressing modes, service types, and selectors.
+Interfaces and settings are composed into their owning entities.
+
+Nodes, links, and services remain ordered lists during parsing.
+Keeping nodes in a list preserves duplicate declarations for diagnostics;
+converting them immediately to a name-indexed dictionary could hide duplicates.
+`Node.interfaces` uses `Optional[Dict[str, Interface]]`: `None` preserves an
+omitted interface set, while `{}` preserves an explicitly empty set.
+
+### Validation
+
+`topology_validator.py` exposes `validate(topology)`.
+It checks semantic and cross-reference constraints after parsing has checked
+field names, representation, and value types.
+See the [language reference](Mininet_DSL_Design.md) for those rules.
+
+The validator collects `ValidationIssue(location, message)` objects and raises
+one `TopologyValidationError` containing all issues discovered in the pass.
+It does not print diagnostics or create Mininet objects.
+Validation checks whether automatic interface allocation is possible;
+planning performs the concrete allocation.
+
+### Planning
+
+`topology_plan.py` exposes `plan(topology)` and produces an immutable
+`ExecutionPlan` from a validated topology.
+It does not import Mininet, execute commands, or render Python.
+
+The plan contains ordered tuples of node, link, interface, sysctl, and service
+operations.
+Its types include `PlannedNode`, `PlannedLinkEndpoint`, `PlannedLink`,
+`PlannedLinkSettings`, `PlannedInterface`, `PlannedSysctl`, `PlannedService`, and
+`PlannedDHCPServerSettings`.
+No unresolved `auto` or `all` selectors remain.
+
+The planner reserves all explicit link-interface references before allocating
+`auto` selections from fixed pools in declaration order.
+Dynamic pools receive synthetic logical identifiers `auto0`, `auto1`, and so on.
+Concrete interface names follow `<node>-eth<N>`, starting at zero per node in
+link and endpoint traversal order.
+For example, `(r0, lan)` may resolve to `r0-eth0`.
+
+Mininet creates interfaces through links.
+Planning therefore rejects configured interfaces or service bindings that have
+no corresponding link, while allowing unused empty interface declarations.
+
+Switches are planned with Open vSwitch `failMode="standalone"` to operate as
+Layer-2 learning switches without an OpenFlow controller.
+Hosts and routers are created with `net.addHost(..., ip=None)`.
+Router settings generate sysctls only when explicitly supplied.
+`rp_filter` operations cover `all`, `default`, and each materialized router
+interface inside the router namespace.
+
+### Rendering and runtime lifecycle
+
+`topology_renderer.py` exposes `render_python(plan)`.
+It serializes the resolved plan without allocating interfaces or validating
+language semantics.
+The resulting standalone Python program is preserved for inspection.
+
+The generated program:
+
+1. Creates nodes and links, then builds and starts Mininet.
+2. Configures interfaces, static default routes, and namespace-scoped sysctls.
+3. Starts services and enters the Mininet CLI.
+4. Terminates tracked service processes and calls `net.stop()` in a `finally`
+   block.
+
+When a link has traffic-control settings, the renderer emits `TCLink`.
+Bandwidth maps to `bw`, loss to `loss`, and delay and jitter to millisecond
+strings.
+For example:
+
+```python
+net.addLink(
+    nodes["r0"],
+    nodes["s1"],
+    intfName1="r0-eth0",
+    intfName2="s1-eth1",
+    cls=TCLink,
+    delay="1.5ms",
+)
+```
+
+Interface configuration uses Linux commands such as `ip addr add`,
+`ip route replace`, and `sysctl -w` inside the appropriate node namespace.
+
+DHCP services run through `dnsmasq`, with DNS disabled and a 12-hour lease time.
+These are backend choices, not configurable JSON fields.
+Each service uses indexed lease, PID, and log paths under `/tmp`.
+The generated script removes its previous lease and PID files before startup
+and tracks the background PID for cleanup.
+DHCP clients are started manually after packet capture begins, as described in
+[Runtime experiments](#runtime-experiments).
+
+### Coordination and error reporting
+
+`build_network.py` coordinates the stages through `compile_topology(path)`,
+which returns the execution plan and rendered source.
+The coordinator writes the generated artifact beside the input using the
+`.generated.py` suffix unless `--emit PATH` selects a different destination.
+
+`--emit` stops after writing, without requiring Mininet or root privileges.
+Normal execution writes the same artifact, checks dependencies, and runs it
+with the coordinator's Python interpreter.
+Network execution requires root privileges.
+`--env-check` reports dependencies and exits without compiling a topology.
+See [Quick start](#quick-start) for commands.
+
+Core stages raise typed exceptions; the command-line layer reports them.
+
+| Stage | Exception |
+| --- | --- |
+| Loading | `TopologyLoadError` |
+| Parsing | `TopologyParseError` |
+| Validation | `TopologyValidationError` |
+| Planning | `TopologyPlanError` |
+| Artifact writing or process launch | `BuildNetworkError` |
+
+The coordinator returns a failing status for reported errors and propagates the
+exit status of the generated program.
+
+## Self-tests
+
+The five core pipeline modules contain lightweight `__main__` smoke tests.
+The coordinator's `__main__` invokes its command-line interface instead.
+
+They exercise each module's public interface.
+
+They can be run directly:
+
+```bash
+python3 source/topology_loader.py
+python3 source/topology_parser.py
+python3 source/topology_validator.py
+python3 source/topology_plan.py
+python3 source/topology_renderer.py
+```
+
+These smoke tests do not require Mininet, root privileges, or network changes.
+
+The environment can be checked separately with:
+
+```bash
+python3 source/build_network.py --env-check
+```
+
+A generated topology can then be tested in Mininet with:
+
+```bash
+sudo python3 source/build_network.py topology.json
+```
+
+## Current scope and extension points
+
+The current language supports:
+
+- hosts,
+- Layer-2 learning switches,
+- routers,
+- static IPv4 addressing,
+- DHCP client intent,
+- one optional static default gateway per node,
+- logical interface tags,
+- automatic interface allocation,
+- link bandwidth, delay, loss, and jitter,
+- DHCP server services,
+- router forwarding and reverse-path-filter settings.
+
+Extending the language requires corresponding parser, validator, planner, and
+renderer support.
+Potential extensions include:
+
+- additional node types,
+- additional services,
+- richer interface properties,
+- richer link behavior,
+- more general routing constructs.
+
+The project currently supports IPv4 network configuration for the assignment.
+
+## Further documentation
+
+- [JSON language reference](Mininet_DSL_Design.md):
+  complete field definitions, defaults, and semantic constraints.
+- [Assignment brief](Computer_Networks_II-Programming_task.pdf):
+  required topology, experiments, and deliverables.
+

exercise/results/exp1-dhcp/dhcp-decoded.txt

@@ -0,0 +1,91 @@
+10:58:29.655251 12:07:f8:bf:6e:ff > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
+    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 12:07:f8:bf:6e:ff, length 300, xid 0xecb5a2e, Flags [none] (0x0000)
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Discover
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Parameter-Request Option 55, length 13: 
+	      Subnet-Mask, BR, Time-Zone, Default-Gateway
+	      Domain-Name, Domain-Name-Server, Option 119, Hostname
+	      Netbios-Name-Server, Netbios-Scope, MTU, Classless-Static-Route
+	      NTP
+10:58:29.655633 82:3b:16:e9:bb:17 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:30.662723 82:3b:16:e9:bb:17 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:31.687064 82:3b:16:e9:bb:17 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:32.214530 12:07:f8:bf:6e:ff > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
+    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 12:07:f8:bf:6e:ff, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Discover
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Parameter-Request Option 55, length 13: 
+	      Subnet-Mask, BR, Time-Zone, Default-Gateway
+	      Domain-Name, Domain-Name-Server, Option 119, Hostname
+	      Netbios-Name-Server, Netbios-Scope, MTU, Classless-Static-Route
+	      NTP
+10:58:32.670822 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 62: (tos 0x0, ttl 64, id 28856, offset 0, flags [DF], proto ICMP (1), length 48)
+    192.168.1.1 > 192.168.1.131: ICMP echo request, id 21591, seq 0, length 28
+10:58:32.670897 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 342: (tos 0xc0, ttl 64, id 52736, offset 0, flags [none], proto UDP (17), length 328)
+    192.168.1.1.67 > 192.168.1.131.68: [udp sum ok] BOOTP/DHCP, Reply, length 300, xid 0xecb5a2e, Flags [none] (0x0000)
+	  Your-IP 192.168.1.131
+	  Server-IP 192.168.1.1
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Offer
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Lease-Time Option 51, length 4: 43200
+	    RN Option 58, length 4: 21600
+	    RB Option 59, length 4: 37800
+	    Subnet-Mask Option 1, length 4: 255.255.255.0
+	    BR Option 28, length 4: 192.168.1.255
+	    Default-Gateway Option 3, length 4: 192.168.1.1
+10:58:32.671193 12:07:f8:bf:6e:ff > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
+    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 12:07:f8:bf:6e:ff, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Request
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Requested-IP Option 50, length 4: 192.168.1.131
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Parameter-Request Option 55, length 13: 
+	      Subnet-Mask, BR, Time-Zone, Default-Gateway
+	      Domain-Name, Domain-Name-Server, Option 119, Hostname
+	      Netbios-Name-Server, Netbios-Scope, MTU, Classless-Static-Route
+	      NTP
+10:58:32.673025 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 342: (tos 0xc0, ttl 64, id 52738, offset 0, flags [none], proto UDP (17), length 328)
+    192.168.1.1.67 > 192.168.1.131.68: [bad udp cksum 0x851a -> 0x5896!] BOOTP/DHCP, Reply, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Your-IP 192.168.1.131
+	  Server-IP 192.168.1.1
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: ACK
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Lease-Time Option 51, length 4: 43200
+	    RN Option 58, length 4: 21600
+	    RB Option 59, length 4: 37800
+	    Subnet-Mask Option 1, length 4: 255.255.255.0
+	    BR Option 28, length 4: 192.168.1.255
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Default-Gateway Option 3, length 4: 192.168.1.1
+10:58:32.678132 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 342: (tos 0xc0, ttl 64, id 52737, offset 0, flags [none], proto UDP (17), length 328)
+    192.168.1.1.67 > 192.168.1.131.68: [udp sum ok] BOOTP/DHCP, Reply, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Your-IP 192.168.1.131
+	  Server-IP 192.168.1.1
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Offer
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Lease-Time Option 51, length 4: 43200
+	    RN Option 58, length 4: 21600
+	    RB Option 59, length 4: 37800
+	    Subnet-Mask Option 1, length 4: 255.255.255.0
+	    BR Option 28, length 4: 192.168.1.255
+	    Default-Gateway Option 3, length 4: 192.168.1.1
+10:58:37.831406 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:37.831440 12:07:f8:bf:6e:ff > 82:3b:16:e9:bb:17, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.131 is-at 12:07:f8:bf:6e:ff, length 28

exercise/results/exp1-dhcp/execution.txt

@@ -0,0 +1,109 @@
+mininet@mininet-vm:~/Networks-II/exercise$ sudo python3 ../source/build_network.py topology.json 
+Generated: topology.generated.py
+mininet> h1 rm -f /var/lib/dhcp/dhclient.leases
+mininet> h1 rm -f /tmp/dhcp.pcap
+mininet> h1 tcpdump -i h1-eth0 -n -w /tmp/dhcp.pcap &
+mininet> h1 ps aux | grep tcpdump
+tcpdump: listening on h1-eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
+tcpdump     4196  0.0  0.1  10904  5920 pts/2    S+   10:57   0:00 tcpdump -i h1-eth0 -n -w /tmp/dhcp.pcap
+root        4199  0.0  0.0   9368  2548 pts/2    S+   10:58   0:00 grep tcpdump
+mininet> h1 dhclient h1-eth0
+mininet> h1 pkill -INT tcpdump
+12 packets captured
+12 packets received by filter
+0 packets dropped by kernel
+mininet>  h1 tcpdump -n -e -vv -r /tmp/dhcp.pcap   
+reading from file /tmp/dhcp.pcap, link-type EN10MB (Ethernet)
+10:58:29.655251 12:07:f8:bf:6e:ff > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
+    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 12:07:f8:bf:6e:ff, length 300, xid 0xecb5a2e, Flags [none] (0x0000)
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Discover
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Parameter-Request Option 55, length 13: 
+	      Subnet-Mask, BR, Time-Zone, Default-Gateway
+	      Domain-Name, Domain-Name-Server, Option 119, Hostname
+	      Netbios-Name-Server, Netbios-Scope, MTU, Classless-Static-Route
+	      NTP
+10:58:29.655633 82:3b:16:e9:bb:17 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:30.662723 82:3b:16:e9:bb:17 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:31.687064 82:3b:16:e9:bb:17 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:32.214530 12:07:f8:bf:6e:ff > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
+    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 12:07:f8:bf:6e:ff, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Discover
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Parameter-Request Option 55, length 13: 
+	      Subnet-Mask, BR, Time-Zone, Default-Gateway
+	      Domain-Name, Domain-Name-Server, Option 119, Hostname
+	      Netbios-Name-Server, Netbios-Scope, MTU, Classless-Static-Route
+	      NTP
+10:58:32.670822 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 62: (tos 0x0, ttl 64, id 28856, offset 0, flags [DF], proto ICMP (1), length 48)
+    192.168.1.1 > 192.168.1.131: ICMP echo request, id 21591, seq 0, length 28
+10:58:32.670897 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 342: (tos 0xc0, ttl 64, id 52736, offset 0, flags [none], proto UDP (17), length 328)
+    192.168.1.1.67 > 192.168.1.131.68: [udp sum ok] BOOTP/DHCP, Reply, length 300, xid 0xecb5a2e, Flags [none] (0x0000)
+	  Your-IP 192.168.1.131
+	  Server-IP 192.168.1.1
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Offer
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Lease-Time Option 51, length 4: 43200
+	    RN Option 58, length 4: 21600
+	    RB Option 59, length 4: 37800
+	    Subnet-Mask Option 1, length 4: 255.255.255.0
+	    BR Option 28, length 4: 192.168.1.255
+	    Default-Gateway Option 3, length 4: 192.168.1.1
+10:58:32.671193 12:07:f8:bf:6e:ff > ff:ff:ff:ff:ff:ff, ethertype IPv4 (0x0800), length 342: (tos 0x10, ttl 128, id 0, offset 0, flags [none], proto UDP (17), length 328)
+    0.0.0.0.68 > 255.255.255.255.67: [udp sum ok] BOOTP/DHCP, Request from 12:07:f8:bf:6e:ff, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Request
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Requested-IP Option 50, length 4: 192.168.1.131
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Parameter-Request Option 55, length 13: 
+	      Subnet-Mask, BR, Time-Zone, Default-Gateway
+	      Domain-Name, Domain-Name-Server, Option 119, Hostname
+	      Netbios-Name-Server, Netbios-Scope, MTU, Classless-Static-Route
+	      NTP
+10:58:32.673025 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 342: (tos 0xc0, ttl 64, id 52738, offset 0, flags [none], proto UDP (17), length 328)
+    192.168.1.1.67 > 192.168.1.131.68: [bad udp cksum 0x851a -> 0x5896!] BOOTP/DHCP, Reply, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Your-IP 192.168.1.131
+	  Server-IP 192.168.1.1
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: ACK
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Lease-Time Option 51, length 4: 43200
+	    RN Option 58, length 4: 21600
+	    RB Option 59, length 4: 37800
+	    Subnet-Mask Option 1, length 4: 255.255.255.0
+	    BR Option 28, length 4: 192.168.1.255
+	    Hostname Option 12, length 10: "mininet-vm"
+	    Default-Gateway Option 3, length 4: 192.168.1.1
+10:58:32.678132 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype IPv4 (0x0800), length 342: (tos 0xc0, ttl 64, id 52737, offset 0, flags [none], proto UDP (17), length 328)
+    192.168.1.1.67 > 192.168.1.131.68: [udp sum ok] BOOTP/DHCP, Reply, length 300, xid 0xecb5a2e, secs 3, Flags [none] (0x0000)
+	  Your-IP 192.168.1.131
+	  Server-IP 192.168.1.1
+	  Client-Ethernet-Address 12:07:f8:bf:6e:ff
+	  Vendor-rfc1048 Extensions
+	    Magic Cookie 0x63825363
+	    DHCP-Message Option 53, length 1: Offer
+	    Server-ID Option 54, length 4: 192.168.1.1
+	    Lease-Time Option 51, length 4: 43200
+	    RN Option 58, length 4: 21600
+	    RB Option 59, length 4: 37800
+	    Subnet-Mask Option 1, length 4: 255.255.255.0
+	    BR Option 28, length 4: 192.168.1.255
+	    Default-Gateway Option 3, length 4: 192.168.1.1
+10:58:37.831406 82:3b:16:e9:bb:17 > 12:07:f8:bf:6e:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.1, length 28
+10:58:37.831440 12:07:f8:bf:6e:ff > 82:3b:16:e9:bb:17, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.131 is-at 12:07:f8:bf:6e:ff, length 28
+mininet> exit
+

exercise/results/exp2-arp/arp-decoded.txt

@@ -0,0 +1,4 @@
+11:24:23.554475 4a:6f:2a:18:f4:80 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.164 tell 192.168.1.131, length 28
+11:24:23.554730 82:c0:6d:ae:3f:56 > 4a:6f:2a:18:f4:80, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.164 is-at 82:c0:6d:ae:3f:56, length 28
+11:24:28.679054 82:c0:6d:ae:3f:56 > 4a:6f:2a:18:f4:80, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.164, length 28
+11:24:28.679071 4a:6f:2a:18:f4:80 > 82:c0:6d:ae:3f:56, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.131 is-at 4a:6f:2a:18:f4:80, length 28

exercise/results/exp2-arp/execution.txt

@@ -0,0 +1,40 @@
+mininet@mininet-vm:~/Networks-II/exercise$ sudo python3 ../source/build_network.py topology.json 
+Generated: topology.generated.py
+mininet> h1 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+mininet> h2 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+mininet> h1 dhclient h1-eth0
+mininet> h2 dhclient h2-eth0
+mininet> h1 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+h1-eth0@if56     UP             192.168.1.131/24 
+mininet> h2 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+h2-eth0@if57     UP             192.168.1.164/24 
+mininet> h1 ip neigh flush all
+mininet> h1 ip neigh show
+mininet> h1 rm -f /tmp/arp.pcap
+mininet> h1 tcpdump -i h1-eth0 -n arp -w /tmp/arp.pcap &
+mininet> h1 ping -c 1 192.168.1.164
+tcpdump: listening on h1-eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
+PING 192.168.1.164 (192.168.1.164) 56(84) bytes of data.
+64 bytes from 192.168.1.164: icmp_seq=1 ttl=64 time=0.425 ms
+
+--- 192.168.1.164 ping statistics ---
+1 packets transmitted, 1 received, 0% packet loss, time 0ms
+rtt min/avg/max/mdev = 0.425/0.425/0.425/0.000 ms
+mininet> h1 ip neigh show
+192.168.1.164 dev h1-eth0 lladdr 82:c0:6d:ae:3f:56 REACHABLE
+mininet> h1 pkill -INT tcpdump
+4 packets captured
+4 packets received by filter
+0 packets dropped by kernel
+mininet> h1 tcpdump -n -e -vv -r /tmp/arp.pcap
+reading from file /tmp/arp.pcap, link-type EN10MB (Ethernet)
+11:24:23.554475 4a:6f:2a:18:f4:80 > ff:ff:ff:ff:ff:ff, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.164 tell 192.168.1.131, length 28
+11:24:23.554730 82:c0:6d:ae:3f:56 > 4a:6f:2a:18:f4:80, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.164 is-at 82:c0:6d:ae:3f:56, length 28
+11:24:28.679054 82:c0:6d:ae:3f:56 > 4a:6f:2a:18:f4:80, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Request who-has 192.168.1.131 tell 192.168.1.164, length 28
+11:24:28.679071 4a:6f:2a:18:f4:80 > 82:c0:6d:ae:3f:56, ethertype ARP (0x0806), length 42: Ethernet (len 6), IPv4 (len 4), Reply 192.168.1.131 is-at 4a:6f:2a:18:f4:80, length 28
+mininet> 
+

exercise/results/exp3-routing/execution.txt

@@ -0,0 +1,79 @@
+mininet> 
+mininet> h1 ip neigh flush all
+mininet> h3 ip neigh flush all
+mininet> r0 ip neigh flush all
+mininet> h1 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+h1-eth0@if56     UP             192.168.1.131/24 
+mininet> h1 ip route
+default via 192.168.1.1 dev h1-eth0 
+192.168.1.0/24 dev h1-eth0 proto kernel scope link src 192.168.1.131 
+mininet> r0 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+r0-eth0@if59     UP             192.168.1.1/24 
+r0-eth1@if60     UP             192.168.2.1/24 
+mininet> r0 ip route
+192.168.1.0/24 dev r0-eth0 proto kernel scope link src 192.168.1.1 
+192.168.2.0/24 dev r0-eth1 proto kernel scope link src 192.168.2.1 
+mininet> h3 ip -4 -br addr
+lo               UNKNOWN        127.0.0.1/8 
+h3-eth0@if58     UP             192.168.2.10/24 
+mininet> h3 ip route
+default via 192.168.2.1 dev h3-eth0 
+192.168.2.0/24 dev h3-eth0 proto kernel scope link src 192.168.2.10 
+mininet> h1 rm -f /tmp/icmp-A.pcap
+mininet> h3 rm -f /tmp/icmp-B.pcap
+mininet> h1 tcpdump -i h1-eth0 -n icmp -w /tmp/icmp-A.pcap &
+mininet> h3 tcpdump -i h3-eth0 -n icmp -w /tmp/icmp-B.pcap &
+mininet> h1 ps aux | grep tcpdump
+tcpdump: listening on h1-eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
+tcpdump     4640  0.0  0.1  10904  5984 pts/2    S+   11:41   0:00 tcpdump -i h1-eth0 -n icmp -w /tmp/icmp-A.pcap
+tcpdump     4642  0.0  0.1  10904  6044 pts/4    S+   11:41   0:00 tcpdump -i h3-eth0 -n icmp -w /tmp/icmp-B.pcap
+root        4645  0.0  0.0   9368  2272 pts/2    S+   11:41   0:00 grep tcpdump
+mininet> h3 ps aux | grep tcpdump
+tcpdump: listening on h3-eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
+tcpdump     4640  0.0  0.1  10904  5984 pts/2    S+   11:41   0:00 tcpdump -i h1-eth0 -n icmp -w /tmp/icmp-A.pcap
+tcpdump     4642  0.0  0.1  10904  6044 pts/4    S+   11:41   0:00 tcpdump -i h3-eth0 -n icmp -w /tmp/icmp-B.pcap
+root        4648  0.0  0.0   9368  2304 pts/4    S+   11:41   0:00 grep tcpdump
+mininet>                          
+mininet> h1 ping -c 1 192.168.2.10
+PING 192.168.2.10 (192.168.2.10) 56(84) bytes of data.
+64 bytes from 192.168.2.10: icmp_seq=1 ttl=63 time=1.66 ms
+
+--- 192.168.2.10 ping statistics ---
+1 packets transmitted, 1 received, 0% packet loss, time 0ms
+rtt min/avg/max/mdev = 1.659/1.659/1.659/0.000 ms
+mininet> h1 pkill -INT tcpdump
+2 packets captured
+2 packets received by filter
+0 packets dropped by kernel
+mininet> h3 pkill -INT tcpdump
+2 packets captured
+2 packets received by filter
+0 packets dropped by kernel
+mininet> h1 ip link show h1-eth0
+2: h1-eth0@if56: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+    link/ether 4a:6f:2a:18:f4:80 brd ff:ff:ff:ff:ff:ff link-netnsid 0
+mininet> h3 ip link show h3-eth0
+2: h3-eth0@if58: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+    link/ether 2e:ef:81:65:2c:c9 brd ff:ff:ff:ff:ff:ff link-netnsid 0
+mininet> r0 ip link show r0-eth0
+2: r0-eth0@if59: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+    link/ether ea:2e:7b:6d:78:82 brd ff:ff:ff:ff:ff:ff link-netnsid 0
+mininet> r0 ip link show r0-eth1
+3: r0-eth1@if60: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+    link/ether 7e:41:8e:cb:65:05 brd ff:ff:ff:ff:ff:ff link-netnsid 0
+mininet> h1 tcpdump -n -e -vv -r /tmp/icmp-A.pcap
+reading from file /tmp/icmp-A.pcap, link-type EN10MB (Ethernet)
+11:42:14.509645 4a:6f:2a:18:f4:80 > ea:2e:7b:6d:78:82, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 64, id 33575, offset 0, flags [DF], proto ICMP (1), length 84)
+    192.168.1.131 > 192.168.2.10: ICMP echo request, id 4650, seq 1, length 64
+11:42:14.510633 ea:2e:7b:6d:78:82 > 4a:6f:2a:18:f4:80, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 63, id 65287, offset 0, flags [none], proto ICMP (1), length 84)
+    192.168.2.10 > 192.168.1.131: ICMP echo reply, id 4650, seq 1, length 64
+mininet> h3 tcpdump -n -e -vv -r /tmp/icmp-B.pcap
+reading from file /tmp/icmp-B.pcap, link-type EN10MB (Ethernet)
+11:42:14.510255 7e:41:8e:cb:65:05 > 2e:ef:81:65:2c:c9, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 63, id 33575, offset 0, flags [DF], proto ICMP (1), length 84)
+    192.168.1.131 > 192.168.2.10: ICMP echo request, id 4650, seq 1, length 64
+11:42:14.510299 2e:ef:81:65:2c:c9 > 7e:41:8e:cb:65:05, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 64, id 65287, offset 0, flags [none], proto ICMP (1), length 84)
+    192.168.2.10 > 192.168.1.131: ICMP echo reply, id 4650, seq 1, length 64
+
+

exercise/results/exp3-routing/icmp-A-decoded.txt

@@ -0,0 +1,4 @@
+11:42:14.509645 4a:6f:2a:18:f4:80 > ea:2e:7b:6d:78:82, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 64, id 33575, offset 0, flags [DF], proto ICMP (1), length 84)
+    192.168.1.131 > 192.168.2.10: ICMP echo request, id 4650, seq 1, length 64
+11:42:14.510633 ea:2e:7b:6d:78:82 > 4a:6f:2a:18:f4:80, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 63, id 65287, offset 0, flags [none], proto ICMP (1), length 84)
+    192.168.2.10 > 192.168.1.131: ICMP echo reply, id 4650, seq 1, length 64

exercise/results/exp3-routing/icmp-B-decoded.txt

@@ -0,0 +1,4 @@
+11:42:14.510255 7e:41:8e:cb:65:05 > 2e:ef:81:65:2c:c9, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 63, id 33575, offset 0, flags [DF], proto ICMP (1), length 84)
+    192.168.1.131 > 192.168.2.10: ICMP echo request, id 4650, seq 1, length 64
+11:42:14.510299 2e:ef:81:65:2c:c9 > 7e:41:8e:cb:65:05, ethertype IPv4 (0x0800), length 98: (tos 0x0, ttl 64, id 65287, offset 0, flags [none], proto ICMP (1), length 84)
+    192.168.2.10 > 192.168.1.131: ICMP echo reply, id 4650, seq 1, length 64

exercise/topology.generated.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Generated Mininet topology.  Do not edit by hand."""
+
+import shlex
+
+from mininet.cli import CLI
+from mininet.link import TCLink
+from mininet.net import Mininet
+
+
+def _shell_join(args):
+    """Quote command arguments for execution inside a Mininet node."""
+
+    return ' '.join(shlex.quote(str(arg)) for arg in args)
+
+
+def _node_cmd(node, *args):
+    """Execute one safely quoted command inside a Mininet node."""
+
+    return node.cmd(_shell_join(args))
+
+
+def _start_background(node, args, log_path):
+    """Start one background process and return its shell PID."""
+
+    command = _shell_join(args)
+    shell_command = (
+        command
+        + ' >'
+        + shlex.quote(log_path)
+        + ' 2>&1 & echo $!'
+    )
+    return node.cmd('sh -c ' + shlex.quote(shell_command)).strip()
+
+
+def main():
+    """Build, configure, expose, and clean up the planned network."""
+
+    net = Mininet(controller=None, build=False)
+    nodes = {}
+    service_processes = []
+
+    try:
+        # Create nodes.
+        nodes['h1'] = net.addHost('h1', ip=None)
+        nodes['h2'] = net.addHost('h2', ip=None)
+        nodes['h3'] = net.addHost('h3', ip=None)
+        nodes['s1'] = net.addSwitch('s1', failMode='standalone')
+        nodes['s2'] = net.addSwitch('s2', failMode='standalone')
+        nodes['r0'] = net.addHost('r0', ip=None)
+
+        # Create links.
+        net.addLink(
+            nodes['h1'],
+            nodes['s1'],
+            intfName1='h1-eth0',
+            intfName2='s1-eth0',
+        )
+        net.addLink(
+            nodes['h2'],
+            nodes['s1'],
+            intfName1='h2-eth0',
+            intfName2='s1-eth1',
+        )
+        net.addLink(
+            nodes['h3'],
+            nodes['s2'],
+            intfName1='h3-eth0',
+            intfName2='s2-eth0',
+        )
+        net.addLink(
+            nodes['r0'],
+            nodes['s1'],
+            intfName1='r0-eth0',
+            intfName2='s1-eth2',
+        )
+        net.addLink(
+            nodes['r0'],
+            nodes['s2'],
+            intfName1='r0-eth1',
+            intfName2='s2-eth1',
+        )
+
+        # Materialize the Mininet topology.
+        net.build()
+        net.start()
+
+        # Configure concrete interfaces.
+        _node_cmd(nodes['h1'], 'ip', '-4', 'addr', 'flush', 'dev', 'h1-eth0')
+        _node_cmd(nodes['h1'], 'ip', 'link', 'set', 'dev', 'h1-eth0', 'up')
+        _node_cmd(nodes['h2'], 'ip', '-4', 'addr', 'flush', 'dev', 'h2-eth0')
+        _node_cmd(nodes['h2'], 'ip', 'link', 'set', 'dev', 'h2-eth0', 'up')
+        _node_cmd(nodes['h3'], 'ip', '-4', 'addr', 'flush', 'dev', 'h3-eth0')
+        _node_cmd(nodes['h3'], 'ip', 'addr', 'add', '192.168.2.10/24', 'dev', 'h3-eth0')
+        _node_cmd(nodes['h3'], 'ip', 'link', 'set', 'dev', 'h3-eth0', 'up')
+        _node_cmd(nodes['r0'], 'ip', '-4', 'addr', 'flush', 'dev', 'r0-eth0')
+        _node_cmd(nodes['r0'], 'ip', 'addr', 'add', '192.168.1.1/24', 'dev', 'r0-eth0')
+        _node_cmd(nodes['r0'], 'ip', 'link', 'set', 'dev', 'r0-eth0', 'up')
+        _node_cmd(nodes['r0'], 'ip', '-4', 'addr', 'flush', 'dev', 'r0-eth1')
+        _node_cmd(nodes['r0'], 'ip', 'addr', 'add', '192.168.2.1/24', 'dev', 'r0-eth1')
+        _node_cmd(nodes['r0'], 'ip', 'link', 'set', 'dev', 'r0-eth1', 'up')
+
+        # Configure static default routes.
+        _node_cmd(nodes['h3'], 'ip', 'route', 'replace', 'default', 'via', '192.168.2.1', 'dev', 'h3-eth0')
+
+        # Apply node-level networking settings.
+        _node_cmd(nodes['r0'], 'sysctl', '-w', 'net.ipv4.ip_forward=1')
+        _node_cmd(nodes['r0'], 'sysctl', '-w', 'net.ipv4.conf.all.rp_filter=0')
+        _node_cmd(nodes['r0'], 'sysctl', '-w', 'net.ipv4.conf.default.rp_filter=0')
+        _node_cmd(nodes['r0'], 'sysctl', '-w', 'net.ipv4.conf.r0-eth0.rp_filter=0')
+        _node_cmd(nodes['r0'], 'sysctl', '-w', 'net.ipv4.conf.r0-eth1.rp_filter=0')
+
+        # Start planned services.
+        _node_cmd(nodes['r0'], 'rm', '-f', '/tmp/mininet-dnsmasq-0.leases', '/tmp/mininet-dnsmasq-0.pid')
+        pid = _start_background(
+            nodes['r0'],
+            ['dnsmasq', '--no-daemon', '--conf-file=', '--port=0', '--bind-interfaces', '--dhcp-authoritative', '--interface=r0-eth0', '--dhcp-range=192.168.1.100,192.168.1.200,12h', '--dhcp-leasefile=/tmp/mininet-dnsmasq-0.leases', '--pid-file=/tmp/mininet-dnsmasq-0.pid', '--dhcp-option=3,192.168.1.1'],
+            '/tmp/mininet-dnsmasq-0.log',
+        )
+        service_processes.append((nodes['r0'], pid))
+
+        # DHCP clients are intentionally not started here.
+        # The assignment captures DHCP before dhclient is run manually.
+        CLI(net)
+
+    finally:
+        # Stop only the service processes started by this script.
+        for node, pid in reversed(service_processes):
+            if pid:
+                _node_cmd(node, 'kill', pid)
+
+        net.stop()
+
+
+if __name__ == '__main__':
+    main()

exercise/topology.json

@@ -0,0 +1,95 @@
+{
+  "nodes": [ {
+      "name": "h1",
+      "type": "host",
+      "interfaces": {
+        "net0": {
+          "addressing": "dhcp"
+        }
+      }
+    }, {
+      "name": "h2",
+      "type": "host",
+      "interfaces": {
+        "net0": {
+          "addressing": "dhcp"
+        }
+      }
+    }, {
+      "name": "h3",
+      "type": "host",
+      "interfaces": {
+        "net0": {
+          "addressing": "static",
+          "address": "192.168.2.10/24",
+          "gateway": "192.168.2.1"
+        }
+      }
+    }, {
+      "name": "s1",
+      "type": "switch"
+    }, {
+      "name": "s2",
+      "type": "switch"
+    }, {
+      "name": "r0",
+      "type": "router",
+      "interfaces": {
+        "netA": {
+          "addressing": "static",
+          "address": "192.168.1.1/24"
+        },
+        "netB": {
+          "addressing": "static",
+          "address": "192.168.2.1/24"
+        }
+      },
+      "settings": {
+        "ip_forward": true,
+        "rp_filter": false
+      }
+    }
+  ],
+
+  "links": [ {
+      "endpoints": [
+        { "node": "h1",  "interface": "net0" },
+        { "node": "s1",  "interface": "auto" }
+      ]
+    }, {
+      "endpoints": [
+        { "node": "h2",  "interface": "net0" },
+        { "node": "s1",  "interface": "auto" }
+      ]
+    }, {
+      "endpoints": [
+        { "node": "h3",  "interface": "net0" },
+        { "node": "s2",  "interface": "auto" }
+      ]
+    }, {
+      "endpoints": [
+        { "node": "r0",  "interface": "netA"  },
+        { "node": "s1",  "interface": "auto" }
+      ]
+    }, {
+      "endpoints": [
+        { "node": "r0",  "interface": "netB"  },
+        { "node": "s2",  "interface": "auto" }
+      ]
+    }
+  ],
+
+  "services": [ {
+      "type": "dhcp-server",
+      "node": "r0",
+      "interface": "netA",
+      "settings": {
+        "range": {
+          "start": "192.168.1.100",
+          "end": "192.168.1.200"
+        },
+        "gateway": "192.168.1.1"
+      }
+    }
+  ]
+}

report/.gitignore

@@ -0,0 +1,8 @@
+# LaTeX auxiliary files
+*.aux
+*.log
+*.out
+*.synctex.gz
+_minted*/*
+
+

source/build_network.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""Coordinate topology loading, validation, planning, rendering, and execution.
+
+The coordinator is the user-facing entry point of the project.
+
+Normal execution follows this pipeline:
+
+    topology.json
+        -> load and parse
+        -> validate
+        -> plan
+        -> render executable Mininet Python
+        -> write the generated intermediate artifact
+        -> execute that generated artifact
+
+The generated Python file is intentionally preserved so it can be inspected
+independently of the declarative topology source.
+
+Author: Christos Choutouridis <cchoutou@ece.auth.gr>
+"""
+
+import argparse
+from dataclasses import dataclass
+import importlib.util
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from typing import Optional, Sequence, Tuple, Union
+
+from topology_loader import TopologyLoadError, load_topology
+from topology_parser import TopologyParseError, parse_topology
+from topology_plan import ExecutionPlan, TopologyPlanError, plan
+from topology_renderer import render_python
+from topology_validator import TopologyValidationError, validate
+
+
+# ============================ Types and errors ============================
+
+PathLike = Union[str, Path]
+
+
+class BuildNetworkError(RuntimeError):
+    """Raised for coordinator-level generation or execution failures."""
+
+
+@dataclass(frozen=True)
+class EnvironmentRequirement:
+    """Describe one external runtime requirement.
+
+    Args:
+        name: Human-readable requirement name.
+        available: Whether the requirement is available in the current
+            environment.
+        detail: Resolved path, explanatory status, or installation hint.
+    """
+
+    name: str
+    available: bool
+    detail: str
+
+
+@dataclass(frozen=True)
+class EnvironmentReport:
+    """Contain the result of checking external project dependencies.
+
+    Args:
+        requirements: Individual dependency checks.
+    """
+
+    requirements: Tuple[EnvironmentRequirement, ...]
+
+    @property
+    def ok(self) -> bool:
+        """Return whether every required dependency is available."""
+
+        return all(item.available for item in self.requirements)
+
+
+# =========================== Environment checks ===========================
+
+def _check_python_module(name: str, install_hint: str) -> EnvironmentRequirement:
+    """Check whether one Python module is importable.
+
+    Args:
+        name: Importable Python module name.
+        install_hint: Human-readable installation hint used when missing.
+
+    Returns:
+        EnvironmentRequirement describing the result.
+    """
+
+    available = importlib.util.find_spec(name) is not None
+    detail = "Python module available" if available else install_hint
+
+    return EnvironmentRequirement(
+        name="python module %s" % name,
+        available=available,
+        detail=detail,
+    )
+
+
+def _check_command(
+    command: str,
+    purpose: str,
+    install_hint: str,
+) -> EnvironmentRequirement:
+    """Check whether one executable is available through PATH.
+
+    Args:
+        command: Executable name to locate.
+        purpose: Short description of why the executable is required.
+        install_hint: Human-readable installation hint used when missing.
+
+    Returns:
+        EnvironmentRequirement describing the result.
+    """
+
+    path = shutil.which(command)
+
+    if path is not None:
+        detail = "%s (%s)" % (path, purpose)
+    else:
+        detail = "%s; %s" % (purpose, install_hint)
+
+    return EnvironmentRequirement(
+        name=command,
+        available=path is not None,
+        detail=detail,
+    )
+
+
+def check_environment() -> EnvironmentReport:
+    """Check dependencies required by the builder and assignment experiments.
+
+    Returns:
+        EnvironmentReport containing all required dependency checks.
+
+    Notes:
+        This function performs read-only availability checks.
+        It does not install packages or modify the system.
+    """
+
+    requirements = [
+        _check_python_module(
+            "mininet",
+            "install Mininet, for example: sudo apt install mininet",
+        ),
+        _check_command(
+            "mn",
+            "Mininet command-line utilities",
+            "install Mininet, for example: sudo apt install mininet",
+        ),
+        _check_command(
+            "ovs-vsctl",
+            "Open vSwitch configuration used by Mininet switches",
+            "install Open vSwitch, for example: sudo apt install openvswitch-switch",
+        ),
+        _check_command(
+            "ip",
+            "interface and route configuration",
+            "install iproute2: sudo apt install iproute2",
+        ),
+        _check_command(
+            "tc",
+            "traffic-control settings for TCLink",
+            "install iproute2: sudo apt install iproute2",
+        ),
+        _check_command(
+            "sysctl",
+            "router kernel settings",
+            "install procps: sudo apt install procps",
+        ),
+        _check_command(
+            "dnsmasq",
+            "DHCP server service",
+            "install dnsmasq-base: sudo apt install dnsmasq-base",
+        ),
+        _check_command(
+            "dhclient",
+            "manual DHCP client experiment",
+            "install isc-dhcp-client: sudo apt install isc-dhcp-client",
+        ),
+        _check_command(
+            "tcpdump",
+            "packet capture for DHCP, ARP, and routing experiments",
+            "install tcpdump: sudo apt install tcpdump",
+        ),
+        _check_command(
+            "ping",
+            "ICMP connectivity experiments",
+            "install iputils-ping: sudo apt install iputils-ping",
+        ),
+    ]
+
+    return EnvironmentReport(requirements=tuple(requirements))
+
+
+# =================== Compilation and artifact execution ===================
+
+def compile_topology(path: PathLike) -> Tuple[ExecutionPlan, str]:
+    """Compile one topology file into a plan and executable Python source.
+
+    Args:
+        path: Path to the declarative topology JSON file.
+
+    Returns:
+        Pair containing the fully resolved ExecutionPlan and rendered Python
+        source.
+
+    Raises:
+        TopologyLoadError: If the JSON source cannot be loaded.
+        TopologyParseError: If the JSON violates the topology grammar.
+        TopologyValidationError: If the parsed topology is semantically
+            inconsistent.
+        TopologyPlanError: If the validated topology cannot be lowered into a
+            complete execution plan.
+    """
+
+    topology = parse_topology(load_topology(path))
+    validate(topology)
+    execution_plan = plan(topology)
+    source = render_python(execution_plan)
+
+    return execution_plan, source
+
+
+def default_generated_path(topology_path: PathLike) -> Path:
+    """Return the default intermediate Python path for a topology source.
+
+    Args:
+        topology_path: Source topology path.
+
+    Returns:
+        Path alongside the topology using the `.generated.py` suffix.
+    """
+
+    return Path(topology_path).with_suffix(".generated.py")
+
+
+def write_generated_python(source: str, path: PathLike) -> Path:
+    """Write generated executable Python source to disk.
+
+    Args:
+        source: Rendered Python program.
+        path: Destination path for the generated artifact.
+
+    Returns:
+        Destination Path, remaining relative if the supplied path is relative.
+
+    Raises:
+        BuildNetworkError: If the artifact cannot be written.
+    """
+
+    destination = Path(path)
+
+    try:
+        destination.write_text(source, encoding="utf-8")
+    except OSError as exc:
+        raise BuildNetworkError(
+            "failed to write generated Python %s: %s" % (destination, exc)
+        ) from exc
+
+    return destination
+
+
+def execute_generated_python(path: PathLike) -> int:
+    """Execute one generated Mininet Python artifact interactively.
+
+    Args:
+        path: Generated Python file to execute.
+
+    Returns:
+        Exit status returned by the generated process.
+
+    Raises:
+        BuildNetworkError: If execution is attempted without root privileges
+            or the generated process cannot be started.
+    """
+
+    source = Path(path)
+
+    if os.geteuid() != 0:
+        raise BuildNetworkError(
+            "network execution requires root privileges; rerun with sudo or "
+            "use --emit to generate the intermediate Python without executing it"
+        )
+
+    try:
+        completed = subprocess.run(
+            [sys.executable, str(source)],
+            check=False,
+        )
+    except OSError as exc:
+        raise BuildNetworkError(
+            "failed to execute generated Python %s: %s" % (source, exc)
+        ) from exc
+
+    return completed.returncode
+
+
+# ================== Command-line reporting and arguments ==================
+
+def _print_environment_report(report: EnvironmentReport) -> None:
+    """Print an environment report from the command-line layer.
+
+    Args:
+        report: Environment report to present to the user.
+    """
+
+    print("Environment check:")
+    for requirement in report.requirements:
+        marker = "OK" if requirement.available else "MISSING"
+        print("[%s] %-16s %s" % (marker, requirement.name, requirement.detail))
+
+    if report.ok:
+        print("Environment OK.")
+    else:
+        print("Environment check failed: one or more required dependencies are missing.")
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    """Create the command-line argument parser.
+
+    Returns:
+        Configured ArgumentParser instance.
+    """
+
+    parser = argparse.ArgumentParser(
+        description=(
+            "Load, validate, plan, render, and execute a declarative Mininet "
+            "topology."
+        )
+    )
+    parser.add_argument(
+        "topology",
+        nargs="?",
+        help="path to topology.json; omitted only with --env-check",
+    )
+    parser.add_argument(
+        "--env-check",
+        action="store_true",
+        help=(
+            "check Mininet, Open vSwitch, dnsmasq, and experiment tools, then exit"
+        ),
+    )
+    parser.add_argument(
+        "--emit",
+        nargs="?",
+        const="",
+        metavar="PATH",
+        help=(
+            "generate the intermediate Python and stop; optionally write it to PATH"
+        ),
+    )
+
+    return parser
+
+
+# ======================== Command-line entry point ========================
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Run the coordinator command-line interface.
+
+    Args:
+        argv: Optional argument sequence excluding the executable name.
+
+    Returns:
+        Process exit status.
+    """
+
+    parser = _build_argument_parser()
+    args = parser.parse_args(argv)
+
+    if args.env_check:
+        report = check_environment()
+        _print_environment_report(report)
+        return 0 if report.ok else 1
+
+    if args.topology is None:
+        parser.error("topology is required unless --env-check is used")
+
+    topology_path = Path(args.topology)
+
+    if args.emit is None:
+        generated_path = default_generated_path(topology_path)
+        execute = True
+    else:
+        generated_path = (
+            default_generated_path(topology_path)
+            if args.emit == ""
+            else Path(args.emit)
+        )
+        execute = False
+
+    try:
+        _, source = compile_topology(topology_path)
+        generated_path = write_generated_python(source, generated_path)
+
+        print("Generated: %s" % generated_path)
+
+        if not execute:
+            return 0
+
+        report = check_environment()
+        if not report.ok:
+            _print_environment_report(report)
+            return 1
+
+        return execute_generated_python(generated_path)
+
+    except (
+        TopologyLoadError,
+        TopologyParseError,
+        TopologyValidationError,
+        TopologyPlanError,
+        BuildNetworkError,
+    ) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

source/topology_loader.py

@@ -15,13 +15,16 @@ Author: Christos Choutouridis <cchoutou@ece.auth.gr>
 """
 
 import json
-from pathlib import Path
+
+from pathlib  import Path
 from tempfile import NamedTemporaryFile
-from typing import Any, Dict, Union
+from typing   import Any, Dict, Union
 
 from topology_parser import Topology, parse_topology
 
 
+# ============================ Types and errors ============================
+
 PathLike = Union[str, Path]
 
 
@@ -29,6 +32,8 @@ class TopologyLoadError(ValueError):
     """Raised when a topology file cannot be loaded as a JSON object."""
 
 
+# ============================ Public interface ============================
+
 def load_topology(path: PathLike) -> Dict[str, Any]:
     """Load a topology JSON file into a raw dictionary.
 
@@ -66,23 +71,8 @@ def load_topology(path: PathLike) -> Dict[str, Any]:
     return raw
 
 
-def load(path: PathLike) -> Topology:
-    """Load and parse a topology file in one convenience call.
-
-    Args:
-        path: Path to the topology JSON file.
-
-    Returns:
-        Parsed Topology model.
-
-    Raises:
-        TopologyLoadError: If the JSON file cannot be loaded.
-        topology_parser.TopologyParseError: If the loaded JSON cannot be
-            represented by the topology grammar.
-    """
-
-    return parse_topology(load_topology(path))
 
+# =============================== Self-test ===============================
 
 def _self_test() -> None:
     """Run a small smoke test against load_topology() and load()."""
@@ -108,7 +98,7 @@ def _self_test() -> None:
         handle.flush()
 
         raw = load_topology(handle.name)
-        topology = load(handle.name)
+        topology = parse_topology(load_topology(handle.name))
 
     assert raw["nodes"][0]["name"] == "s1"
     assert topology.nodes[0].name == "s1"

source/topology_parser.py

@@ -3,18 +3,20 @@
 This module contains the in-memory semantic model used by the rest of the
 pipeline and the parser that converts a raw JSON dictionary into that model.
 
-The parser is intentionally independent of Mininet.  Its job is only to turn
+The parser is intentionally independent of Mininet. Its job is only to turn
-JSON-shaped data into typed Python objects.  Cross-reference and semantic
+JSON-shaped data into typed Python objects. Cross-reference and semantic
 validation belong to the validation stage that follows parsing.
 
 Author: Christos Choutouridis <cchoutou@ece.auth.gr>
 """
 
 from dataclasses import dataclass, field
-from enum import Enum
+from enum        import Enum
-from typing import Any, Dict, List, Mapping, Optional, Set, Tuple, Union
+from typing      import Any, Dict, List, Mapping, Optional, Set, Tuple, Union
 
 
+# ======================= Semantic model and errors =======================
+
 JSONMapping = Mapping[str, Any]
 
 
@@ -25,7 +27,7 @@ class TopologyParseError(ValueError):
 class NodeType(Enum):
     """Supported logical node types."""
 
-    HOST = "host"
+    HOST   = "host"
     SWITCH = "switch"
     ROUTER = "router"
 
@@ -33,9 +35,9 @@ class NodeType(Enum):
 class AddressingMode(Enum):
     """Supported Layer-3 addressing modes for an interface."""
 
-    NONE = "none"
+    NONE   = "none"
     STATIC = "static"
-    DHCP = "dhcp"
+    DHCP   = "dhcp"
 
 
 class LinkInterfaceSelector(Enum):
@@ -48,7 +50,7 @@ class ServiceInterfaceSelector(Enum):
     """Special interface selectors that are valid for a service binding."""
 
     AUTO = "auto"
-    ALL = "all"
+    ALL  = "all"
 
 
 class ServiceType(Enum):
@@ -62,29 +64,33 @@ class Interface:
     """Describe one logical network interface owned by a node.
 
     Args:
-        name: Logical interface tag used by the topology description.
+        name:       Logical interface tag used by the topology description.
-        addressing: Layer-3 addressing strategy.  Omitting addressing in JSON
+        addressing: Layer-3 addressing strategy.
-            is represented as AddressingMode.NONE.
+                    Omitting addressing in JSON is represented as AddressingMode.NONE.
-        address: Static CIDR address, valid when addressing is STATIC.
+        address:    Static CIDR address, valid when addressing is STATIC.
-        gateway: Optional default gateway, valid when addressing is STATIC.
+        gateway:    [Optional] default gateway, valid when addressing is STATIC.
-        mac: Optional explicit MAC address.  Reserved for current/future use.
+        mac:        [Optional] explicit MAC address applied to the concrete interface.
-        mtu: Optional MTU value.  Reserved for current/future use.
+        mtu:        [Optional] MTU in bytes applied to the concrete interface.
+
+    Notes:
+        MAC and MTU are independent of the addressing mode.
+        The generated program applies them using Linux ip link commands.
     """
 
-    name: str
+    name:       str
     addressing: AddressingMode = AddressingMode.NONE
-    address: Optional[str] = None
+    address:    Optional[str] = None
-    gateway: Optional[str] = None
+    gateway:    Optional[str] = None
-    mac: Optional[str] = None
+    mac:        Optional[str] = None
-    mtu: Optional[int] = None
+    mtu:        Optional[int] = None
 
 
 @dataclass
 class HostSettings:
     """Contain host-specific settings.
 
-    The current grammar does not require host-specific settings yet.  Keeping
+    The current grammar does not require host-specific settings yet.
-    a dedicated type gives the model a stable extension point.
+    Keeping a dedicated type gives the model a stable extension point.
     """
 
 
@@ -92,8 +98,8 @@ class HostSettings:
 class SwitchSettings:
     """Contain switch-specific settings.
 
-    The current grammar does not require switch-specific settings yet.  Keeping
+    The current grammar does not require switch-specific settings yet.
-    a dedicated type gives the model a stable extension point.
+    Keping a dedicated type gives the model a stable extension point.
     """
 
 
@@ -107,9 +113,9 @@ class RouterSettings:
     """
 
     ip_forward: Optional[bool] = None
-    rp_filter: Optional[bool] = None
+    rp_filter:  Optional[bool] = None
-
 
+# Mutable global
 NodeSettings = Union[HostSettings, SwitchSettings, RouterSettings]
 
 
@@ -118,19 +124,21 @@ class Node:
     """Describe one logical topology node.
 
     Args:
-        name: Unique logical node name.
+        name:   Unique logical node name.
-        type: Semantic node type.
+        type:   Semantic node type.
-        interfaces: Declared logical interfaces.  None means that the node did
+        interfaces:
-            not declare an interface set and therefore allows dynamic interface
+                Declared logical interfaces.
-            allocation.  An empty dictionary means that an explicit, fixed
+                None means that the node did not declare an interface set and therefore
-            interface set was declared and contains zero interfaces.
+                allows dynamic interface allocation.
+                An empty dictionary means that an explicit, fixed interface set was declared
+                and contains zero interfaces.
         settings: Type-specific node settings.
     """
 
-    name: str
+    name:       str
-    type: NodeType
+    type:       NodeType
     interfaces: Optional[Dict[str, Interface]]
-    settings: NodeSettings
+    settings:   NodeSettings
 
 
 @dataclass
@@ -138,11 +146,11 @@ class LinkEndpoint:
     """Describe one endpoint of a point-to-point logical link.
 
     Args:
-        node: Name of the node referenced by the endpoint.
+        node:      Name of the node referenced by the endpoint.
         interface: Explicit logical interface tag or the AUTO selector.
     """
 
-    node: str
+    node:      str
     interface: Union[str, LinkInterfaceSelector]
 
 
@@ -151,22 +159,23 @@ class LinkSettings:
     """Contain optional link-specific provisioning settings.
 
     Args:
-        bandwidth_mbps: Optional link bandwidth limit in megabits per second.
+        bandwidth_mbps: [Optional] link bandwidth limit in megabits per second.
-        delay_ms: Optional one-way propagation delay in milliseconds.
+        delay_ms:       [Optional] one-way propagation delay in milliseconds.
-        loss_percent: Optional packet-loss percentage.
+        loss_percent:   [Optional] packet-loss percentage.
-        jitter_ms: Optional delay variation in milliseconds.
+        jitter_ms:      [Optional] delay variation in milliseconds.
 
     Notes:
-        These fields are reserved as extension points for later Mininet link
+        All four settings are implemented through Mininet TCLink parameters
-        provisioning, for example through traffic-controlled link classes.
+        in the generated program.
-        They are parsed now so the semantic model already has a stable place
+        Bandwidth maps to bw, loss to loss, and delay and jitter to millisecond strings.
-        for link-level configuration.
+        Additional provisioning settings require corresponding parser,
+        validator, planner, and renderer support before they can be used.
     """
 
     bandwidth_mbps: Optional[float] = None
-    delay_ms: Optional[float] = None
+    delay_ms:       Optional[float] = None
-    loss_percent: Optional[float] = None
+    loss_percent:   Optional[float] = None
-    jitter_ms: Optional[float] = None
+    jitter_ms:      Optional[float] = None
 
 
 @dataclass
@@ -175,13 +184,13 @@ class Link:
 
     Args:
         endpoints: Ordered pair of link endpoints.
-        name: Optional logical link name used for diagnostics or extensions.
+        name:      [ Optional] logical link name used for diagnostics or extensions.
-        settings: Link-specific provisioning settings.
+        settings:  Link-specific provisioning settings.
     """
 
     endpoints: Tuple[LinkEndpoint, LinkEndpoint]
-    name: Optional[str] = None
+    name:      Optional[str] = None
-    settings: LinkSettings = field(default_factory=LinkSettings)
+    settings:  LinkSettings = field(default_factory=LinkSettings)
 
 
 @dataclass
@@ -190,11 +199,11 @@ class DHCPRange:
 
     Args:
         start: First address in the DHCP allocation range.
-        end: Last address in the DHCP allocation range.
+        end:   Last address in the DHCP allocation range.
     """
 
     start: str
-    end: str
+    end:   str
 
 
 @dataclass
@@ -203,13 +212,14 @@ class DHCPServerSettings:
 
     Args:
         address_range: Address range offered to DHCP clients.
-        gateway: Optional default gateway advertised to DHCP clients.
+        gateway:       [Optional] default gateway advertised to DHCP clients.
     """
 
     address_range: DHCPRange
-    gateway: Optional[str] = None
+    gateway:       Optional[str] = None
 
 
+# Mutable global
 ServiceSettings = DHCPServerSettings
 
 
@@ -218,44 +228,48 @@ class Service:
     """Describe a service attached to a topology node.
 
     Args:
-        type: Service implementation type.
+        type:      Service implementation type.
-        node: Name of the node on which the service runs.
+        node:      Name of the node on which the service runs.
         interface: Explicit logical interface tag or a supported special
             selector such as AUTO or ALL.
-        settings: Type-specific service settings.
+        settings:  Type-specific service settings.
     """
 
     type: ServiceType
     node: str
     interface: Union[str, ServiceInterfaceSelector]
-    settings: ServiceSettings
+    settings:  ServiceSettings
 
 
 @dataclass
 class Topology:
     """Contain the complete parsed topology model.
 
-    Args:
+    nodes:
-        nodes: Nodes in declaration order.  Keeping nodes as a list preserves
+        Nodes in declaration order. Keeping nodes as a list preserves
-            the parsed source faithfully, including duplicate names, so that
+        the parsed source faithfully, including duplicate names, so that
-            the separate validation stage can diagnose them instead of losing
+        the separate validation stage can diagnose them instead of losing
-            information during parsing.
+        information during parsing.
-        links: Links in declaration order.  Order is preserved because it can
+    links:
-            make automatic interface allocation deterministic.
+        Links in declaration order. Order is preserved because it can
-        services: Services in declaration order.  Order may later be useful for
+        make automatic interface allocation deterministic.
-            deterministic startup and shutdown.
+    services:
+        Services in declaration order. Order may later be useful for
+        deterministic startup and shutdown.
     """
 
-    nodes: List[Node] = field(default_factory=list)
+    nodes:    List[Node]    = field(default_factory=list)
-    links: List[Link] = field(default_factory=list)
+    links:    List[Link]    = field(default_factory=list)
     services: List[Service] = field(default_factory=list)
 
 
+# ============================ Parsing filters ============================
+
 def _mapping(value: Any, context: str) -> JSONMapping:
     """Return a value as a mapping or raise a parse error.
 
     Args:
-        value: Value expected to be a JSON object.
+        value:   Value expected to be a JSON object.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -278,7 +292,7 @@ def _reject_unknown_fields(
     """Reject object members that are not part of the grammar.
 
     Args:
-        data: Parsed JSON object whose member names are checked.
+        data:    Parsed JSON object whose member names are checked.
         allowed: Set of field names accepted at this grammar location.
         context: Human-readable location used in the error message.
 
@@ -292,7 +306,7 @@ def _reject_unknown_fields(
             "%s contains unknown field%s: %s"
             % (
                 context,
-                "s" if len(unknown) != 1 else "",
+                "s" if len(unknown) != 1 else "",  # don't forget your English grammar ;)
                 ", ".join(repr(name) for name in unknown),
             )
         )
@@ -302,7 +316,7 @@ def _list(value: Any, context: str) -> List[Any]:
     """Return a value as a list or raise a parse error.
 
     Args:
-        value: Value expected to be a JSON array.
+        value:   Value expected to be a JSON array.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -321,7 +335,7 @@ def _string(value: Any, context: str) -> str:
     """Return a value as a string or raise a parse error.
 
     Args:
-        value: Value expected to be a string.
+        value:   Value expected to be a string.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -340,7 +354,7 @@ def _optional_string(value: Any, context: str) -> Optional[str]:
     """Return an optional string or raise a parse error.
 
     Args:
-        value: None or a value expected to be a string.
+        value:   None or a value expected to be a string.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -359,7 +373,7 @@ def _optional_bool(value: Any, context: str) -> Optional[bool]:
     """Return an optional boolean or raise a parse error.
 
     Args:
-        value: None or a value expected to be a boolean.
+        value:   None or a value expected to be a boolean.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -380,7 +394,7 @@ def _optional_int(value: Any, context: str) -> Optional[int]:
     """Return an optional integer or raise a parse error.
 
     Args:
-        value: None or a value expected to be an integer.
+        value:   None or a value expected to be an integer.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -392,6 +406,7 @@ def _optional_int(value: Any, context: str) -> Optional[int]:
 
     if value is None:
         return None
+    # bool is a subclass of int, but JSON booleans are not numeric settings.
     if isinstance(value, bool) or not isinstance(value, int):
         raise TopologyParseError("%s must be an integer" % context)
     return value
@@ -401,8 +416,7 @@ def _optional_float(value: Any, context: str) -> Optional[float]:
     """Return an optional numeric value as float or raise a parse error.
 
     Args:
-        value: None or a value expected to be an integer or floating-point
+        value:   None or a value expected to be an integer or floating-point number.
-            number.
         context: Human-readable location used in the error message.
 
     Returns:
@@ -414,22 +428,42 @@ def _optional_float(value: Any, context: str) -> Optional[float]:
 
     if value is None:
         return None
+    # Reject booleans before accepting Python's integer and float types.
     if isinstance(value, bool) or not isinstance(value, (int, float)):
         raise TopologyParseError("%s must be a number" % context)
     return float(value)
 
+# ============================= Entity parsing =============================
 
 def _parse_interface(name: str, raw: Any, context: str) -> Interface:
     """Parse one interface definition.
 
     Args:
-        name: Logical interface tag taken from the JSON object key.
+        name:    Logical interface tag taken from the JSON object key.
-        raw: Raw JSON value containing interface properties.
+        raw:     Raw JSON value containing interface properties.
         context: Human-readable location used in error messages.
 
     Returns:
         Parsed Interface object.
 
+    Example:
+        Input (diagnostic context omitted):
+            name = "lan"
+            raw = {
+                "addressing": "static",
+                "address": "192.168.1.1/24",
+            }
+
+        Output:
+            Interface(
+                name="lan",
+                addressing=AddressingMode.STATIC,
+                address="192.168.1.1/24",
+                gateway=None,
+                mac=None,
+                mtu=None,
+            )
+
     Raises:
         TopologyParseError: If the interface cannot be represented.
     """
@@ -464,16 +498,34 @@ def _parse_interfaces(raw_node: JSONMapping, context: str) -> Optional[Dict[str,
 
     Args:
         raw_node: Raw JSON node object.
-        context: Human-readable node location used in error messages.
+        context:  Human-readable node location used in error messages.
 
     Returns:
-        None when the interfaces field is omitted, otherwise a dictionary of
+        - None when the interfaces field is omitted (dynamic), otherwise
-        logical interface tags to Interface objects.
+        - a dictionary of logical interface tags to Interface objects.
+
+    Example:
+        Each case shows the value passed as raw_node and the returned value,
+        the diagnostic context argument is omitted.
+        raw_node is the node object, not just its interfaces member.
+        Unrelated node fields are omitted from these examples.
+
+        Interface set      raw_node["interfaces"]        return
+        --------------------------------------------------------
+        Omitted:           {}                            None
+        Explicitly empty:  {"interfaces": {}}            {}
+        One declared:      {"interfaces": {"lan": {}}}   {"lan": Interface(name="lan")}
+
+        Omission preserves a dynamic interface set. An empty object preserves
+        a fixed pool containing zero interfaces.
+        Interface(name="lan") uses the model defaults, including NONE
+        addressing and no address, gateway, MAC, or MTU.
 
     Raises:
         TopologyParseError: If the interfaces field has an invalid shape.
     """
 
+    # Preserve the distinction between dynamic allocation and a fixed empty pool.
     if "interfaces" not in raw_node:
         return None
 
@@ -496,12 +548,23 @@ def _parse_node_settings(node_type: NodeType, raw: Any, context: str) -> NodeSet
 
     Args:
         node_type: Parsed semantic node type.
-        raw: Raw JSON settings object or None.
+        raw:       Raw JSON settings object or None.
-        context: Human-readable node location used in error messages.
+        context:   Human-readable node location used in error messages.
 
     Returns:
         Type-specific node settings object.
 
+    Example:
+        Input (Python values after JSON loading, diagnostic context omitted):
+            node_type = NodeType.ROUTER
+            raw = {"ip_forward": True, "rp_filter": False}
+
+        Output:
+            RouterSettings(ip_forward=True, rp_filter=False)
+
+        For node_type = NodeType.HOST and raw = {}, the output is
+        HostSettings().
+
     Raises:
         TopologyParseError: If the settings object has an invalid shape or
             contains values that cannot be represented by the selected type.
@@ -538,12 +601,34 @@ def _parse_node(raw: Any, index: int) -> Node:
     """Parse one node declaration.
 
     Args:
-        raw: Raw JSON node object.
+        raw:   Raw JSON node object.
         index: Node index in the source array, used in diagnostics.
 
     Returns:
         Parsed Node object.
 
+    Example:
+        Input raw (diagnostic index omitted):
+            {
+                "name": "h1",
+                "type": "host",
+                "interfaces": {"net0": {"addressing": "dhcp"}},
+            }
+
+        Output:
+            Node(
+                name="h1",
+                type=NodeType.HOST,
+                interfaces={
+                    "net0": Interface(
+                        name="net0", addressing=AddressingMode.DHCP,
+                    ),
+                },
+                settings=HostSettings(),
+            )
+
+        Unspecified Interface fields use their model defaults.
+
     Raises:
         TopologyParseError: If the node cannot be represented.
     """
@@ -578,7 +663,7 @@ def _parse_link_interface(value: Any, context: str) -> Union[str, LinkInterfaceS
     """Parse a link endpoint interface reference.
 
     Args:
-        value: Raw interface reference.
+        value:   Raw interface reference.
         context: Human-readable location used in error messages.
 
     Returns:
@@ -598,7 +683,7 @@ def _parse_link_endpoint(raw: Any, context: str) -> LinkEndpoint:
     """Parse one link endpoint.
 
     Args:
-        raw: Raw JSON endpoint object.
+        raw:     Raw JSON endpoint object.
         context: Human-readable location used in error messages.
 
     Returns:
@@ -624,7 +709,7 @@ def _parse_link_settings(raw: Any, context: str) -> LinkSettings:
     """Parse optional link-specific provisioning settings.
 
     Args:
-        raw: Raw JSON settings object or None.
+        raw:     Raw JSON settings object or None.
         context: Human-readable link location used in error messages.
 
     Returns:
@@ -665,12 +750,35 @@ def _parse_link(raw: Any, index: int) -> Link:
     """Parse one link declaration.
 
     Args:
-        raw: Raw JSON link object.
+        raw:   Raw JSON link object.
         index: Link index in the source array, used in diagnostics.
 
     Returns:
         Parsed Link object.
 
+    Example:
+        Input raw (diagnostic index omitted):
+            {
+                "endpoints": [
+                    {"node": "h1", "interface": "net0"},
+                    {"node": "s1", "interface": "auto"},
+                ],
+            }
+
+        Output:
+            Link(
+                endpoints=(
+                    LinkEndpoint(node="h1", interface="net0"),
+                    LinkEndpoint(
+                        node="s1", interface=LinkInterfaceSelector.AUTO,
+                    ),
+                ),
+            )
+    Note:
+        - Omitted name and settings use the Link defaults.
+        - Parsing converts the endpoint list to a tuple and recognizes AUTO.
+        - Validation checks whether the referenced nodes and interfaces exist.
+
     Raises:
         TopologyParseError: If the link cannot be represented.
     """
@@ -712,7 +820,7 @@ def _parse_service_interface(
     """Parse a service interface binding.
 
     Args:
-        value: Raw service interface reference.
+        value:   Raw service interface reference.
         context: Human-readable location used in error messages.
 
     Returns:
@@ -735,12 +843,32 @@ def _parse_dhcp_server_settings(raw: Any, context: str) -> DHCPServerSettings:
     """Parse DHCP-server-specific settings.
 
     Args:
-        raw: Raw JSON DHCP server settings object.
+        raw:     Raw JSON DHCP server settings object.
         context: Human-readable location used in error messages.
 
     Returns:
         Parsed DHCPServerSettings object.
 
+    Example:
+        Input raw (diagnostic context omitted):
+            {
+                "range": {
+                    "start": "192.168.1.100",
+                    "end": "192.168.1.200",
+                },
+                "gateway": "192.168.1.1",
+            }
+
+        Output:
+            DHCPServerSettings(
+                address_range=DHCPRange(
+                    start="192.168.1.100", end="192.168.1.200",
+                ),
+                gateway="192.168.1.1",
+            )
+
+        The JSON range object becomes the typed address_range field.
+
     Raises:
         TopologyParseError: If required structural fields are missing or have
             incompatible JSON types.
@@ -767,12 +895,43 @@ def _parse_service(raw: Any, index: int) -> Service:
     """Parse one service declaration.
 
     Args:
-        raw: Raw JSON service object.
+        raw:   Raw JSON service object.
         index: Service index in the source array, used in diagnostics.
 
     Returns:
         Parsed Service object.
 
+    Example:
+        Input raw (diagnostic index omitted):
+            {
+                "type": "dhcp-server",
+                "node": "r0",
+                "interface": "lan",
+                "settings": {
+                    "range": {
+                        "start": "192.168.1.100",
+                        "end": "192.168.1.200",
+                    },
+                    "gateway": "192.168.1.1",
+                },
+            }
+
+        Output:
+            Service(
+                type=ServiceType.DHCP_SERVER,
+                node="r0",
+                interface="lan",
+                settings=DHCPServerSettings(
+                    address_range=DHCPRange(
+                        start="192.168.1.100", end="192.168.1.200",
+                    ),
+                    gateway="192.168.1.1",
+                ),
+            )
+
+        Binding fields remain separate from service settings.
+        Parsing preserves the references. Validation checks their validity.
+
     Raises:
         TopologyParseError: If the service cannot be represented.
     """
@@ -814,6 +973,10 @@ def _parse_service(raw: Any, index: int) -> Service:
     )
 
 
+
+
+# ============================ Public interface ============================
+
 def parse_topology(raw: Mapping[str, Any]) -> Topology:
     """Parse a raw JSON dictionary into the typed topology model.
 
@@ -828,8 +991,8 @@ def parse_topology(raw: Mapping[str, Any]) -> Topology:
             topology grammar.
 
     Notes:
-        This function intentionally does not validate cross references such as
+        This function intentionally does not validate cross-references such as
-        whether a link references an existing node.  Those checks belong to
+        whether a link references an existing node. Those checks belong to
         the separate validation stage.
     """
 
@@ -858,6 +1021,9 @@ def parse_topology(raw: Mapping[str, Any]) -> Topology:
     return Topology(nodes=nodes, links=links, services=services)
 
 
+
+# =============================== Self-test ===============================
+
 def _self_test() -> None:
     """Run a small smoke test against the public parse_topology() interface."""
 

source/topology_plan.py

@@ -32,6 +32,8 @@ from topology_parser import (
 )
 
 
+# ========================== Execution plan model ==========================
+
 class TopologyPlanError(ValueError):
     """Raised when a validated topology cannot be lowered into a plan."""
 
@@ -182,6 +184,12 @@ class PlannedService:
 class ExecutionPlan:
     """Contain the complete, fully resolved execution plan.
 
+    Ordered tuples of frozen operation objects capture the result of planning.
+    They carry concrete names and configuration into the renderer without
+    exposing the mutable allocation context or the source model objects.
+    The renderer emits the operations in lifecycle order: construction,
+    configuration, and service startup.
+
     Args:
         nodes: Node creation operations in declaration order.
         links: Link creation operations in declaration order.
@@ -201,21 +209,45 @@ class ExecutionPlan:
     services: Tuple[PlannedService, ...]
 
 
+# ======================== Mutable planning context ========================
+
 @dataclass
 class _PlanningContext:
     """Hold mutable state used while lowering a topology.
 
+    _build_context() initializes node lookup, reservations, free pools, and
+    counters from the validated topology.
+    During _plan_links(), allocation helpers consume pool entries, advance
+    counters, and record interface mappings.
+    Interface, node-setting, and service planning then read those mappings.
+
+    A logical interface is identified by (node_name, logical_name), since tags
+    need only be unique within their owning node.
+    interface_names and interface_models acquire the same keys on allocation:
+    one supplies the backend name, and the other supplies its configuration.
+    A reservation alone does not create an entry in either mapping.
+
     Args:
-        nodes: Nodes indexed by logical name.
+        nodes: Source nodes indexed by name, safe after uniqueness validation.
-        reserved_interfaces: Explicitly referenced logical interfaces per node.
+        reserved_interfaces: All explicit link references per node, used to
-        free_interfaces: Remaining declared interfaces available to AUTO.
+            construct free pools and retained unchanged during allocation.
-        dynamic_interface_counters: Synthetic logical-name counters for nodes
+        free_interfaces: Ordered lists of unreserved declared tags for fixed
-            whose interface sets were omitted.
+            pools; AUTO removes the first entry.
-        physical_interface_counters: Concrete eth-index counters per node.
+            An empty list means exhaustion; dynamic nodes have no entry.
-        interface_names: Mapping from resolved logical interfaces to concrete
+        dynamic_interface_counters: Next synthetic logical-tag indices, such
-            Linux/Mininet interface names.
+            as auto0; advanced only for nodes with omitted interface sets.
-        interface_models: Mapping from resolved logical interfaces to their
+        physical_interface_counters: Next concrete eth-index per node;
-            source Interface objects.
+            advanced for every allocation, including explicit selections.
+        interface_names: Allocated (node, logical tag) pairs mapped to concrete
+            Linux/Mininet names, in interface-configuration order.
+        interface_models: The same allocated keys mapped to source Interface
+            objects or default models created for dynamic interfaces.
+
+    Example:
+        A fixed pool declared as p1, p2, uplink with an explicit uplink
+        reference starts with free_interfaces containing [p1, p2].
+        If the first endpoint for that node uses AUTO, it consumes p1 and
+        receives <node>-eth0, recording both mappings for (node, p1).
     """
 
     nodes: Dict[str, Node]
@@ -227,9 +259,15 @@ class _PlanningContext:
     interface_models: Dict[Tuple[str, str], Interface]
 
 
+# ========================= Context initialization =========================
+
 def _build_context(topology: Topology) -> _PlanningContext:
     """Create planning state and reserve all explicit link interfaces.
 
+    Scan every link before constructing the free-interface pools so an AUTO
+    endpoint cannot consume an interface explicitly referenced by a later link.
+    Preserve declaration order in each pool for deterministic allocation.
+
     Args:
         topology: Validated topology to lower.
 
@@ -267,6 +305,8 @@ def _build_context(topology: Topology) -> _PlanningContext:
     )
 
 
+# ========================= Node and link planning =========================
+
 def _plan_nodes(topology: Topology) -> Tuple[PlannedNode, ...]:
     """Lower topology nodes into concrete node creation operations.
 
@@ -296,6 +336,11 @@ def _allocate_logical_interface(
 ) -> Tuple[str, Interface]:
     """Resolve one link endpoint to a concrete logical interface.
 
+    Explicit tags look up their declared models without consuming a free pool.
+    AUTO consumes the first available tag for a fixed pool, or creates a
+    synthetic tag and an unconfigured model for a dynamic pool.
+    Concrete backend names are assigned separately by physical allocation.
+
     Args:
         node: Node that owns the endpoint.
         selector: Explicit interface tag or AUTO selector.
@@ -373,6 +418,7 @@ def _allocate_physical_interface(
     context.physical_interface_counters[node_name] = index + 1
 
     interface_name = "%s-eth%d" % (node_name, index)
+    # These mappings let later stages recover both the name and configuration.
     context.interface_names[key] = interface_name
     context.interface_models[key] = interface
 
@@ -385,6 +431,11 @@ def _plan_links(
 ) -> Tuple[PlannedLink, ...]:
     """Resolve all link endpoints and concrete interface names.
 
+    Traverse links and their endpoints in source order, resolving each logical
+    selection before assigning its backend name.
+    Allocation records mappings in the shared context for subsequent interface,
+    node-setting, and service planning, so traversal order determines naming.
+
     Args:
         topology: Validated topology to lower.
         context: Mutable planning context.
@@ -436,6 +487,8 @@ def _plan_links(
     return tuple(planned_links)
 
 
+# ==================== Interface and node configuration ====================
+
 def _interface_requires_materialization(interface: Interface) -> bool:
     """Return whether an unused declared interface carries configuration.
 
@@ -462,6 +515,12 @@ def _plan_interfaces(
 ) -> Tuple[PlannedInterface, ...]:
     """Create interface-configuration operations for materialized interfaces.
 
+    First reject configured declarations absent from the allocation mappings:
+    Mininet creates these interfaces through links, so there would be no
+    concrete interface on which to apply their configuration.
+    Empty unused declarations need no operation and may remain unallocated.
+    Then pair each allocated name with its model in allocation order.
+
     Args:
         topology: Validated topology to lower.
         context: Planning context containing resolved interface mappings.
@@ -581,6 +640,8 @@ def _plan_node_settings(
     return tuple(planned)
 
 
+# ============================ Service planning ============================
+
 def _resolve_service_logical_interface(
     service: Service,
     node: Node,
@@ -694,6 +755,8 @@ def _plan_services(
     return tuple(planned)
 
 
+# ============================ Public interface ============================
+
 def plan(topology: Topology) -> ExecutionPlan:
     """Lower a validated topology into a fully resolved execution plan.
 
@@ -730,6 +793,8 @@ def plan(topology: Topology) -> ExecutionPlan:
     )
 
 
+# =============================== Self-test ===============================
+
 def _self_test() -> None:
     """Run a smoke test against the public plan() interface."""
 

source/topology_renderer.py

@@ -24,6 +24,8 @@ from topology_plan import (
 )
 
 
+# =========================== Rendering helpers ===========================
+
 def _python_string(value: str) -> str:
     """Return a safe Python string literal.
 
@@ -136,17 +138,11 @@ def _render_interface_configuration(interface: PlannedInterface) -> List[str]:
         )
 
     if interface.addressing is AddressingMode.STATIC:
-        if interface.address is None:
-            raise ValueError(
-                "planned static interface %s:%s has no address"
-                % (interface.node, interface.logical_interface)
-            )
-
         lines.append(
             "        _node_cmd(%s, 'ip', 'addr', 'add', %s, 'dev', %s)"
             % (
                 node,
-                _python_string(interface.address),
+                repr(interface.address),
                 name,
             )
         )
@@ -193,6 +189,12 @@ def _render_gateway_configuration(interface: PlannedInterface) -> List[str]:
 def _render_service_start(service: PlannedService, index: int) -> List[str]:
     """Render startup code for one planned service.
 
+    Construct dnsmasq arguments from the resolved binding and DHCP settings,
+    using the service index for lease, PID, and log filenames.
+    Emit commands that remove previous lease and PID files, launch the daemon
+    in the background, and record its shell PID for later cleanup.
+    The emitted startup sequence does not check daemon readiness.
+
     Args:
         service: Fully resolved service operation.
         index: Stable service index used for temporary runtime files.
@@ -200,19 +202,8 @@ def _render_service_start(service: PlannedService, index: int) -> List[str]:
     Returns:
         Generated Python source lines that start and track the service.
 
-    Raises:
-        ValueError: If the plan contains an unsupported service type or
-            incompatible settings object.
     """
 
-    if service.type is not ServiceType.DHCP_SERVER:
-        raise ValueError(
-            "unsupported planned service type %r" % service.type.value
-        )
-
-    if not isinstance(service.settings, PlannedDHCPServerSettings):
-        raise ValueError("DHCP service has incompatible planned settings")
-
     node = "nodes[%s]" % _python_string(service.node)
     lease_file = "/tmp/mininet-dnsmasq-%d.leases" % index
     pid_file = "/tmp/mininet-dnsmasq-%d.pid" % index
@@ -240,6 +231,12 @@ def _render_service_start(service: PlannedService, index: int) -> List[str]:
     rendered_args = ", ".join(_python_string(arg) for arg in args)
 
     return [
+        "        _node_cmd(%s, 'rm', '-f', %s, %s)"
+        % (
+            node,
+            _python_string(lease_file),
+            _python_string(pid_file),
+        ),
         "        pid = _start_background(",
         "            %s," % node,
         "            [%s]," % rendered_args,
@@ -249,9 +246,18 @@ def _render_service_start(service: PlannedService, index: int) -> List[str]:
     ]
 
 
+# ============================ Public interface ============================
+
 def render_python(plan: ExecutionPlan) -> str:
     """Render an execution plan as a complete executable Python program.
 
+    Assemble source lines for runtime helpers and the network lifecycle.
+    Emit construction first so interfaces exist before configuration; emit
+    addresses before default routes and services that depend on them.
+    Finish with the interactive CLI and a finally block that attempts tracked
+    service cleanup followed by network shutdown.
+    Rendering itself only produces text and does not execute these operations.
+
     Args:
         plan: Fully resolved execution plan returned by topology_plan.plan().
 
@@ -259,9 +265,6 @@ def render_python(plan: ExecutionPlan) -> str:
         Python source code that creates the network, applies configuration,
         starts services, opens the Mininet CLI, and performs structured cleanup.
 
-    Raises:
-        ValueError: If the supplied plan contains an operation that this
-            renderer cannot serialize.
     """
 
     lines: List[str] = [
@@ -320,7 +323,7 @@ def render_python(plan: ExecutionPlan) -> str:
                     _python_string(node.name),
                 )
             )
-        elif node.type is NodeType.SWITCH:
+        else:
             lines.append(
                 "        nodes[%s] = net.addSwitch(%s, failMode=%r)"
                 % (
@@ -329,8 +332,6 @@ def render_python(plan: ExecutionPlan) -> str:
                     node.switch_fail_mode,
                 )
             )
-        else:
-            raise ValueError("unsupported planned node type %r" % node.type)
 
     lines.extend(["", "        # Create links."])
     for link in plan.links:
@@ -393,6 +394,8 @@ def render_python(plan: ExecutionPlan) -> str:
     return "\n".join(lines)
 
 
+# =============================== Self-test ===============================
+
 def _self_test() -> None:
     """Run a smoke test against the public render_python() interface."""
 
@@ -474,6 +477,7 @@ def _self_test() -> None:
     assert "net.addLink(" in source
     assert "cls=TCLink" in source
     assert "dnsmasq" in source
+    assert "rm', '-f', '/tmp/mininet-dnsmasq-0.leases'" in source
     assert "CLI(net)" in source
     assert "dhclient" in source
 

source/topology_validator.py

@@ -3,11 +3,9 @@
 This module implements the validation stage of the topology pipeline.
 
 The parser answers:
-
     "Can this JSON be represented by the topology grammar?"
 
 The validator answers:
-
     "Does the parsed topology describe a coherent network?"
 
 Validation is intentionally independent of Mininet.  It does not create
@@ -18,11 +16,11 @@ validation fails.
 Author: Christos Choutouridis <cchoutou@ece.auth.gr>
 """
 
-from dataclasses import dataclass
+from   dataclasses import dataclass
 import ipaddress
 import math
 import re
-from typing import Dict, List, Optional, Sequence, Set, Tuple
+from   typing import Dict, List, Optional, Sequence, Set, Tuple
 
 from topology_parser import (
     AddressingMode,
@@ -43,6 +41,8 @@ from topology_parser import (
 )
 
 
+# ========================== Validation constants ==========================
+
 _RESERVED_INTERFACE_TAGS = {
     LinkInterfaceSelector.AUTO.value,
     ServiceInterfaceSelector.ALL.value,
@@ -53,6 +53,8 @@ _MAC_ADDRESS_RE = re.compile(
 )
 
 
+# ====================== Diagnostics and lookup state ======================
+
 @dataclass(frozen=True)
 class ValidationIssue:
     """Describe one semantic topology validation failure.
@@ -63,7 +65,7 @@ class ValidationIssue:
     """
 
     location: str
-    message: str
+    message:  str
 
 
 class TopologyValidationError(ValueError):
@@ -96,7 +98,7 @@ class TopologyValidationError(ValueError):
         count = len(self.issues)
         header = "%d topology validation error%s" % (
             count,
-            "" if count == 1 else "s",
+            "" if count == 1 else "s", # ;)
         )
 
         lines = [header]
@@ -110,26 +112,57 @@ class TopologyValidationError(ValueError):
 class _NodeIndex:
     """Hold node lookup information prepared for validation.
 
+    _build_node_index() retains the first declaration for each nonempty name
+    and records repeated names separately while reporting duplicate issues.
+    Link and service checks consult duplicate_names before resolving a known
+    node, avoiding secondary diagnostics based on an ambiguous declaration.
+
     Args:
-        nodes: Unique node declarations indexed by name.
+        nodes: First declaration for each distinct nonempty node name.
         duplicate_names: Node names that were declared more than once.
+
+    Example:
+        Suppose the source list contains three Node objects:
+            topology.nodes = [first_h1, s1, second_h1]
+            first_h1.name = "h1"
+            s1.name = "s1"
+            second_h1.name = "h1"
+
+        The resulting lookup has this shape:
+            node_index = _NodeIndex(
+                nodes={"h1": first_h1, "s1": s1},
+                duplicate_names={"h1"},
+            )
+
+        Dictionary keys are logical node names, and values reference the
+        original Node objects, not copies or positions in the source list.
+        node_index.nodes["s1"] therefore gives the s1 object directly.
+        The duplicate set contains names only; it is empty for unique names.
+
+        Membership in nodes means a declaration exists, not that it is unique.
+        Although nodes["h1"] retains first_h1, duplicate_names marks that
+        reference as ambiguous so link and service checks skip resolving it.
+        The original topology.nodes list still contains both h1 declarations.
+        Empty names are reported as issues and excluded from both collections.
     """
 
-    nodes: Dict[str, Node]
+    nodes:           Dict[str, Node]
     duplicate_names: Set[str]
 
 
+# =========================== Validation helpers ===========================
+
 def _add_issue(
-    issues: List[ValidationIssue],
+    issues:   List[ValidationIssue],
     location: str,
-    message: str,
+    message:  str,
 ) -> None:
     """Append one validation issue.
 
     Args:
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
         location: Logical location associated with the failure.
-        message: Human-readable description of the failure.
+        message:  Human-readable description of the failure.
     """
 
     issues.append(ValidationIssue(location=location, message=message))
@@ -143,13 +176,21 @@ def _build_node_index(
 
     Args:
         topology: Parsed topology being validated.
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
 
     Returns:
         Node lookup information for later validation passes.
+
+    Notes:
+        The returned _NodeIndex holds name-to-object lookup and ambiguity
+        information; validation issues are appended to the supplied list.
+        first_index is a temporary name-to-source-position map used to point
+        duplicate diagnostics back to the first declaration.
+        It is not part of the returned index, whose shape is illustrated in
+        the _NodeIndex class docstring.
     """
 
-    nodes: Dict[str, Node] = {}
+    nodes:       Dict[str, Node] = {}
     first_index: Dict[str, int] = {}
     duplicate_names: Set[str] = set()
 
@@ -179,17 +220,21 @@ def _build_node_index(
     )
 
 
+
+# ============================ Validation core =============================
+
+
 def _validate_node_settings(
-    node: Node,
+    node:     Node,
     location: str,
-    issues: List[ValidationIssue],
+    issues:   List[ValidationIssue],
 ) -> None:
     """Validate that a node carries settings matching its semantic type.
 
     Args:
-        node: Node whose settings object is checked.
+        node:     Node whose settings object is checked.
-        location: Logical location of the node.
+        location: Logical location of the node (where node data came from).
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
     """
 
     expected_type = {
@@ -206,20 +251,46 @@ def _validate_node_settings(
         )
 
 
-def _parse_ipv4_interface(
+def _validate_ipv4_interface(
-    value: str,
+    value:    str,
     location: str,
-    issues: List[ValidationIssue],
+    issues:   List[ValidationIssue],
 ) -> Optional[ipaddress.IPv4Interface]:
-    """Parse and validate one IPv4 CIDR interface address.
+    """Validate one IPv4 CIDR interface address.
+
+    Require an explicit prefix and convert the string to an IPv4Interface for
+    subsequent subnet checks.
+    Invalid syntax or an unsupported address family records a validation issue
+    at the supplied location instead of raising a parsing exception.
 
     Args:
-        value: Address string expected to contain an IPv4 address and prefix.
+        value:    Address string expected to contain an IPv4 address and prefix.
-        location: Logical location associated with the address.
+        location: Logical location associated with the address(where address string--value-- came from).
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
 
     Returns:
-        Parsed IPv4Interface on success, otherwise None.
+        IPv4Interface on success, otherwise None after recording an issue.
+
+    Example:
+        Input:
+            value = "192.168.1.10/24"
+            location = "nodes[0].interfaces.lan.address"
+            issues = []
+
+        Output (result names the return value):
+            result = ipaddress.IPv4Interface("192.168.1.10/24")
+            issues = []
+
+        With value = "192.168.1.10" and a fresh empty issues list:
+            result = None
+            issues = [
+                ValidationIssue(
+                    location="nodes[0].interfaces.lan.address",
+                    message="static address must use CIDR notation",
+                ),
+            ]
+
+        Failure appends to the supplied list rather than raising an exception.
     """
 
     if "/" not in value:
@@ -243,20 +314,47 @@ def _parse_ipv4_interface(
     return parsed
 
 
-def _parse_ipv4_address(
+def _validate_ipv4_address(
-    value: str,
+    value:    str,
     location: str,
-    issues: List[ValidationIssue],
+    issues:   List[ValidationIssue],
 ) -> Optional[ipaddress.IPv4Address]:
-    """Parse and validate one IPv4 address without a prefix.
+    """Validate one IPv4 address without a prefix.
+
+    Convert the string to an IPv4Address for subsequent semantic checks.
+    Invalid syntax or an unsupported address family records a validation issue
+    at the supplied location instead of raising a parsing exception.
 
     Args:
-        value: Address string expected to contain one IPv4 address.
+        value:    Address string expected to contain one IPv4 address.
-        location: Logical location associated with the address.
+        location: Logical location associated with the address (where value string came from).
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
 
     Returns:
-        Parsed IPv4Address on success, otherwise None.
+        IPv4Address on success, otherwise None after recording an issue.
+
+    Example:
+        Input:
+            value = "192.168.1.1"
+            location = "nodes[0].interfaces.lan.gateway"
+            issues = []
+
+        Output (result names the return value):
+            result = ipaddress.IPv4Address("192.168.1.1")
+            issues = []
+
+        With value = "::1" and a fresh empty issues list:
+            result = None
+            issues = [
+                ValidationIssue(
+                    location="nodes[0].interfaces.lan.gateway",
+                    message="only IPv4 addresses are supported",
+                ),
+            ]
+
+        A prefixed value such as "192.168.1.1/24" also returns None and
+        appends an invalid-IPv4-address issue, since this helper expects
+        an address without a prefix.
     """
 
     try:
@@ -273,18 +371,18 @@ def _parse_ipv4_address(
 
 
 def _validate_interface(
-    node: Node,
+    node:      Node,
     interface: Interface,
-    location: str,
+    location:  str,
-    issues: List[ValidationIssue],
+    issues:    List[ValidationIssue],
 ) -> None:
     """Validate one declared logical interface.
 
     Args:
-        node: Node that owns the interface.
+        node:      Node that owns the interface.
         interface: Interface being validated.
-        location: Logical location of the interface.
+        location:  Logical location of the interface (where the interface data came from).
-        issues: Mutable list receiving validation failures.
+        issues:    Mutable list receiving validation failures.
     """
 
     if not interface.name:
@@ -314,16 +412,18 @@ def _validate_interface(
                 "static addressing requires an address",
             )
         else:
-            parsed_address = _parse_ipv4_interface(
+            parsed_address = _validate_ipv4_interface(
                 interface.address,
                 location + ".address",
                 issues,
             )
 
+            # For subnets larger than two(2) addresses, reject assigning the network or broadcast
+            # address to an interface.
             if parsed_address is not None:
                 network = parsed_address.network
                 if (
-                    network.num_addresses > 2
+                    network.num_addresses > 2 # /30  and up
                     and parsed_address.ip in {network.network_address, network.broadcast_address}
                 ):
                     _add_issue(
@@ -333,7 +433,7 @@ def _validate_interface(
                     )
 
         if interface.gateway is not None:
-            parsed_gateway = _parse_ipv4_address(
+            parsed_gateway = _validate_ipv4_address(
                 interface.gateway,
                 location + ".gateway",
                 issues,
@@ -353,6 +453,7 @@ def _validate_interface(
                         "gateway must not be the interface's own address",
                     )
                 elif (
+                    # Same here, /30 and up
                     parsed_address.network.num_addresses > 2
                     and parsed_gateway
                     in {
@@ -398,7 +499,7 @@ def _validate_interface(
 
 def _validate_nodes(
     topology: Topology,
-    issues: List[ValidationIssue],
+    issues:   List[ValidationIssue],
 ) -> _NodeIndex:
     """Validate node declarations and their local interface configuration.
 
@@ -413,6 +514,7 @@ def _validate_nodes(
     node_index = _build_node_index(topology, issues)
 
     for node_number, node in enumerate(topology.nodes):
+        # keep node's location for error reporting
         node_location = "nodes[%d]" % node_number
 
         _validate_node_settings(node, node_location, issues)
@@ -423,12 +525,14 @@ def _validate_nodes(
         gateway_locations: List[str] = []
 
         for interface_name, interface in node.interfaces.items():
+            # keep interface's location for error reporting
             interface_location = "%s.interfaces.%s" % (
                 node_location,
                 interface_name,
             )
 
             if interface.name != interface_name:
+                # yes I have name inside the interface
                 _add_issue(
                     issues,
                     interface_location,
@@ -437,10 +541,7 @@ def _validate_nodes(
                 )
 
             _validate_interface(
-                node,
+                node, interface, interface_location, issues
-                interface,
-                interface_location,
-                issues,
             )
 
             if interface.gateway is not None:
@@ -457,24 +558,26 @@ def _validate_nodes(
     return node_index
 
 
+# ============================ Link validation ============================
+
 def _validate_link_settings(
     settings: LinkSettings,
     location: str,
-    issues: List[ValidationIssue],
+    issues:   List[ValidationIssue],
 ) -> None:
     """Validate optional link provisioning settings.
 
     Args:
         settings: Link settings being validated.
-        location: Logical location of the settings object.
+        location: Logical location of the settings object (where the settings data came from).
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
     """
 
     numeric_settings = {
         "bandwidth_mbps": settings.bandwidth_mbps,
-        "delay_ms": settings.delay_ms,
+        "delay_ms":       settings.delay_ms,
-        "loss_percent": settings.loss_percent,
+        "loss_percent":   settings.loss_percent,
-        "jitter_ms": settings.jitter_ms,
+        "jitter_ms":      settings.jitter_ms,
     }
 
     for name, value in numeric_settings.items():
@@ -525,7 +628,7 @@ def _validate_link_names(
 
     Args:
         topology: Parsed topology being validated.
-        issues: Mutable list receiving validation failures.
+        issues:   Mutable list receiving validation failures.
     """
 
     first_index: Dict[str, int] = {}
@@ -559,10 +662,28 @@ def _validate_links(
 ) -> None:
     """Validate links, endpoint references, and interface allocation capacity.
 
+    First collect valid explicit interface usage and AUTO requests while
+    checking endpoint references and rejecting explicit reuse.
+    Then compare each fixed pool's AUTO demand with its remaining capacity
+    after all explicit reservations are known.
+    This checks allocation feasibility without selecting concrete interfaces;
+    dynamic pools need no capacity check.
+
     Args:
-        topology: Parsed topology being validated.
+        topology:   Parsed topology being validated.
         node_index: Node lookup information prepared by node validation.
-        issues: Mutable list receiving validation failures.
+        issues:     Mutable list receiving validation failures.
+
+    Example:
+        For otherwise valid links involving a fixed pool on an example switch s1:
+            Declared interfaces:  p1, p2
+            Explicit reservation: p2
+            AUTO requests:        2
+            Remaining capacity:   1
+            Result:               None; one capacity issue appended
+
+        With only one AUTO request, no capacity issue is appended.
+        Neither case consumes the pool or assigns an interface to AUTO.
     """
 
     _validate_link_names(topology, issues)
@@ -578,6 +699,7 @@ def _validate_links(
         )
 
         for endpoint_index, endpoint in enumerate(link.endpoints):
+            # keep endpoint's location for error reporting
             endpoint_location = "links[%d].endpoints[%d]" % (
                 link_index,
                 endpoint_index,
@@ -651,9 +773,11 @@ def _validate_links(
 
             used_explicit[key] = endpoint_location
 
+    # Count AUTO capacity only after collecting every explicit reservation.
     for node_name, request_locations in auto_requests.items():
         node = node_index.nodes[node_name]
 
+        # Dynamic check
         if node.interfaces is None:
             continue
 
@@ -670,39 +794,58 @@ def _validate_links(
                 issues,
                 "links",
                 "node %r has %d automatic interface request%s but only %d "
-                "unused declared interface%s remain%s"
+                "unused declared interface%s remain%s" % (
-                % (
                     node_name,
                     len(request_locations),
                     "" if len(request_locations) == 1 else "s",
                     free_count,
                     "" if free_count == 1 else "s",
-                    "; %d request%s cannot be satisfied"
+                    "; %d request%s cannot be satisfied" % (
-                    % (
                         shortage,
                         "" if shortage == 1 else "s",
                     ),
                 ),
+                # Ok, laugh as you want, but I like my plurals!
             )
 
 
+# =========================== Service validation ===========================
+
 def _resolve_service_interface(
-    service: Service,
+    service:          Service,
     service_location: str,
-    node: Node,
+    node:             Node,
-    issues: List[ValidationIssue],
+    issues:           List[ValidationIssue],
 ) -> Optional[Interface]:
     """Resolve a service binding to one declared interface when possible.
 
+    Explicit tags select a declared model directly; AUTO requires exactly one
+    declared interface with static addressing.
+    Service AUTO never allocates an interface or consumes a link's free pool.
+    ALL is left unresolved for the service-specific validator to diagnose.
+
     Args:
-        service: Service whose interface binding is resolved.
+        service:          Service whose interface binding is resolved.
-        service_location: Logical location of the service.
+        service_location: Logical location of the service (whre service data came from).
-        node: Node on which the service runs.
+        node:             Node on which the service runs.
-        issues: Mutable list receiving validation failures.
+        issues:           Mutable list receiving validation failures.
 
     Returns:
         Resolved Interface when the binding identifies exactly one valid
         interface, otherwise None.
+
+    Example:
+        With service.interface = ServiceInterfaceSelector.AUTO and issues = []:
+            Declared static ifaces: lan
+            Result:                 node.interfaces["lan"]
+            Issues:                 unchanged
+
+        With two declared static interfaces, lan and wan:
+            Result: None
+            Issues: one ambiguity issue appended at the service interface
+
+        These scenarios describe selection only; address validity and link
+        attachment are checked elsewhere in the pipeline.
     """
 
     selector = service.interface
@@ -772,18 +915,34 @@ def _resolve_service_interface(
 def _validate_dhcp_server(
     service: Service,
     service_location: str,
-    node: Node,
     interface: Optional[Interface],
     issues: List[ValidationIssue],
 ) -> None:
     """Validate DHCP-server-specific semantics.
 
+    Check address syntax and range ordering independently of the binding, so
+    those diagnostics remain available even when interface resolution fails.
+    With a usable static binding, check subnet membership and reserved subnet
+    addresses, then exclude the server and advertised gateway from the pool.
+    Skip checks whose required address or binding could not be parsed.
+
     Args:
-        service: DHCP server service being validated.
+        service:          DHCP server service being validated.
-        service_location: Logical location of the service.
+        service_location: Logical location of the service (where service data came from).
-        node: Node on which the service runs.
+        interface:        Resolved service interface, if available.
-        interface: Resolved service interface, if available.
+        issues:           Mutable list receiving validation failures.
-        issues: Mutable list receiving validation failures.
+
+    Example:
+        For a valid static binding and otherwise valid service settings:
+            Server interface:   192.168.1.1/24
+            Advertised gateway: omitted
+            Pool:               192.168.1.100 through 192.168.1.200
+            Result:             None; no issues appended
+
+        Changing the pool to 192.168.1.1 through 192.168.1.200 still keeps
+        it inside the subnet, but includes the server's own address.
+        The result remains None, with one server-address exclusion issue
+        appended to the supplied issues list.
     """
 
     if service.interface is ServiceInterfaceSelector.ALL:
@@ -801,12 +960,12 @@ def _validate_dhcp_server(
         )
         return
 
-    start = _parse_ipv4_address(
+    start = _validate_ipv4_address(
         service.settings.address_range.start,
         service_location + ".settings.range.start",
         issues,
     )
-    end = _parse_ipv4_address(
+    end = _validate_ipv4_address(
         service.settings.address_range.end,
         service_location + ".settings.range.end",
         issues,
@@ -821,7 +980,7 @@ def _validate_dhcp_server(
 
     gateway: Optional[ipaddress.IPv4Address] = None
     if service.settings.gateway is not None:
-        gateway = _parse_ipv4_address(
+        gateway = _validate_ipv4_address(
             service.settings.gateway,
             service_location + ".settings.gateway",
             issues,
@@ -842,7 +1001,7 @@ def _validate_dhcp_server(
         # The interface validator reports this as well.
         return
 
-    parsed_interface = _parse_ipv4_interface(
+    parsed_interface = _validate_ipv4_interface(
         interface.address,
         service_location + ".interface",
         issues,
@@ -962,18 +1121,45 @@ def _validate_services(
             _validate_dhcp_server(
                 service,
                 location,
-                node,
                 interface,
                 issues,
             )
 
 
+# ============================ Public interface ============================
+
 def validate(topology: Topology) -> None:
     """Validate the semantic consistency of a parsed topology.
 
     Args:
         topology: Parsed topology produced by topology_parser.parse_topology().
 
+    Returns:
+        None when no semantic issues are found.
+
+    Example:
+        Input constructed through the public parser:
+            topology = parse_topology({
+                "nodes": [{"name": "h1", "type": "host"}],
+            })
+
+        Output:
+            result = validate(topology)
+            result is None
+
+        Invalid input:
+            topology = parse_topology({
+                "nodes": [
+                    {"name": "h1", "type": "host"},
+                    {"name": "h1", "type": "host"},
+                ],
+            })
+
+        validate(topology) raises TopologyValidationError instead of returning.
+        The exception's issues tuple contains one ValidationIssue with
+        location="nodes[1].name" and a duplicate-node-name message.
+        When multiple issues are discovered, they share one exception.
+
     Raises:
         TopologyValidationError: If one or more semantic consistency errors are
             discovered.
@@ -994,6 +1180,8 @@ def validate(topology: Topology) -> None:
         raise TopologyValidationError(issues)
 
 
+# =============================== Self-test ===============================
+
 def _self_test() -> None:
     """Run smoke tests against the public validate() interface."""