JSON database service (hosting information for other BBSes to access)

One of the services that Synchronet includes is a JSON database service. With this service, a Synchronet BBS can serve information in the form of JSON (Javascript Object Notation). This means a Synchronet BBS can provide information via web/HTTP requests; any client software (such as BBS doors, etc.) can request this information and even add/update the information.
For instance, a BBS might provide game scores for a particular game; that particular door game could be installed on multiple BBSes and post their user scores to the host BBS, which would provide a central place to host scores for the door, so that there could be a multi-BBS top scores list. Another example is a global one-liners wall where people from multiple BBSes could post a one-liner, and the one-liners could be hosted by a BBS and accessed from any other BBS.

Synchronet provides this via the script json-service.js (in the exec directory). To enable the JSON service, add the following lines to your ctrl/services.ini' if not already there:

[JSON]
Port=10088
Options=STATIC | LOOP
Command=json-service.js

Note the port number is 10088. This is a common port number to use for the JSON service.

For storing data to be accessed this way, Synchronet uses the concept of JSON “databases”. Each JSON database is given a name and are configured in ctrl/json-service.ini. For instance, there is a one-liners script in xtrn/oneliners, and if you want to host one-liners, you would need these lines in ctrl/json-service.ini:

[oneliners]
dir=../xtrn/oneliners/

This means that the 'oneliners' JSON database will be in the xtrn/oneliners directory; the actual file for the JSON database is oneliners.json. When client software reads or writes to this JSON database, the data will be stored in xtrn/oneliners/oneliners.json.

Most basically, all that is really required to interact with a JSON database is writing (adding/updating data) and reading (getting data from the JSON database). The top of json-client.js (in sbbs/exec/load) has a list of relevant functions for working with a JSON database. Assuming the JSON client object is jsonClient, the two functions for reading from and writing to a JSON database are:

jsonClient.read(scope,location,lock)
jsonClient.write(scope,location,data,lock)

The 'scope' parameter is the name of the database (i.e., “gttrivia” for Good Times Trivia scores. The 'location' parameter specifies the location in the JSON object. For instance, if there is a JSON object as follows:

scores: {
    player1: {
        TestGame: 100
    }
}

A location of scores.player1.TestGame specifies the value of the TestGame property under player1 under scores in the JSON object.

For the 'lock' parameter in the JSON client functions, lock objects are often used to protect against problems if multiple things try to read/write the same value at the same time. There are a few lock values that can be specified for the lock parameter:

LOCK_READ = 1
LOCK_WRITE = 2
LOCK_UNLOCK = -1

Generally, when reading, specify a lock value of 1; when writing, specify a lock value of 2.

The subscribe function can be used to subscribe to get updates when data at a given JSON location changes:

jsonClient.subscribe(scope,location)

When you subscribe to a certain data location, it's important to specify a callback function. For instance:

JSONClient.callback = processUpdate;
function processUpdate(update)
{
}

When there could be concurrent access to the same data (i.e., multiple clients that might need to write to the same location in the JSON data), it would be a good practice to lock that location for writing, read the data, write your changes, then unlock it. There are a couple of functions, lock() and unlock() that you can use to do this:

jsonClient.lock(scope,location,lock);
jsonClient.unlock(scope,location);

For instance:

var JSON_DB_LOCK_READ = 1;
var JSON_DB_LOCK_WRITE = 2;
var jsonClient = new JSONClient("servername", 10088);
jsonClient.lock("scores", "player1.TestGame", JSON_DB_LOCK_WRITE);
var scoresData = jsonClient.read("scores", "player1.TestGame", JSON_DB_LOCK_READ);
// Change scoresData ...
jsonClient.write("scores", "player1.TestGame", scoresData, JSON_DB_LOCK_WRITE);
jsonClient.unlock("scores", "player1.TestGame");

There are a couple of additional JavaScript files you can create for your JSON database:

• commands.js: This can be used to deny (or allow) access to perform certain JSON commands, by specifying a function for this.QUERY. It returns a boolean; Note that a return value of false allows a command, and a return value of true denies the command. For instance, you could prevent client programs from deleting data from the JSON database if you wish. For instance, this one (One Liners) allows subscribe, unsubscribe, read, slice, and push or anything from the current computer: https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/oneliners/commands.js
• service.js: This can be used to write a long-running background script to perform maintenance tasks on your JSON database. For example, this is the service.js for One Liners: https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/oneliners/service.js

• service index