How harvard-cs145/routing works
1. Repository purpose
- This is a Python networking project focused on intra-domain routing.
- The only required algorithm implementations are in DVrouter.py and/or LSrouter.py.
2. Core architecture
- The repo is built around a network simulator that instantiates one router object per router node and connects them with simulated links.
- The simulator drives each router by calling event handlers such as packet arrival, link add/remove, and timer/heartbeat events.
3. Main runtime boundary
- The simulator treats each router as an independent actor and runs them in separate threads.
- That makes the routing logic decentralized: routers only know their local state plus messages received from neighbors.
4. Packet and message flow
- packet.py defines the packet model used both for normal client traffic and for routing control messages.
- Client packets are used for traceroute-like path verification; routing packets are sent between routers with kind == Packet.ROUTING and JSON-string content.
- A key boundary is that router code may manipulate packet fields, but must not touch the packet route-tracking internals.
5. Router abstraction
- router.py provides the base Router interface that both algorithm implementations extend.
- The important overridable hooks are __init__, handle_packet, handle_new_link, handle_remove_link, handle_time, and optionally __repr__.
- Router implementations are expected to use only the base send() method and their own addr field from the base class.
6. Distance-vector subsystem
- DVrouter.py is the distance-vector implementation.
- Each router maintains local distance estimates and a forwarding decision for each destination.
- It reacts to neighbor advertisements, recomputes best next hops, and periodically rebroadcasts its own vector to neighbors.
7. Link-state subsystem
- LSrouter.py is the link-state implementation.
- Each router stores its own link state plus learned link states from other routers.
- It floods link-state updates with sequence numbers to suppress stale information, then recomputes shortest paths from the collected topology.
8. Topology and event inputs
- The *.json files at the repo root define test networks, link costs, and sometimes scheduled link failures/additions.
- Files ending in _events.json represent dynamic scenarios where the router must adapt to topology changes over time.
9. Execution paths
- network.py runs the simulator headlessly for automated testing.
- visualize_network.py runs the same simulation with a GUI, showing routers, clients, links, packet movement, and the current traced routes.
- These two entry points are the main way the repository is exercised.
10. Testing and validation
- test_scripts/test_dv_ls.sh runs the provided scenarios against either DVrouter or LSrouter.
- The end-to-end success criterion is whether traceroute packets follow the expected lowest-cost paths after convergence and after topology events.
11. Repository boundaries and constraints
- The grading boundary is strict: only DVrouter.py and LSrouter.py should be changed.
- The simulator, packet model, router base class, and test harness are treated as fixed infrastructure.
12. Documentation and deliverables
- README.md is the project spec and usage guide.
- report/report.md is present for writeup/reporting, but the code architecture itself centers on the simulator plus the two router implementations.
Main entry points: network.py network.py · DVrouter.py DVrouter.py · LSrouter.py LSrouter.py · packet.py packet.py
Components 17
Runtime
Simulator and entry points that drive the routing actors.
- network.py · Headless simulator that instantiates routers, links, and drives events.
network.py - visualize_network.py · Interactive simulator front end that visualizes packet movement and routes.
visualize_network.py
Core model
Shared packet, router, client, and link abstractions.
- router.py · Base Router interface and shared send/event hooks for routing actors.
router.py - packet.py · Packet representation for client traffic and routing control messages.
packet.py - client.py · Client-side logic used to inject traceroute-like traffic into the network.
client.py - link.py · Simulated link abstraction connecting routers and carrying packets.
link.py
Routing algorithms
Alternative decentralized routing implementations.
- DVrouter.py · Distance-vector router implementation with local tables and periodic advertisements.
DVrouter.py - LSrouter.py · Link-state router implementation with flooding and shortest-path recomputation.
LSrouter.py
Scenarios
Static and dynamic network definitions used by the simulator.
- 01_small_net.json · Static test network definition.
01_small_net.json - 02_small_net_events.json · Small network scenario with scheduled link events.
02_small_net_events.json - 03_pg244_net.json · Larger static network test scenario.
03_pg244_net.json - 04_pg244_net_events.json · Larger network scenario with topology changes over time.
04_pg244_net_events.json - 05_pg242_net.json · Additional static network test scenario.
05_pg242_net.json - 06_pg242_net_events.json · Additional network scenario with failures and recovery events.
06_pg242_net_events.json
Validation
Scripts and docs for running and checking the project.
- test_dv_ls.sh · Runs the provided scenarios against DVrouter or LSrouter.
test_scripts/test_dv_ls.sh - README.md · Project specification, usage, and expected behavior.
README.md - report.md · Project report and implementation notes.
report/report.md
Connections 27
- network.py → router.py: instantiates · Creates one router object per node and calls its event hooks.
- network.py → packet.py: moves packets · Delivers client and routing packets through the simulation.
- network.py → link.py: uses links · Builds and updates simulated adjacency between routers.
- network.py → DVrouter.py: loads · Can run the distance-vector algorithm implementation.
- network.py → LSrouter.py: loads · Can run the link-state algorithm implementation.
- visualize_network.py → network.py: wraps · Runs the same simulation with a graphical front end.
- visualize_network.py → client.py: shows · Visualizes client traffic and traced routes.
- router.py → packet.py: sends · Base router send() transmits packets using the shared packet model.
- client.py → packet.py: creates · Builds traceroute-like packets injected into the network.
- DVrouter.py → router.py: extends · Implements router hooks for distance-vector behavior.
- DVrouter.py → packet.py: advertises · Encodes routing updates as packet payloads.
- LSrouter.py → router.py: extends · Implements router hooks for link-state behavior.
- LSrouter.py → packet.py: floods · Encodes and forwards link-state announcements as packets.
- 01_small_net.json → network.py: inputs · Defines one test topology for the simulator.
- 02_small_net_events.json → network.py: inputs · Defines a dynamic topology with scheduled events.
- 03_pg244_net.json → network.py: inputs · Defines one larger test topology.
- 04_pg244_net_events.json → network.py: inputs · Defines a larger dynamic scenario.
- 05_pg242_net.json → network.py: inputs · Defines another test topology.
- 06_pg242_net_events.json → network.py: inputs · Defines another dynamic scenario.
- test_dv_ls.sh → network.py: runs · Executes headless scenarios for automated validation.
- test_dv_ls.sh → DVrouter.py: tests · Validates distance-vector behavior across scenarios.
- test_dv_ls.sh → LSrouter.py: tests · Validates link-state behavior across scenarios.
- README.md → network.py: documents · Explains simulator usage and execution flow.
- README.md → DVrouter.py: specifies · Defines the expected distance-vector implementation behavior.
- README.md → LSrouter.py: specifies · Defines the expected link-state implementation behavior.
- report.md → DVrouter.py: describes · Records implementation details for the routing project.
- report.md → LSrouter.py: describes · Records implementation details for the routing project.