src/main/resources/assets/opencomputers/loot/network/protocol

MCNET
=========

1. Definitions
 1. Network interface - any networking device that can send and recieve data and discover other cards in network node
 2. Network node - subnetwork of few compatibile network interfaces
 3. Address - unique name of network interface in network, by default unique id. One interface can have more than one address.

2. Network layers
  1. Physical - Implemented by network interface drivers, is able to send and recieve data form other interface in node, is responsible for host discovery in node
  2. Network - Implements routing.
  3. Transport - Other protocols allowing simple data transfer
  -This driver implements layer 2 and is interface to layer 1 implementations as well as part of layer 1
 
3. Layer implementation guidelines
  1. Physical
    1. Driver - Network interface driver is written in way libraries are written in LUA for OC. Each driver shold implement following methods:
       1. start(eventHandler): handle
          Starts a networking device, returns driver-defined handler. eventHandler is a table provded by higher layer, containing callbacks to it.
       2. send(handle, interface, destination, data)
          destination is address of another interface in node
          data is string data to send
       3. stop(handle, interface)
          Deactivates network interface. if interface is nil then driver should deactivate all its interfaces
       4. info(interface): pktIn, pktOut, bytesIn, bytesOut - usage stats
     2. Driver interface (or eventHandler) is table containing set of functions allowing lower layers to communicate with higher ones. The table must contain following methods:
        1. recvData(data, node, origin) - this function allows driver to pass incoming data to higher layer
        2. newInterface(interfaceAddr, selfAddr) - Register new interface. Interface is considered as node I/O, interface addr is internal node name
        3. delInterface(interfaceAddr)
        4. newHost(node, address) - this function must be called when new interface is detected in node
        5. delHost(node, address) - this function must be called when interface is removed from node
        6. setListener(evt, function) - event.listen wrapper

4. Network layer packets:
    Direct Data:
      D[ttl-byte][data]
    
    Routed data:
      E[ttl-byte][hostlen-byte][dest host][hostlen-byte][origin host]message
    
    Route Discovery:
      R[ttl-byte][Addr len][Requested addr][Route hosts-byte][ [addrLen-byte][addr] ]
    
    Host found:
      H[ttl-byte][Found host]
    
    Example case
    
    a. network:
    
       A        G
       |        |
    C--x--D--F--x
       |  |     |
       B  E     H
    
    b: nodes
     1. A,B,C,D
     2. D,E
     3. D,F
     4. F,G,H
     
    Example cases:
        I. Network booted, nodes know hosts in them
            1. Host A sends message to host B
                -Host A is known to host B, so host A sends to B direct message
                -Network data:
                    A -> B: "Dmessage"
            2. Host A sends message to G
                -Host A doesn't know host G so it sends route request to all hosts
                    host F knows G so it sends Host found packet back to A and another
                    Host found to G so it will be able to reply faster
                -Network data:
                    A -> B,C,D: "R[32][1]G[1][1]A"
                    B,C = Connected to one node, do nothing
                    D -> E,F: "R[31][1]G[2][1]A[1]D" - also D save A to requester table of G
                    E = Connected to one node, but it's nice to know A
                    F -> D "H[32]G"
                    F -> G "H[32]A"
                    D -> A "H[31]G" - D had A in requester table of G so the packet is sent
                    A -> D "E[32][1]G[1]Amessage"
                    D -> F "E[31][1]G[1]Amessage"
                    F -> G "E[30][1]G[1]Amessage"