ParlorNet
Turn-based game server for any computer, old or new
Clients | Protocols | Browsers | Telnet programs | Docs | Source

Server extensions (draft 0)

Two kinds of server-side plugin, kept apart:

Server extensions live in the adapters/ package (adapters/*.py), and the code calls them adapters. The native protocol on 6501 has no extension: the core serves it itself.

Ports

One parlor (a deployment) listens on consecutive ports from 6500; the firewall opens 6500-6800.

PortProtocolServed by
6500HTTP, with two sides (below)web extension, adapters/web.py
6501native protocol (protocol.md)the core itself (parlord)
6502telnettelnet extension, adapters/telnet.py
6503Reversi over the IOS protocolIOS extension, adapters/ios.py (game-network extension)
6504Reversi over the GGS protocolGGS extension (game-network extension; planned)
6505Backgammon over the FIBS protocolFIBS extension, adapters/fibs.py (game-network extension)
6506Backgammon for the Outland GatewayOutland extension, adapters/outland.py (game-network extension; it listens on 4000 in the container, Outland's own port, and the host publishes it as 6506)
6507Grid Words over the DOoM protocolDOoM extension, adapters/doom.py (game-network extension)
6508-6800further server extensions

Port 6510 is the admin console (below), an operator extension: the operator's blue-screen menus, not for players and not listed on the web site. The core's admin socket, 6599, listens on 127.0.0.1 inside the container only and is never published.

The web site's pages, their frame and what each holds are in site.md, with the docs site's. The lists behind the web site are in adapters/web.py:

Declaring the protocol

Every server extension that players connect to declares its protocol to the core (docs/protocol.md, Protocols; docs/design/protocol-declarations.md). Its module has PROTOCOL = (key, name, description), and its serve() calls declare.start(args, PROTOCOL) (adapters/declare.py) once it listens: one connection to the core is kept open for PRO key port name and PRD key description, sent again every 5 minutes, and made again if the core goes away. The port is --public-port when the extension is published under another port than it listens on (Outland: 4000 in the container, 6506 on the host; deploy/start.py passes it from catalog.PUBLISHED), else --port. The core lists the protocol while that connection is open, and the web's Protocols page shows it. The admin console and the bot declare nothing.

ExtensionKeyName
webHTTPHTTP and HTML 3.2
(the core)PARLOR/1ParlorNet protocol (PARLOR/1)
telnetTELNETTelnet with ANSI escape codes
IOSIOSInternet Othello Server (IOS)
FIBSFIBSFirst Internet Backgammon Server (FIBS)
OutlandOUTLANDOutland
DOoMDOOMDOoM crossword-game server

A GGS extension, when there is one, declares GGS. A new extension picks a key and adds its entry to the docs site's protocols reference (docsite/protocols.py); a test checks that every declared key has one.

Port 80 on the parlor's own name (parlornet.org, and www.) is a plain 301 to port 6500; the web server on 6500 then sends / to /welcome.htm.

Web extension: 1997 and 2027

Telnet extension

One telnet server for the whole game server, not one per game.

Built (adapters/telnet.py): the screen is 80x24. The terminal type (telnet TTYPE) picks a default display mode, offered in a menu with a sample line per mode: pc (ANSI colour, IBM PC CP437 characters; the default when no type is sent), utf8 (the same characters in Unicode), ansi (colour, ASCII only) and plain (no escape codes).

Admin console (operator extension)

adapters/admin.py, on port 6510: the operator's menus (docs/accounts.md, admin panel), over telnet. It reuses the telnet extension's terminal handling, cell screen and line drawing, and draws dialog-style screens: a blue background with a title line and a key hint line, grey boxes with a light top-left and dark bottom-right edge and a shadow, sunken lists, < OK > buttons with the active one highlighted. Menus, checklists, radio lists, one-line inputs (hidden for passwords), a multi-line editor for the message of the day, and message boxes; arrow keys, Tab and Shift-Tab, Enter, Space and Esc, and the first letter of an item or button. Before the first screen it asks for the display (pc, utf8 or ASCII), as the telnet extension does.

It is a client of the core's admin socket (127.0.0.1:6599: TLS 1.3 with an admin-role key, then the admin password) and has no power of its own; at most 4 sessions at a time.

Which server extensions run

adapters/catalog.py lists the server extensions a parlor can run, the admin console included, with their ports. The admin menus store the choice (the Adapters menu; setting adapters.enabled); the container's start script (deploy/start.py) reads it before starting anything and starts those that are installed, then parlord. With no choice stored, PARLOR_ADAPTERS or else every installed extension runs. If any process exits, the container exits and Docker restarts it.

Game-network extensions

Many games already have a network mode or a community server with its own text protocol. Where it makes sense, a server extension lets existing clients of that network play on our server, using our game types underneath.

FIBS extension (port 6505)

Speaks FIBS's plain-text ("telnet") mode, which MacFIBS 2.0.3, FIBS/W 1.30, xfibs 0.8 and xibc 0.31 parse, and CLIP for later clients.

ParlorNet is not FIBS: the First Internet Backgammon Server still runs at fibs.com port 4321, with its own community and ratings, and ParlorNet is not affiliated with it. The extension takes from FIBS only what the clients need to work: the protocol's message formats, the board: line, and the word counts and fixed phrases that MacFIBS, FIBS/W and xfibs match (for example ** User name authenticated., You are registered., the toggle replies and the game messages). Everything else is ParlorNet's own and says so:

The login line tells the session's style apart:

LoginClientsSession
connect name password (one line)MacFIBSno > prompts (toggle telnet NO); ** User name authenticated. starts the client's set / toggle / rawwho sequence
name, then password: FIBS/W, xfibs, xibc, terminalsa > prompt after every reply and every burst of news (xfibs parses nothing until its input ends in > )
login client 1008 name passwordCLIP clientsnumbered lines: 1-4 at login, 5/6 for who and rawwho, 7/8 log in and out, 12-19 chat; no prompts
guestanyFIBS-style registration: name x, then the server's sign-up steps as prompts (under sign-up password: choose a password, type it again), You are registered.

DOoM extension (port 6507)

Speaks the commands and wording of DOoM, a MUD for crossword games, so that BobGrid 2.3 and people at a terminal or MUD client can play gridwords/1. The sources are DOoM's help files, its English message catalogue and BobGrid's class files, read statically (docs/research/clients-gridwords.md, section b, which marks what is still unverified). ParlorNet is not DOoM; the banner and about say so.

The extension channel

Every server extension reaches the core on its extension channel (127.0.0.1:6590 in the container): TLS 1.3 with its own pre-shared key, --core 127.0.0.1:6590 --key /data/frontends/NAME.key (the container's start script enrols each extension it starts). A server extension never checks or keeps a credential: it signs in with the name alone, relays the player's answers to the server's steps (a password the client supplied answers only a question flagged cred), and sends OUT when the player leaves (telnet, IOS, FIBS and Outland hold one connection per player). It opens that connection only once its client has sent a login line, passes the client's address with SRC (for the core's per-address limits), and counts its clients that have not signed in yet, per extension and per address, with a short time to log in (Gate in adapters/common.py), so idle connects cannot use up its share of the extension channel. The container runs everything as one unprivileged user by default; docs/security-design.md (Containment) has the opt-in separations. New server extensions follow the same rules (docs/security-design.md, what each server extension must do).

A server extension may keep a little data with each player, under its own key name, with PRF GET, SET, DEL and LST (docs/protocol.md, data kept per extension and player): at most 16 keys of up to 12 characters, values of up to 56 printable ASCII characters, 1024 bytes per player. It reads and writes only its own namespace and only for the player signed in on the connection. CoreClient has prefs(), pref_get(), pref_set() and pref_del(), and for settings load_pref(key, choices, default) (at sign-in; never fails a sign-in) and save_pref(key, value) (when the player changes it). The first user is the telnet extension's movement keys (MOVE_KEYS_PREF, MOVE_KEYS in adapters/common.py). Nothing secret goes there.

Rules of the seams

This doc on GitHub


 These pages cover every ParlorNet server. | Source code | ParlorNet is free software.