The protocol is nearly complete -- I have a server which implements PPP/M available here. If you'd like to implement this protocol, or make some changes, or can't understand the weirder bits, email me. Extensive credit to archon, who fixed the original server version.
Get PPP/M Server Kit 0.95 (extreme beta) here. The client will be up soon. This server is currently 95% functional. Some fixes need to be made to get it working in all situations/all configurations, but for the most part, it's done.
INDEED!!!
FAQ:
- Q: IS THIS A REAL PROTOCOL?
- A: YES!!!
POKEY PERSONAL PROXY/MIRROR (PPP/M) Protocol Reference
Please note: this protocol is an open standard. Send any suggestions to mmastrac@ucalgary.ca,or share them in EFNet #pokey.
The POKEY PERSONAL PROXY/MIRROR (PPP/M) protocol is used to synchronize either a personal collection of POKEY comics, or a POKEY strip mirror. If a POKEY MIRROR SYNC TOOL is run nightly from a cron or at job, it can keep the mirror up-to-date with a minimum of effort.
The PPP/M protocol consists of three phases: a handshaking phase, where the client and server exchange information; a transmission phase, where the client can request a strip, a set of strips or other information and a termination phase, which finishes the connection. The protocol is triggered by a connection on the port, which defaults to 3746 (0x0ea2). These protocols are defined below.
Very Important General Protocol Specifications
If at any point during the communication the connection becomes idle for a period exceeding thirty seconds, the connection may be terminated. The server may also limit the number of concurrent connections, but must allow for a minimum of ten simultaneous open connections.
With the exception of binary transfer mode, any two adjoining whitespace characters in any transmitted string (transmitted by either the client or the server) may be reduced to one. As well, the whitespace at the beginning and end of a line may be clipped off. According to these rules, the following lines are all equivalent:
"OLD BEAN"
" OLD BEAN "
" OLD BEAN "
Whitespace is defined as ASCII 32 or ASCII 8. ASCII 0 is always illegal and may not occur anywhere, except binary transfer mode. If any servers or clients return ASCII 0, the client is responsible for driving over to the author's house and knocking them about the head until a new version is released.
Stage 1: Handshaking
When the server receives a connection on its POKEY port, it sits idle, waiting for the client to make the first move. The client begins the handshake process by sending:
HELLO!!! x.y<\n>
Client platform/implementation description<\n>
<\n>
The client sends its supported level of the PPP/M protocol as x.y. For logging purposes, the client also sends a short string describing the OS it runs on, the author of the client and other pertinant information. Examples of this would be (but not limiting in format):
x86 Windows by wincoder v2.33
Generic Linux Pokey by unixguy v2.41 HOORAY!!!
v1.1 of Joe Java's Sun Solaris Pokey Proxy
The description should be less than 40 characters, but the server must allow for at least 256. On receipt of this handshake block (a sequence of two linefeeds), and assuming the request was well-formed and valid (see below), the server sends its information block:
HOORAY!!! x.y<\n>
Server platform/implementation description<\n>
<\n>
As for the client, the server's supported POKEY protocol level is returned in the format x.y. The server may send back a protocol version which may be less than the supported protocol version of the client, so the client must be backwards compatible. If the server cannot accommidate the protocol version requested, it sends the following block instead and terminates the connection:
NUTS TO YOUR PROTOCOL!!!<\n>
Reason for disconnection<\n>
<\n>
The reason for disconnection should be human readable. Any client should fail the operation immediately on receipt of this message, possibly logging or displaying it to the user, as it represents a protocol incompatibility with the server which cannot be resolved without intervention. Examples of the reason include, but are not limited to:
I DON'T UNDERSTAND YOUR MOONSPEAK!!! YOUR PROTOCOL IS WEIRD!!!
YOUR VERSION IS TOO OLD AND TOO WEAK!!!
Once the server has transmitted its handshake, both the server and client may proceed to Stage 2.
Stage 2: Transmission
Once the initial handshake is out of the way, the client sends a command or request to the server. Each command will respond in either a text or binary fashion. Text responses are of the form:
name_1: value_1<\n>
name_2: value_2<\n>
name_3: value_3<\n>
etc...
name_n: value_n<\n>
<\n>
"name_n" may contain any alphanumeric characters, while "value_n" may contain any characters.
Binary responses are of the form:
BINARY-LENGTH: xxx<\n>
exactly xxx bytes of binary data<\n>
<\n>
If in either a text or binary transmission an error occurs, or an invalid command is sent, the response takes the form:
ERROR
Error message<\n>
<\n>
If the client believes it has become out of sync with the server, it may send the RESYNC command periodically to the server, but should wait a minimum of 1/10 second between tries.
The following commands are defined by this protocol specification. Note that the Response Detail contains a suggested order and the actual response is not required to follow that order.
BAH: I STARTED GETTING TIRED, SO I
DON'T VOUCH FOR ANY OF THE INFO FOLLOWING THIS POINT
EPISODEINFO episodenum
Usage: Retrieves information about a certain POKEY episode. If stripnum is zero, higher than maxpokey from POKEYINFO or contains illegal characters, an error will be returned. If the server is currently updating the episode for some reason, it should return an error as well. Clients should attempt to transfer all the episodes they wish and display either a play-by-play status, or save the error messages until the end of the batch transfer, display them afterwards for the user's viewing pleasure.
Response Type: Text
Response Detail:
episodename: The name of this POKEY episode.
maxpanels: The number of panels in the episode.
GETHTMLHEADER/GETHTMLFOOTER
Usage: Retrieves the HTML template surrounding each episode. (possibly depreciated -- generate your own pages using the standard format from http://www.yellow5.com/pokey).
Response Type: Binary
GETPANEL episodenum panelnum
Usage: Retrieves the specified panel from the specified episode in GIF format, using binary mode. The client should store the panel's .gif file in the archive directory, with a name like pokeyepisode_panel.gif (ie: pokey10_1.gif or pokey123_4.gif).
Response Type: Binary
GETEPISODE episodenum
Usage: Retrieves the specified episode from the server, but concatenates all the panels into a single, large GIF. The client should store this file as pokeyepisode.gif.
Response Type: Binary
MOTD
Usage: Obtains the message-of-the-day (MOTD) from the server. The MOTD is usually set by the system operator and reflects the current system status. Clients should usually request this before proceeding and display it to the user. The MOTD may not contain linefeeds and will be word-wrapped by the client if necessary.
Response Type: Text
Response Detail:
motd: message-of-the-day
POKEYINFO
Usage: Retrieves the overall status of the POKEY server. Before requesting any files, the client should use this information to determine which, if any, strips need to be transferred.
Response Type: Text
Response Detail:
servercomment: Contains a small comment from the system
administrator, more generic than the MOTD.
maxpokey: The highest POKEY episode that the server has
available.
RESYNC
Usage: Used to get the client and server back in sync, after a possible desync. When the client received a timely response to the command and receives nothing else for a moment, it can assume that the client and server are back in sync.
Response Type: Text
Response Detail:
resync: I AM RESYNCING!!!
POKEYINFO
Usage: Retrieves the overall status of the POKEY server. Before requesting any files, the client should use this information to determine which, if any, strips need to be transferred.
Response Type: Text
Response Detail:
servercomment: Contains a small comment from the system
administrator, more generic than the MOTD.
maxpokey: The highest POKEY episode that the server has
available.
Miscellaneous Notes
In general, POKEY episodes are stored in an archives/ directory. They are named pokeyepisode_panel.gif. The index files to read them are named indexepisode.html. This is the current organization used by the mirrors right now, and is not likely to change.
For episode titles, it is usually sufficient to generate the HTML files using them. If your program will be serving POKEY episodes, however, you should store them in a separate titles file for later retreival.