We've recently moved hosts! Please report any weirdness with the wiki (or spam) on Utopia.

From BBSWiki

This is the official Requirements Specification document for Conspire (formerly known as nuDOC). Conspire is a complete rewrite of DOC (Dave's Own version of Citadel), one of the last living branches of the Citadel BBS software tree.

Since this document has been migrated from one named "nuDOC Requirements Specification," there are many references to "nuDOC" in the text. For the purposes of the document, "nuDOC" is equivalent to "Conspire."

Introduction

Before the Internet became widely accessible to users outside of academic institutions and large corporations, the electronic Bulletin Board System (BBS) was a vital link for discussion, debate, distribution of shareware, and more. The BBS world had its golden age in the early 1990s. By the late 1990s it had almost completely evaporated, quickly replaced by the rapid encroachment of public ISPs.

There were holdouts, however. Among these were Internet-based BBSes running on software known as Dave's Own version of Citadel (DOC). Unlike local dial-up boards, these systems had been connected to the Internet from the very start. This gave them a built-in longer lifespan than dial-up BBSes. The advent of the Web did eventually reduce the number of active users on these boards significantly, but there remains a dedicated core. These users enjoy BBSing and many of them will likely continue to do so as long as a BBS remains.

DOC was originally written circa 1990 for the Iowa Student Computing Association BBS at University of Iowa. It is written in C and heavily optimized for supporting about 1000 simultaneous users on a 50MHz PA-RISC machine, an impressive feat which ISCABBS accomplished in its heyday. However, this arcane and very poorly documented code is not aging well and is nearly impossible to maintain or extend. Experienced programmers refuse to have anything to do with it. It is essentially a living fossil.

The Conspire project goal is to rewrite DOC from the ground up, modernizing it for deployment on modern operating systems including certain flavors of Linux, Solaris, and Mac OS X. The new system will be completely client-server with no direct user connections to the BBS server program. The system will use a flexible, well-defined XML protocol for all communications, allowing for easy development of new clients. UTF-8 will be used globally, allowing for non-English language users. A modern RDBMS will be used for data storage.

The stock client produced as part of the Conspire project will mimic the existing interface almost exactly, easing the transition for users who have been interacting with DOC for 15 years. Later, web-based and light GUI clients may offer ways for new users to join the DOC community without having to learn an arcane character-based interface.

The DOC community is an irreplaceable part of Internet culture. The signal-to-noise ratio on these boards is much higher than on Web-based online communities. The userbase of the best boards is a unique collection of intelligent people. Since 1994, I've gained a lot from the DOC world. Conspire is my way of giving back by extending the lifespan of the community.

Why a total rewrite?

Systems program building is an entropy-decreasing process, hence inherently metastable. Program maintenance is an entropy-increasing process, and even its most skillful execution only delays the subsidence of the system into unfixable obsolescence. -- Frederick P. Brooks, Jr., The Mythical Man-Month (1975)

General Requirements

System Requirements

The server will be written in Python, utilizing the Twisted event-driven networking framework. It will be supported by a PostgreSQL database. The server must run properly on Debian GNU/Linux (lenny), Solaris/x86 and Solaris/SPARC, and Mac OS X.

The stock client will be written in Python. It may, given compatibility with Jython, be compiled for the Java Virtual Machine for certain environments, or it may use wxPython for a fairly cross-platform GUI. It must run properly on Windows XP, Mac OS X, and on the major X Window Desktop Environments including KDE and GNOME on Linux.

Robustness

The system should handle spurious input gracefully. In the case of the server, this means unexpected, malformed, spurious or malicious input must be detected and/or otherwise handled without causing a crash or a security breach. In the case of the client, incorrect or unexpected user input must not cause a crash. Further, to the extent possible, such input must not negatively impact the BBS -- the well known "paste bomb" effect in DOC should be limited where possible by eating characters based on a heuristic.

The server should recover gracefully from a system crash or power failure. This means no dirty room pointers, lost messages, ghosts in the user list, etc. The only exceptions to data loss are pieces of data that were being committed to the database at the instant of failure.

Performance

The server must not allocate excessive amounts of memory nor hog the CPU. The server should roughly be able to support 100 users on a machine with a 533 MHz VIA Centaur CPU and 128MB of RAM without noticeable slowdown.

The stock client should use no more than 8MB of RAM as an absolute maximum and should use negligible CPU time on a modern computer. 2MB of RAM or less is preferable since a form of the stock client will likely be run on the system hosting the server for users who wish to connect via Telnet or Secure Shell.

Security

The system will handle all network transactions via an SSL secured connection.

Licensing

The server and stock client will be released under the Common Public License (CPL).

Specification Limits

• Usernames are 19 characters max.
• Room names are 40 characters max.
• Room 0 is the lobby. Room 1 is Mail>. Room 2 is the Admin Log>. These rooms are unzappable.

Use Cases

Overview

Conspire will be designed roughly following a Model-View-Controller (MVC) architecture. The relational database is the model. The BBS server is the controller. The clients are the views.

With this model, the use cases will be split into two groups: client-server use cases and client-user use cases. Often one use case, such as logging in, will have a component in each group. Note that when we say "client-user" in this case we refer to the stock client. When we say "client-server" we refer to any connecting client; they must all adhere to the same protocol specification.

Client UI

Connecting to a BBS

1. The user starts the client.
2. Depending on the contents of a config file, the client either presents the user with a list of BBSes to choose from with possibility to specify a new system or skips this step.
3. The client connects to the user's choice of BBS or to the BBS specified for autoconnect in the config file.
4. Once a connection is established, the client displays the system's login splash screen and a login prompt.

New account creation

See /New account creation.

Logging In

1. The client presents a login prompt.
2. The user enters their username.
3. The client presents a password prompt.
4. The user enters their password.
5. The client validates the pair with the server. If valid, the client proceeds. If not valid, the client returns to step 1 after printing an error message.
6. The client prints out some useful information.
7. The client prompts the user for color if set to do so.
8. The client enters the BBS in one of several ways:
   1. Into room read mode for the Lobby if there are new messages there
   2. Into room read mode for Mail> if there are new mails for the user
   3. Into the short prompt if there are no new messages in Lobby> or Mail>

Format of useful information printed at login:

Welcome to Utopia Dammit! BBS, Cat!
Last on: 3/15/06 10:41 until 10:42 from pts/17
This is call 98.  There are 11 users.

NOTE:  You have eXpress messages turned OFF as a default!

Short Prompt

The short prompt is displayed when a user is not actively reading a room. Among other things, it allows users to start reading a room, skip or jump to rooms, log out, enter a message in the current room, eXpress message another user, and more.

General use case:

1. The user presses a key.
2. If on the menu and the user has sufficient priveleges, the request action is initiated.
3. If not on the menu or the user does not have sufficient priveleges, nothing happens.

Utopia Planetia>

The menu and specific use cases for the short prompt are present in the /Short prompt commands subpage.

Read prompt

The read prompt, or long prompt, is displayed when actively reading messages in a room.

[Utopia Planetia> msg #154 (0 remaining)] Read cmd ->

Use cases for the read prompt commands are in the /Read prompt commands subpage.

Aide commands

Displays a menu of commands for sysops, programmers and roomaides. See /Aide commands for details and use cases.

Config menu

Displays a menu of configuration and miscellaneous commands, with some commands only accessible to sysops and programmers. See /Config menu for details and use cases.

Help menu

The /Help menu subpage details the menu presentation and use cases.

Message entry

The /Message entry subpage details the use case of entering messages.

Message reading

The /Message reading subpage details display of messages.

eXpress messages

The /eXpress messages subpage details sending and receiving of eXpress messages.

eXpress message log

The /eXpress message log subpage details the eXpress message log interaction (see /Config menu for configuration).

Known rooms list

/Known rooms list details display of the known rooms list.

Wholist

/Wholist details display of online users.

Aidelist

/Aidelist details display of the <@> list.

Profile

/Profile details display of user profiles. /Config menu details modifying them.

Roominfo

/Roominfo details the display and modification of room info.

Find

/Find details the find interface.

Tagging

/Tagging details the tagging interface.

Client-Server

All client-server interaction will consist of XML messages passed between the client and server. All messages fall into the following classes: handshaking, client requests, server responses, and unsolicited server broadcasts.

All messages are defined by an XML DTD. The DTD to use is negotiated at login time by a handshake. In the initial release, there will only be one fully functional DTD, but multiple DTDs may evolve to reflect the capabilities of different clients, such as web clients vs. character based, etc. An extremely basic handshake DTD is also defined. TODO

Logging in

Upon connection, the client sends a handshake message listing the DTD it wishes to use. The server then responds with an acknowledgement or no-acknowledgement response. If the response is NAK, the client falls back to other DTDs if it supports any until the server and client can agree. If no agreement is reached, the client gives up and disconnects.

Handshake traffic is defined in the most basic DTD which all clients must support. (TODO)

Client configuration

Clients may store client-side configuration on the server with a unique ID, minimizing the need for config files and allowing custom configs to be easily used by multiple instances of a client (for example, at home and at work).

Client requests

Any client-user use case which requires interaction with the server -- in other words, which cannot be fulfilled by the client using locally stored or cached data -- will require the client to make one or more requests of the server.

Each client request is a complete XML document formed according to the DTD negotiated at login.

Server responses

Any client request may or may not generate a server response.

Each server response is a complete XML document formed according to the DTD negotiated at login.

Server broadcasts

Certain traffic may be sent to connected clients unsolicited. This traffic is termed a server broadcast. Server broadcasts may or may not generate client requests. An example of a server broadcast might be an eXpress message.

Each server broadcast is a complete XML document formed according to the DTD negotiated at login.