Wormhole

The Wormhole server is the backend component of Astrocast. It is responsible for relaying data between OpenSpace instances in a session, and exposing an HTTP API that the Astrocast frontend uses to manage those sessions.

For the frontend, see the astrocast.openspaceproject.com repository.

Getting Started

Prerequisites

• Node.js and npm

Installation

1. Clone this repository
2. Install dependencies:

   npm install

3. Copy .env-sample to .env and fill in the values (see Environment Variables below)

Running

Command	Description
npm run dev	Start the server with hot reload (development)
npm run build	Compile TypeScript to dist/
npm run preview	Run the compiled output from dist/
npm run lint	Check formatting (Prettier) and linting (ESLint)
npm run lint-fix	Auto-fix formatting and lint issues

Environment Variables

Variable	Required	Default	Description
HTTP_PORT		25000	Port the HTTP API listens on
WORMHOLE_PORT		25001	Port the TCP Wormhole server listens on
SERVER_API_PATH	✓		Base path for all API routes, e.g. /api
CORS_ORIGIN	✓		The origin of the frontend, e.g. https://astrocast.openspaceproject.com
DEBUG		false	Set to true to enable verbose debug logging
ADMIN_AUTH_SDK_FILEPATH	✓		Path to the Firebase Admin SDK JSON file used for authentication
ADMIN_DB_SDK_FILEPATH	✓		Path to the Firebase Admin SDK JSON file used for the database
DATABASE_FIREBASE_DATABASE_URL	✓		URL of the Firebase Realtime Database

Obtaining Firebase credentials

1. Open the Firebase console
2. Go to Project Settings > Service Accounts
3. Click Generate New Private Key and confirm — this downloads a JSON file
4. Set ADMIN_AUTH_SDK_FILEPATH and ADMIN_DB_SDK_FILEPATH to the path(s) of the downloaded file(s)
5. The DATABASE_FIREBASE_DATABASE_URL can be found under Project Settings > General

Message Structures (version 7)

This section describes the different message types that are being sent between OpenSpace and the Wormhole application. A message consists of a header and a type-appropriate payload.

struct {
  byte[2] header; // fixed header, must be equal to "OS"
  uint8_t version; // The version of the protocol. Must be 7
  uint8_t messageType; // The type of the message that is contained in the payload
  uint32_t messageSize; // The total size of the payload data
  byte[messageSize] payload; // The payload of the message according to the messageType
}

Authentication (Type = 0)

This message is sent from OpenSpace to the Wormhole server to authenticate a new peer to a running session. It consists of a password which has to be provided, and an optional host password, and the optional name. An optional parameter is represented by a length of 0.

struct {
  uint16_t passwordLength; // The length of the password field
  byte[passwordLength] password; // The provided password without a terminating \0
  uint16_t hostPasswordLength; // The length of the host password field or 0 if the host password is omitted
  byte[hostPasswordLength] hostPassword; // The host password
  uint8_t roomNameLength; // The length of the session room name field
  byte[roomNameLength] roomName; // The session room name
  uint8_t nameLength; // The length of the user's name or 0 if the name is omitted
  byte[nameLength] name; // The users's name
}

Data (Type = 1)

This type of message is sent from the host Peer to the Wormhole server which then distributes this message to all other connected peers. This message is the primary way method for the host to send OpenSpace related data to the connected peers. Only the host of the session should send these messages to the Wormhole server.

struct {
  enum : uint8_t {
    Camera = 0,
    Time = 1,
    Script = 2
  } dataType; // The type of data message that is being sent

  double timestamp; // A monotonously increasing timestamp used to uniquely order the data messages on the receiving end

  byte[*] payload; // The content of the data message. The length of this payload is fixed for each of the `dataTypes` and described below
}

Camera

This data message contains information about the current camera

struct {
  double[3] position; // The position of the camera
  double[4] rotation; // The orientation of the camera expressed as a quaternion
  uint8_t followNodeRotation; // A boolean expressing whether the camera is following the rotation of the current focus node. Only values 0 and 1 are allowed
  uint32_t nodeNameLength; // The length of the name of the current focus node
  byte[nodeNameLength] focusNode; // The name of the current focus node
  float scale; // The current camera scale applied to the entire scene
  double timestamp; // The timestamp of the message
}

Time

This data message contains information about the current in-game time.

struct {
  double time; // The current in-game time
  double dt; // The current simulation increment
  uint8_t isPaused; // Determines whether the current simulation time is paused. Only values 0 and 1 are allowed
  uint8_t requiresTimeJump; // This value is 1 if the current `time` is far different from the `dt` + the `time` of the previous message. Otherwise it is 0
  double timestamp; // The timestamp of the message
}

Script

This data message contains a Lua script that the host wants a peer to be executed.

struct {
  uint32_t scriptLength; // The length of the script message
  byte[scriptLength] script; // The contents of the script
}

ConnectionStatus (Type = 2)

This message is sent from the Wormhole server to OpenSpace to inform the Peer about a change in status, be it the Peer's status or if the host of the session has changed.

struct {
  enum : uint8_t {
    Disconnected = 0,
    Connecting = 1,
    ClientWithoutHost = 2,
    ClientWithHost = 3,
    Host = 4
  } status;  // The identifier of the status

  uint8_t hostNameLength; // The number of characters of the new host or 0 if there is no host
  byte[hostNameLength] hostName; // The name of the current host of the session
}

HostshipRequest (Type = 3)

This message is sent from OpenSpace to the Wormhole server when the Peer signals that it wants to become the active host.

struct {
  uint16_t passwordLength; // The length of the password field
  byte[passwordLength] password; // The password
}

HostshipResignation (Type = 4)

This message is sent from OpenSpace to the Wormhole server when the Peer signals that it wants to resign a potentially current hostship.

struct {
  // No fields sent in the payload of the message
}

NConnections (Type = 5)

This message is sent from the Wormhole server to OpenSpace to inform the peer about a changed number of total connected peers to the server.

struct {
  uint32_t nConnection; // The number of total peers connected to the server
}