The Internet Simulator is a multi-user computer network simulation, designed as a supplementary tool for teaching networking and data encoding concepts.

This document is a technical overview of the simulator. For developer set-up instructions see CONTRIBUTING.md.

• Overview
• Shared Storage
  • Shards
  • Tables
• Distribution of Responsibility
  • Router Status
  • Router Connection Limits
  • Address Assignment
  • Message Routing

The Internet Simulator simulates a computer network for a group of users. It does not actually establish peer-to-peer connections between clients; instead, each client communicates with the Internet Simulator API on CodeAI's servers, so all clients interact with a common network state hosted with us. Beyond that network state, there is little intelligence on the server - clients are trusted, and distribute work for running the simulation among themselves according to some simple rules.

The simulator keeps common network state in a Redis key-value store. The simulation data is organized into "shards" and "tables."

Each client connects to a NetSim Shard (in the MMORPG sense), which is a complete network state that is private to a subset of users. In practice each shard is a single key-hash pair in Redis, where the key is the shard ID and the hash contains a set of tables.

Normally, selecting a shard is completely hidden from the user. For students who are logged in and working with their class section, the shard ID will be generated so that they join the same shard as their classmates. Some users may belong to/own more than one section (e.g. Teachers). They will be able to select a shard to join upon opening the app.

Tentatively, users without an account can create a private shard that uses a UUID for its section ID. They can then copy a shard link that allows other users to join their shard. We may disable this feature in the future, as a privacy concern.

Every shard has an expiration time. After two hours of inactivity (no write operations by any client on the shard) all data associated with the shard will be deleted. Teachers and admins also have the ability to manually reset a shard.

Each shard contains a set of tables. All of the state for the shard is stored in these tables. Rows in shared storage tables don't have 'columns' so much as 'members,' because they are JSON blobs. In addition, every row has an ID, which NetSim relies on as an identifier for that network entity.

Every shard has four tables: Nodes, wires, messages and logs.

Nodes represent devices in the network.. They exist in this table, primarily so that they can receive a row ID, which becomes their unique identifier within the shard, and to broadcast their presence on the shard to other clients.

As soon as a student joins a shard, they create a user node row on that shard. When they disconnect, their user node row is deleted.

User node rows are only modified by the client that created the row. Router rows can be modified by any client, and present one of the synchronization challenges in the system.

Wires model physical connections between nodes, and metadata about those connections. The wires table ends up acting as an address table for routers, and a source for visualizing the network graph.

When a student selects a router and clicks "Connect," they are creating a wire from their node to the router node. When detecting a new wire, a router will assign an address on that wire that is unique within the router's local network. When a node disconnects from another node, the wire connecting them is deleted.

Wire rows are only modified by the client that created them (with the exception of the cleanup system - see "Shard Cleaning" below). Address assignment is done by the appropriate client simulating the router for that purpose.

Messages represent data in-flight between nodes, sent but not yet received. Rather than actually modify a wire row or even refer to one, messages simply exist between any two nodes. This effectively becomes "on-wire" storage.

Notably missing from this table is an "address" field. Routing data must be included in the payload. A routed message is actually two message rows - one from the sender node to the router node, then another from the router node to the recipient.

Message rows are only created by the sender, and only deleted by the recipient. They are never modified. In the case of messages sent to a router, the sender acts as the router and consumes the original message, then produces the new message from the router to the recipient.

Log Entries are entries in a shard log for a node on the network. Right now only router nodes have logs, and they are kept in remote storage so that all clients see a consistent view of the router logs.

Log entries are created by the client that is acting as the router for the particular operation that generates the log. They are never modified or removed. Because of this guarantee clients interact with the log table differently from the other tables, requesting simple forward deltas to keep requests small.

Because there is little server logic beyond the storage table mechanism, clients must divide up the simulation work so that they don't conflict with one another. For simulating the local client node this is fairly simple; for shared entities like routers and wires it's more difficult. Here are some of the ways that the simulation resolves conflicts.

For now, routers can be created by anybody, and updated by anybody. So far this hasn't been a significant problem, because the only thing to update has been the router's visible status, and it's not a huge issue if that's out of date for a few seconds.

Routers are allowed a maximum of six connections in our simulation, so what happens if two clients try to connect to a router at the same time? Here's the protocol each client follows.

1. The client optimistically creates a wire connecting it to the router.
2. The router (actually the client on the router's behalf), detecting a new connection, is given an opportunity to accept or reject the connection. It queries the wires table, and if it finds that it's beyond its connection limit, it rejects the connection.
3. If the connection is rejected, the client destroys the wire and reports a connection failure.

In this way, if two clients simultaneously attempt to fill the router's last seat they will both fail to connect and have to try again.

Similar to the connection limit, it's possible that two clients will simultaneously try and get a unique local address from the router. Since both clients are acting as the router on their own behalf, they might both get assigned the same address. This is not solved yet. Probably will implement a similar optimistic-assignment and rollback strategy.

The actual work of the router, directing a message to its destination, is always handled by the sending client. In a network with multiple routers, the sending client would act as each router for messages that it originated. The recipient only needs to simulate their local node for the final step of receiving the message.