gazagnaire.org / space-net
APID-based virtual switch for SpaceOS inter-guest routing
fork atom
OCaml 94.0%
Dune 2.0%
Other 3.9%
6 1 0

Clone this repository

https://tangled.org/gazagnaire.org/space-net https://tangled.org/did:plc:jhift2vwcxhou52p3sewcrpx/space-net
git@git.recoil.org:gazagnaire.org/space-net git@git.recoil.org:did:plc:jhift2vwcxhou52p3sewcrpx/space-net

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

space-net#

APID-based virtual switch for SpaceOS inter-guest routing.

space-net routes 256-byte wire frames between guest VMs over Unix domain sockets (simulating virtio-net). Each guest (tenant) owns an exclusive APID range. The switch validates source APID ownership, enforces inter-guest send policies, and routes frames to their destination based on a destination APID carried in the frame's reserved field. Frames addressed to system APIDs (0x001--0x00F) are dispatched to a configurable handler, and frames with no local owner are forwarded to a DTN uplink callback. The switch also supports CCSDS Space Packet wrapping for uplinked frames.

The package ships a CLI tool with two subcommands: run to start the virtual switch, and inject to send a test frame directly to a guest socket.

Installation#

opam install space-net

Usage#

CLI#

# Start the switch with default v0 topology (camera, processor, spaceos tenants)
space-net run --socket-dir /tmp/space-net

# Inject a test TM frame into the camera guest socket
space-net inject --type TM --apid 0x010 --payload "hello" --socket /tmp/space-net/camera.sock

Programmatic#

open Space_net

let config =
  Config.{
    tenants = [
      { name = "camera";
        apids = apid_range 0x010 0x01F;
        can_send_to = [ apid_range 0x020 0x02F ] };
      { name = "processor";
        apids = apid_range 0x020 0x02F;
        can_send_to = [ apid_range 0x010 0x01F ] };
    ];
    socket_dir = "/tmp/space-net";
  }

let () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let net = Eio.Stdenv.net env in
  let switch = Switch.v ~config () in
  Switch.run switch ~sw ~net

API#

  • Config -- tenant APID ranges and policy definitions. Each tenant has a name, an owned APID range, and a list of APID ranges it is allowed to send to.
  • Router -- pure routing logic with O(1) APID lookup via a 2048-entry table. Routes frames to Local, System, Uplink, or Drop destinations with source ownership and inter-tenant policy validation.
  • Connection -- per-guest Unix domain socket management. Handles reading and writing 256-byte wire frames and sending ERROR/NACK responses.
  • Switch -- orchestrator that ties routing, connections, and callbacks together. Supports frame injection from DTN and CCSDS Space Packet wrapping for uplink.

References#