NodeListServer Generation 2

This is a reimplementation of the Mirror List Server using NodeJS with 100% Fresh, Organic, Free-Range Australian Code. It runs on top of NodeJS 12.x LTS with Express as the light-weight web server. Please consider a donation (see the Ko-Fi button above) if this product is useful to you.

Features

OSS Core: The official Mirror List Server is closed source. NodeListServer is open source, so you can freely tailor it to your needs.
Fast: Just like the official List Server, this one written in NodeJS is fast too.
Secure: NodeListServer supports ACLs to prevent anyone adding/removing servers from your instances. Clients must provide a key in order to communicate, and rate limiting helps keep traffic floods at bay.
Configurable: Generation 2 of NodeLS now features a INI-styled configuration file. This makes configuration much easier.
WebGL compatible: NodeLS uses a simple HTTP API to add and remove servers. No complex magic required.
Not just useful for games: This is not just limited to games, you could use it for other non-Unity applications too!

Non-Features

Matchmaking: Too complicated for what this product does.
Anything else that it doesn't offer.

Bug Fixes, New Features, etc

If you find a bug: Please report it via the Issues ticket system. If you know NodeJS-flavoured Javascript and think that you can fix it then I'd really appreciate a pull request!
Refactors, Improvements, Tweaks: I'm all ears to improvements and refinements. Please open a issue and suggest your modifications or fork this project, improve it, then open a PR.
Ooh, shiny feature: New features are carefully considered. I try to follow the KISS prinicible, which helps not only keep code clean but doesn't bloat the end product.

Do note that you should not feel offended if I reject an idea, by all means you can make your own variant of NodeListServer with your own additions.

Setup

Docker Support

If you want to have everything handled for you and you're running a linux server, see the Docker support documentation file for more info. Please note that this will require some additional setup.

Requirements

NodeJS 12.x LTS (download and install it first before trying to run this code)
A server instance, be it Windows or Linux
Some knowledge about programming, fair amount of patience and Git-fu

Make sure your installation of NodeJS 12.x LTS is functional before continuing!

Installation

Git Clone Method

Run this in the console of your operating system where you want the code to be placed (for example, C:\NodeListServer).

git clone https://github.com/SoftwareGuy/NodeListServer .

NOTE: It is possible to use a GUI such as Git GUI or SourceTree. Use whatever you're familiar with.

Continue with configuration step below.

ZIP Installation Method

Obtain a ZIP archive of this repository via the "Download as ZIP" option.
Extract it somewhere on your system.

Note: The ZIP Installation Method loses it's Git metadata, so you will not be able to have easy updates.

Configuration

Open config.ini.
Carefully make any adjustments to the configuration as desired (see the configuration page for more information).
Save and Exit. Re-upload your modified config.ini (ie. you edited it via FTP).

Operating & Updating

Note: It's recommended to use a process manager like PM2 which will allow you start and stop the server elegantly, and restart it in case of crashes, etc.

Starting & Stopping

First Run: Install the Node modules by issuing npm install --only=production. This will read the requirements from packages.json.

To start the server:

Protip: Check to see if the port is open that you want NodeListServer to listen on. You cannot have more than one list server listening on the same port number.

Invoke NodeJS with listServer.js. This is dependent on your operating system, but if Node is installed in your path, you can simply do node listServer. Please ensure you use the Node 12.x binary.
Observe the logs that are printed to the console, if the list server does not say anything then something went wrong. A successful startup is as follows:

NodeListServer Gen2: Mirror List Server reimplemented in NodeJS
Report bugs and fork me on GitHub: https://github.com/SoftwareGuy/NodeListServer
Listening on HTTP port 8889!

Issue a HTTP POST command like the following to http://[your-server-ip]:8889/list. cURL is very useful as a debug tool, so here's a one liner. Replace NodeListServerDefaultKey with your changed key if you changed that.

curl -X POST -d "serverKey=NodeListServerDefaultKey" http://127.0.0.1:8889/list

If all goes well, you should get some JSON as a result. If you don't, or you get Bad Request then check what the console says - you dun goofed probably.

To stop the server:

Simply CTRL+C the running Node process, or you can use kill/pkill to kill the node instance. I'd recommend using ps aux and kill <pid> carefully, because pkill node would try to kill all node instances on your box - and that's really no bueno.

Updating NodeListServer

Stop NodeListServer if it's running.
Execute git pull from the repository you cloned to your local machine or server instance.
- Note that if you obtained the source via a ZIP archive, then you're not going to be able to just execute git pull. Download and extract a new ZIP archive of this repository instead.
New commits will update your installation of NodeListServer after running git pull.
- Rectify any pull merge errors if you have any (and you should know how to do this).
Start NodeListServer again.

The API Explained

Section omitted because it needs cleanup. Check back later.

Using NodeListServer with Unity

Want a easy, ready to go project? Then grab a copy of the NodeListServer-Example repository.

In fairness, It's pretty easy to use NodeListServer with Unity. You can use UnityWebRequest or another library (ie. Best HTTP Pro) to fetch the server lists and issue add/remove commands. As long as you can decode JSON it returns for the server list, you should be fine.

Important: Do NOT auto-assume that POST functions will be successful. Always check the HTTP status code before doing anything with the returned response.

You will get HTTP code 200 with a "OK" response from NodeListServer on success.
Anything not HTTP code 200 will be NodeListServer denying your request (you'll most likely get HTTP Code 400, Bad Request or if your IP is blocked, 403 Forbidden).
Make sure you cache the Server UUID you use. You'll need to use that to tell the List Server what to do with your server entry. Without a valid Server UUID, it will refuse to do anything.
I strongly recommend using GUIDs, which are unique and if you're using Mono or .NET, you can just use System.Guid.newGuid() to generate a random one.

As a bonus, here's some generic serializable classes that you can use to translate the JSON into something more usable:

[Serializable]
public class NodeListServerListResponse
{
    // Number of known servers.
    public int count;
    // The container for the known servers.
    public List<NodeListServerListEntry> servers;
    // Ideally used for client-hosted games, tells you how often you should refresh your server information.
    public int updateFrequency;
}

[Serializable]
public class NodeListServerListEntry
{
    // IP address. Beware: Might be IPv6 format, and require you to chop off the leading "::ffff:" part. YMMV.
    public string ip;
    // Name of the server.
    public string name;
    // Port of the server.
    public int port;
    // Number of players on the server.
    public int players;
    // The number of players maximum allowed on the server.
    public int capacity;
    // Extra data.
    public string extras;
}

Make sure you POST the correct data when you want to add/remove servers. See API Endpoints for more details on the required POST fields.

Credits

vis2k: Mirror Networking and the original List Server
JesusLuvsYooh: That other blacksmith that's forging NodeLS into shape and always annoying me with questions
AnthonyE: First actual deployment of NodeLS in production!
Mirror Team & Discord Members

Thank you for choosing Australian Open Source Software.

AdrianCabrera / NodeListServer