# Networks

Planning / designing documents for networks.

Very coder and technical, fair warning.

## Core abstractions

- A network obeys its router.
- The router is **the** end-all. Everything obeys the router's whim.
- The router, however, obeys specialized peripherals on it.
- e.g. if you ask a router for the access controller, it'll send you to the access controller. That access controller is not necessarily what the router's owner wants. You should probably audit what's on your network.
- Anything on the network system obeys the network axioms.
- Deterministic routing.
- All routing must have one possible path. This is the only way we can have **fast** packet simulations with optimizations open in the future.
- Constant or linear-time operations.
- Nothing can be unbounded in time. Packets are **real time** and will not be allowed to spend much compute.
- **Asynchronous**
- **Packet lag can be simulated.**
- **End to end encryption does not exist.**
- Encryption ends at the destination network.
- This is not up for debate for many balancing reasons.
- **Encryption is not absolute.**
- Outside of monitor keys / stealing keys, some mechanics can just break encryption for certain packets / sockets.
- Anything that doesn't want to can use another system and use an adapter that does, or use its own system.
- No joke, 'radio' will be kicked off networks because it **does not obey the network axioms.**

## Pieces

### `/datum/datanet_connection`

A single connection to a network, with state of connected or disconnected.

If you need multiple, you set multiple.
Most things only need one.

- A connection can only be on zero or one networks.
- A connection is the packet / socket endpoint API.

### `/datum/datanet`

A network, formed by a router peripheral with a specific ID, which other devices *join* to.

### `/datum/datanet_routing_graph`

A routing graph describing inter-network connections.

Routing graphs are:

1. deterministic; there's only one possible route to a given network
2. cached; rebuilt when necessary, packet traversal should be super fast

### `/datum/datanet_packet`

A single packet of information.

- Individually processed and routed.
- Contains:
- sender device
- origin network
- receiver device, or just a network id for broadcast
- delay
- lag simulation, built right this time
- packet type
- packet domain
- this does not describe datatype, this is used for broadcast filtering, so you can only register to certain domains
- an arbitrary `data` var that makes sense for that packet type
- an `encryption` bool field
- If set, iptables / logging / sniffers cannot access `data` outside of the destination network.
- Has a return value that's transmit back to caller.
- **UH OH.** This means packet sends are **BLOCKING.**
- This sucks ass! Shame we're doing it anyways for reasons, like `iptables` working with more things.
- **You cannot tamper, under any circumstances, with the return value.** The 'return trip' of the packet is assumed to always succeed with no tampering if the 'forward trip' finishes. Design accordingly.

### `/datum/datanet_socket`

A single open connection

- Routed once and kept open
- Re-routed or closed on changes
- Contains:
- sender device
- origin network
- receiver device, or just a network id for broadcast
- if broadcast, things can query for open sockets on the network
- delay
- lag simulation, built right this time
- socket type
- socket domain
- this does not describe datatype, this is used for broadcast filtering
- an arbitrary `flags[]` list that works somewhat like add/remove traits (things can bad touch this as needed)
- an arbitrary `content` var that is **only mutable by the sender**, used to encapsulate the data, like a camera stream
- an `encryption` bool field
- If set, firewall / status monitoring / sniffers cannot access `flags` or `content` outside of the destination network.
- There *is* a string API for this, bust most of the time you're going to be directly accessing / typecasting / calling.
- This is after all meant to simulate a low-overhead datum to datum connection without packets being needed.

## Addressing

`/datum/datanet_connection` is our NIC-equivalent.

It has address in the form of `<network>:<device>` while on a network, and just `<device>` off network.

- Addresses are hexadecimal.
- Device IDs for normal networks are persistence-mangled 16 characters hexadecimals.
- First 8 characters is persistent mangling key.
- Last 8 characters is round-specific ID.
- Network IDs are special.
- `exonet` stands for "go to exonet"; this is used for special things like socketing to say, ONN's news servers.
- `<faction>-internal` stands for 'go to that faction'. Only some relays can reach some factions.
- **special values can be rewritten on the fly, by the router. you can infact sabotage the escape shuttle or require a special key to reach NT instead of the usual. these are just defaults.**
- for everything else, networks are a 4 character round-specific ID
- Persistence mangling is not done as routers already have persistence-mangled UIDs.
- `s` stands for namespace.
- There's a namespace for "regular network"
- There's a namespace for "exonet" - basically 'reaching out towards the wider galaxy'
- This is 2 digits for pretty-ness, even if we only have two right now. Forwards compatibility, too.
- Namespaces are **never** persistent; networks in that namespace may be.
- `n` stands for network ID. This is persistently mangled. The first 8 is the persistent key. The latter 8 is the round-specific key.
- `d` stands for device ID. This is persistently mangled. The first 8 is the persistent key. The latter 8 is the round-specific key.
- Things don't necessarily need to be 16 hexadecimal long. Player communicators, for example, will likely use namespacing.

## Routing

Routing is done via a routing graph.

A network may set **one** upstream, and have **infinite** downstreams.

A routing graph is a **tree** structure.

### path-finding

A packet / socket attempting to connect will do the following.

1. Check the source connection for special routing hooks.
- `datanet_connection`s are very modular, and support special routing / handling of packets and sockets.
- If it's handled on the connection as special, the connection is responsible for handling the packet / socket, up to and including just directly kicking it to the destination.
- **Packets / sockets without a target network can only be handled this way.** If this happens, and it isn't handled, it fails, as target network is **required** for route resolution.
2. Look for the source connection's network.
- The route fails if there's no network.
3. Check the network's routing graph for if the destination network is **below** the parent network (upstreamed, directly or indirectly).
- If it is, the packet routes through all the hops needed to get there.
4. Check **up** through the network routing graph for the first common ancestor network with the destination network.
- If it's not found, the packet is dropped.
- If it is found, the packet routes **up to that common ancestor**, and then **down through the hops necessary to reach the destination.**

A packet / socket has a **maximum depth of 8.**

- This means that it can go up a maximum of 8 networks, then down a maximum of 8 networks.

### Examples

#### department networks

All department networks are on the same `/datum/wirenet/data` (wired network cables), synced to their host router.

All department networks **upstream** the core station network.

The core station network is ran by engineering, and **upstreams** an abstract 'overmaps network', through the use of a long range transreceiver.

#### overmaps networks

All overmap entities are able to register transreceivers.

This basically results in a spatial system that meshes things together.

There's an abstract 'network' spanning all of the overmaps.

When a packet reaches this level, a check is done to see if a ship can transmit to the target. If it can, the packet is routed over to the transreceiver network of that ship (or the one with the downstream wanted). If it can't, the packet is dropped.

- Unfortunately, as a consequence of how the routing graph system works, this does mean that packets magically know how to route to overmaps.
- There will be a way to have routers kick a packet to another source for handling so you can have special bluespace bridges, but that will be hard to implement without violating the deterministic axiom.
- What's more likely is that routers will have this mode, with a warning that this can result in the target network pretty much voiding the packet, as you're more or less escape-hatching the automatic handling to say "I know this is reachable, go reach it via this".

#### overmaps comms buoys

Overmaps comms buoys don't actually form a network themselves, they'll just ensure the special checks done for 'can reach other ship' always pass if the ships are able to reach the same comms buoy network.

- There will be visual links for deployed buoys to visualize the network.

### Router - `config`

Routers have a set of configurations:

- `Allow Downstream Ingress` - allow downstreams to send data to this network
- `Allow Downstream Routing` - allow downstreams to send data **through** this network
- `Allow Upstream Ingress` - allow upstreams to send data to this network
- `Allow Upstream Routing` - allow upstreams to send data **through** this network
- `Routing Auth` - The key used to authenticate to the upstream network.
- Unnecessary most of the time.
- `Routing Security` - If **on**, `Routing Keys` is used for routing auth.
- `Routing Keys` - A list of up to 16 string keys **with descriptions** that a router must have to be a downstream.
- `Network Security` - If **on**, `Network Keys` is used for auth.
- Department networks start with this on, and pre-generated keys.
- `Network Keys` - A list of up to 32 string keys **with descriptions** that a device must have to join this network.
- `Encryption Key` - **Must be set for encryption to exist.** Things with this key as a monitor key can break encryption of packets targeting this network.
- `Monitor Keys` - Any network whose encryption key is in here **can be sniffed by this router, but not all devices on this network.**
- This allows engineering to have a monitor key on the station network without opening everyone's radios to sniffing.
- `Service Routes` - A list of network services (**unimplemented**) bound to their device IDs.
- Without this, anything on the network can say "I'm the server for this"; with this, the network has a defined one.
- This is for stuff like airlock controllers.
- This defaults to null because services should have keys to join the network anyways.
- `Address Blacklist` - A list of up to 64 device IDs to block entirely (including from being routed)
- **This is intentionally small for both optimization, and so the station network (engineering) cannot efficiently use this to ban a large amount of devices.**

### Router - `services`

#### `voice`

- The default handler for headsets / comms

### Router - `devices`

Routers can display a list of devices, along with their device classes.

- Device classes may be spoofed.

### Router - `iptables` (experimental)

**This will not be on first release.**

Routers can set packet rules via chains.

- `iptables` only works on packets. Sockets do not use this.

#### Actions

Each rule can do these things to a packet:

- PASS (default); do nothing
- ACCEPT; immediately pass it along
- DROP; throw it out
- CALL; redirect to a given chain and then return execution if it hasn't been DROP'd or ACCEPT'd
- This can only be done by the primary filter chain, to prevent recursion. It obviously cannot call the primary filter chain recursively.
- The chain to use can be specified by variable.
- There's a hard limit of 1 CALL in the primary filter chain. Be smart about it.
- LOG; log the packet
- WRITE; write a value to context, push a value to stack, or pop (and void) a value from stack
- Used as a timer system.
- There's a limit on how many WRITE's can be active, as they are actual timers.
- Has a **configurable delay**
- Has a **configurable timer de-dupe** ('do not start a new timer if one already started', 'overwrite existing timer')

#### Store Operations

Each rule can do up to 8 store operations of variable sets / gets.

#### Chains

A chain is a list of rules.

- Chains may have a maximum of 8 rules.
- There are a maximum of 8 chains in a router.
- The primary `filter` table may have a maximum of 16 rules.

#### Values

Rules can reference as values:

- Packet key's
- Packet intrinsics (type, domain, source ID, dest ID, origin network ID, dest network ID)
- Context keys
- Stack pushes (set) and pops (get)
- Procedures (named procedure with a set of values to use with it)
- Will not be in first implementation.

#### Context

Each `iptables` parser has a set of context key-value stores.

- You can have up to 8 keyed context tables.
- You can have up to 64 values per context table.
- Keys are strings.
- Values are strings, numbers, or null.
- Context can be manually edited.

#### Stacks

Each `iptables` parser has a maximum of 8 keyed stacks with a maximum size of 64 elements.

They can be `push`'d to as a variable set or `pop`'d to as a variable get.

- Stacks can be manually edited.

#### Rule: Always

Do something always.

#### Rule: If

Do something if a list of conditions match.

- The rule may have up to 4 conditions.
- Conditions may be set to 'AND' or 'OR'
- 'OR' conditions immediately pass the rule if encountered
- 'AND' conditions pass the rule if all of them are encountered
- Rule evaluates 'OR's first for speed.

#### "But this is missing"

- You can do most operations with just if's, context, and stacks.
- In-fact, the amount given to you is already **ridiculously massive**.
- There is, intentionally, no arbitrary string operations.
- A network axiom is that processing must be linear time. The allowed operations of iptables are always O(log N) or O(N)
- There is, intentionally, no 'send packet'
- This is a network filter system. not a scripting system.
- There is, intentionally, no 'do this every x seconds'
- This is a network filter system, not a scripting system.

### Router - `firewall` (experimental)

The much more boring version of `iptables` for **sockets only.**

A router has only one firewall state.

#### Rules

A router's firewall may have up to 16 rules.

A rule, while active, blocks sockets that it applies to from routing through the network.

#### Specifiers

A rule has specifiers for:

- The socket type it applies to
- The socket domain it applies to

#### Conditions

A rule has conditions for:

- ALWAYS; Always active
- NEVER; Never active
- CONTEXT; If `iptables` is active **and** a context value is set to a truthy, or a specific value

## Servers & Devices

### Server Racks

There are no real 'server racks'. Racked servers can be placed ontop of each other and removed as needed.

### Server Standalones

Some servers are actually machines and can't be stacked on top of each other, requiring a full frame.

### Server Types - Racked

#### VOIP Server

Processes and logs headset communications.

Has **filter rules.**

### Server Types - Standalone

#### Router

The core of a network.

Automatically forms a network; connect more devices to it with wired connections.

#### Bridge

Sort of like a breaker box.

Allows a network to connect to another network without being literally on the same data network.

- Multiple **upstream connections** does not violate the deterministic routing axiom.

##### Antenna

Joins as long as radio reception is active, and in range.

- Same zlevel / map struct
- Within radio range of the other
- **See: `What To Do With Radio`**

##### Subspace Data Array

Subspace relay nodes are how you connect across wide areas of the overmap.

Joins via TBD overmap calculations.

- The entire 'overmaps network' is one massive abstracted network that relay nodes let you 'upstream'.
- The overmaps network has special handling
- Longer distances with another ship might mean only text comms work, and with a delay.

##### Long-Distance Array

LDA nodes are a connection to the outside world.

- The station has transmit/receive
- Nebula has a transmit/receive
- **No one else has one that can transmit in general.**
- **They cannot connect to other LDA's.**
- Their routing is special; they're basically on an escape route. You cannot connect to them by going up / down through routing graph, only by 'jumping' to it from its host network.

##### Datanet

Basically lets you bridge to a network on another datanet, without physically joining the datanets.

- **Non-recursive.**

##### Powernet

Powernets have abstract, very simple networks.

Things like APCs will use it to connect to a designated controller on a proper network.

Area devices obey the APC, which obeys the network it's connected to.

This allows network integration of devices with practically no overhead (just a reference on APC and some additional powernet code).

Powernet nodes allow things on the powernet to access the network.

#### SPECIAL: Research Server

Mostly only included as an API test for "this map has this service please connect to it roundstart".

The research server is something you can socket to, to download research data.

Shrimple as that.

## Broadcasts

I don't know where to start with this.

This is a lot easier on radios than networks.

"Fast enough" is not okay, we need efficient and constrained broadcast specifiers.

What's likely to happen is that one of the two will happen;

- broadcasts only happen on the target network
- broadcasts only happen on the target network and downstream networks
- if this happens, its encryption is stripped for all downstream networks

Broadcasts as of right now are only anticipated to be needed for:

- Status Displays
- PDAs
- Headsets

Unfortunately, 2 and 3 cannot function perfectly with broadcast-only with the above constraints, so something will need to be figured out.

## Major Changes

### Headsets

**All headsets are now both radio and subspace headsets.**

- Headsets **join** to a network via an abstract headset receiver network and its corrosponding node.
- Headsets target a network (and the `voice` service on it; if there's multiple the first one wins).

#### Encryption

- **Headsets, like many other devices, only set `encryption` flag on packet.**
- Headsets target a network and use the network's headset key by default.
- **Headset network key, but not ID, is write-only.** You cannot extract the network key outside of checkin the router.
- **Headset encryption keys are just a magical re-sync method.** How they work is TBD, but losing an encryption key is still going to be a big deal (as well as being easy to use in general)
- Headsets can target a specific voice server on the network
- Lets you have sub-nets for radio
- This is obnoxious to use as you have to input the device address
- This is intentional, but we may make it so you can just put in a `*` to have it autodetect and fill it out.
- **Voice servers do not have their own encryption key.** They're slaved to the network's.
- This means that someone being on your network means they can hear all voice comms by just discovering the other voice servers from their headsets. **This is not a system to add levels of voice access in a network.**

All of this is TBD, really.

Packets / networks are hard.

#### Radio

See: 'What To Do With Radios'

### PDAs

PDAs target a PDA server on the map.

The PDA server keeps track of who's who, relaying messages as needed.

@everyone messages from say, the captain, use broadcast specifier system, maybe. I don't know.

### APCs

APCs will powernet connect to a target network.

All devices on that APCs without an explicit network connection use that connection and obeys that network.

- Most devices will use their own addressing if they're 'spammed' as `datanet_connection` is somewhat heavy for something like say, lights. Or not. Who knows.

### Cameras

Cameras sync to their APC.

### Holopads

Service discovery issue. Unsure how to solve. Similar problem to PDAs.

Holopads are likely to use the overmap networks abstraction without actually being on a network.

- Normal holopads can discover holopads on their sector
- Sector holopads can discover all holopads, using that abstraction to check distance / access
- Holopads **may** have a networked mode, but that would only work with direct dial.
- They're like radios in this way.

## Special Equipment

### Overmap Communications Buoy

Pretty much buoys you can drop to force certain ships to have a strong connection.

Acts like a relay network.

### Synthetic Radios

Synths will later be able to have radio / subspace nodes.

In the latter case, they'll connect to the overmaps abstraction directly, or to a given network as a device.

## What To Do With Radios

Here's the axioms for radios.

- Radio messages have a frequency.
- Radio messages are packets.
- Radio messages are not encrypted.
- Radio messages *are* potentially obfuscated.
- Radio messages are imperfect.
- You will not have perfect voice quality, even on the same map, most of the time.
- Radio messages **can only be tampered with at start / end** of a packet send/receive.
- Fast simulation, and it doesn't make sense to tamper mid-way.

### the fake kind (machinery kind)

Machinery will:

- Optimally use physical connections if the use case is a few tiles.
- Optimally use 'simple datum networks' system instead for anything on-map.
- Use radios for 'maybe on the same map but otherwise close enough'
- Use networks for anything complicated.

Radios will still work for machines but will be range limited to the new radio system.

It is no longer a valid system to use in every feature. Radio packets are expensive and obnoxious to use.

- Airlocks are being refactored to physical connections
- Atmos tanks we have no clue what to do with but it definitely won't be radio
- Never underestimate the power of "JUST PUT IN A STRING CONTROLLER KEY".

### the real kind (radio-radios)

### the weird kind (signallers)

### tampering

#### jammers

### bridging