wppsvr

README

wppsvr — Weekly Packet Practice Server

wppsvr is a server that retrieves, analyzes, responds to, and reports on SCCo weekly packet practice messages. Its results are available through a web server that it hosts.

wppsvr takes no command line arguments; simply start it from within the directory that contains its data files. Only one copy of wppsvr can be running at a time; if you start a second copy (in the same directory), it will exit immediately and silently. (This allows for a primitive HA mechanism: start new copies of it frequently, and if they aren't needed they'll go away instantly.)

In its working directory, wppsvr expects to find three files:

• config.yaml contains the configuration for the server. Consult the comments in that file for detailed explanations of the configuration options.
• wppsvr.db contains the server database. It is a SQLite 3 database; the schema for it is in store/schema.sql.
• run.lock is used to ensure that only one copy of wppsvr is running at a time. It will be created if it doesn't already exist.

Theory of Operation

wppsvr is organized around the concept of a "session", which is a collection of messages and responses that are reported together. As of this writing, SCCo has two sessions each week: a SPECS net session (running from Tuesday 00:00 to Monday 19:00) and an SVECS session (running from Wednesday 00:00 to Tuesday 19:00), plus a hospital net session running from 18:00 to 19:30 on the fourth Wednesday of each month. However, any number and scheduling of sessions can be defined.

Each session has parameters defining it. These include:

• The name of the session (e.g., "SVECS Net"), and the call sign and message number prefix to be used for it (e.g., "PKTTUE" and "TUE").
• The start and end times of the session.
• The set of BBSes to which practice messages should be sent for the session, and the set of BBSes that are simulated "down" for the session.
• The set of BBSes from which practice messages should be retrieved, and the schedule and mechanism by which those retrievals are performed.
• The set of practice message types that are supposed to be sent for the session, or alternatively, the specific practice message that is supposed to be sent.

Each session has a set of messages that were received for it. (Note: in all wppsvr documentation and code, "message" refers to a received message. The transmissions generated by wppsvr are referred to as "responses" and "reports", not "messages".)

When a message is received for a session, it is analyzed according to the parameters of the session. Analysis of a message can detect a variety of problems. The configuration file describes how each type of problem should be handled: whether it should be reported, whether the message should count as a valid "check-in", etc.

In most cases a delivery receipt will be generated and sent for the received message. The message, its analysis, and the generated responses are then stored in the wppsvr.db database.

At the end of the session, a report will be generated, saved in the database, and sent to the recipients identified in the session parameters. Reports on sessions (even incomplete ones) are also available through the web server interface.

Web Server

The web server interface runs independently from the message retrieval, analysis, and reporting system. The front page of the web interface gives basic statistics on the most recently concluded SPECS and SVECS nets, and the ones in progress. (Note: this front page is the only part of the entire wppsvr system that has information about those specific nets hard-coded.)

All other information provided by the web server requires a valid login. wppsvr does not maintain its own user database; it relies on the scc-ares-races.org database. Specifically, whenever anyone attempts to log into the wppsvr web interface, wppsvr takes their provided call sign and password and uses them to attempt to log into scc-ares-races.org. If the login to scc-ares-races.org is successful, they are considered logged into wppsvr. wppsvr does not use any data from scc-ares-races.org other than detecting whether a particular call sign and password combination is valid.

Once logged in, users are shown a calendar with all sessions on it. Clicking on a session will show its report and give access to its messages and responses. On the calendar, each session has a notation. Initially, those notations show the current user's practice history: whether they sent a practice message for each session, and whether those message had problems. However, the display can be changed to show the total message counts for each session instead. Privileged users can also change the calendar to show some other user's practice history.

The displayed report for a session may be either static or interactive. Reports that were generated by previous packet NCO scripts are presented statically, and are recognizable because they are in fixed-width font. Reports for sessions handled by wppsvr are presented interactively. In the list of messages for a session, users will see their own message presented with a hyperlink that will allow them to see the message that was sent and the responses that were generated for it. Privileged users will see such a hyperlink on all messages, not just their own.

Software Layout

wppsvr has the following sub-packages:

• analyze handles analysis of retrieved messages and generation of responses.
• cmd/jnospwd is a command that generates the response to the JNOS password prompt, including MD5 hashing with the provided secret. It gets passwords from the config.yaml configuration file.
• cmd/reanalyze is a command that forces the messages in a session to be re-analyzed. This can be used after the analysis code has been updated, in order to correct an error in analysis.
• cmd/send-report generates and sends the report for a session. (This is in addition to the automatic send at the end of the session period.)
• cmd/test-history re-analyzes a set of past messages and ensures that their analysis did not change. It is used in testing wppsvr changes.
• config handles reading the config.yaml configuration file.
• english contains utility functions for generating English prose in problem responses.
• interval contains code for parsing and interpreting time interval specifications, as used in the config.yaml configuration file.
• report contains code for generating and sending session reports.
• retrieve contains code for retrieving messages from BBSes.
• store contains the code for managing the wppsvr.db database.
• webserver contains the code for the web interface.

The wppsvr package itself contains code for managing the log files as well as the main session retrieve-analyze-report loop.

Legal Text

This software was written by Steve Roth, KC6RSC.

Copyright © 2021–2023 by Steven Roth steve@rothskeller.net

See LICENSE.txt for license details.

Documentation

Overview

wppsvr is a server that retrieves, analyzes, responds to, and reports on SCCo weekly packet practice messages. config.yaml (configuration data) and wppsvr.db (message database) must exist in the current directory when the server is started. The server runs forever, operating periodically as dictated by the configuration. The configuration is re-read periodically and can be changed while the server is running.

If multiple instances of the server are started concurrently, all but the first of them will exit immediately and silently. As a result, the server program can be invoked frequently (e.g., via cron job) as a sort of poor-man's HA strategy: if a previous copy is already running, it will do nothing, and if not, the new copy will take over.