shinGETsu - P2P BBS

shinGETsu Protocol 0.7 draft #1



This is a transration of the shinGETsu protocol 0.6 (Japanese version) and the Japanese version supersedes any other language version.

The protocol has 4 layers:

  1. Communication layer
  2. Intermediate layer
  3. Application layer
  4. Application group

Communication Layer

Elements of shinGETsu Network

shinGETsu network is composed of connection between nodes. Each nodes have uniq name called node name. They have names of other nodes called linked nodes to keep connection. When node A knows node B, node B not has to know node A.

The message between nodes bases on HTTP/1.0 or HTTP/1.1. The response of node is assumed plain text with UTF-8 encoding. A message command is made into URLs.


Node is a unit of program or computer with shinGETsu protocol. Node name format is defined:

<hostname>:<port number>/<path>

where hostname is a DNS hostname or IP address (IPv4) and port number is a decimal number.


Message is information exchanged between nodes including message command and responce. The responce is able to be gziped. It uses HTTP_ACCEPT_ENCODING and Content-Encoding HTTP headers.


The epoch time is 1970-01-01T00:00Z. Time is described by integer that means seconds from the epoc time.

Message Command

The URL made from a message has following form:

It is an example for ping command.

Now we describe message command and responces. \n is a line-feed (0x0a). Sender means message command sender.

Return PONG\n<sender's IP address>
Return the name of one of linked nodes.
/join/<sender's node name>
The node evaluates sender. If the node link the sender, it returns WELCOME or WELCOME\n<name of one of linked nodes>
The evaluation can include sending /ping command and resolving hostname of sender, but we do not define here. The sender's hostname can be skipped. The sender's path is replaced '/' into '+'. Sender has to link the node and suggested node.
/bye/<sender's node name>
Unlink sender and return BYEBYE. The node can evaluate sender.
/have/<file name>
Return YES or NO that means it has the file or not.
/get/<file name>/<time option>
Return records which are included in the file and fulfill the time option. The time option is one of following formats:
  • <stamp> - the records at the timestamp
  • -<stamp> - the records before or at the timestamp
  • <stamp>- - the records after or at the timestamp
  • <stamp1>-<stamp2> - the records between timestamp1 and timestamp2
  • <stamp>/<ID> - the record at the timestamp and with the ID
/head/<file name>/<time option>
Return responce like /get command. However return only timestamp and ID foreach records.
/update/<file name>/<timestamp>/<ID>/<node name>
It means the node with the node name has the new record with the timestamp and the ID. If the node has treated the update, the node does nothing. If the node has the file, the node updates the file, replace the node name its name, and send message to linked node. Else relay the message to linked node. The hostname can be skipped. The sender's path is replaced '/' into '+'.
/recent/<time option>
Return record names which are updated and fulfill the time option. The time option is one of following formats:
  • <stamp> - the records at the timestamp
  • -<stamp> - the records before or at the timestamp
  • <stamp>- - the records after or at the timestamp
  • <stamp1>-<stamp2> - the records between timestamp1 and timestamp2
The responce format is: timestamp<>ID<>file name. It is able to add tags each lines with this format: timestamp<>ID<>file name<>tag:tags. The tags are separated with spaces. Tags cannot include space, <, >, and &.
Any responces are allowed.


Nodes can send /update command when file is updated.


File is set of records that constitut one BBS, it can be empty set. The file format is joind records with \n. File has infinite length, and we can treat a part of it.


Record is element of the file. Record format is:


The ID is MD5 checksum of the entity. The timestamp is seconds from the epoch time.

Intermediate Layer

File Name

File name format is <prefix><basenam>. Prefix is [0-9A-Za-z]+ and basename is [0-9A-Za-z_]+.

Prefix means type of the file and basename can mean 'name' of the file. Application defines file name.

Format of Entity

Elements of entity is separated by '<>'. The element is named field which format is <field name>:<field value>. The field name is [0-9A-Za-z_]+. The field name has to be uniq and processing for duplication is relianced on the implementation. Field names 'stamp' and 'id' are reserved; stamp is timestamp and id is ID. The order of field is optional. The field value must not include '<' or '>'. However the tags '<string>' can be included in field value (the string length shoud be more than 0, and it must not include '<>'). Application defines tag.


See shinGETsu Protocol 0.5 draft#2 PDF.

Signature Fields

Public key.
Signature targets names joined by ','.

Remove Information Field

Target timestamp.
Target ID.

You can make implementation using the communication layer withou the intermediate layer. Such implementations are called ``communication layer compatible''.

Application Layer

Plugin and Application

Plugin is not defined now.

Application is a plugin that define file format. The application defined this protocol is thread only. In past there were 8 applications. Application is differ from implementation.

Any implementation can define an application. Such implementations are called ``intermediate layer compatible''.

Thread Application

The BBS application.

File Name

The format is thread_<encoded title>. Encoded title is a UTF-8 title converted into hexadecimal notation ([0-9A-F]+).

Named Fields

Name of the author.
Mail address of the author.
Post body. The allowed tag is '<br>' means new line. '<BR>' or '<br />' are not allowed.
Attachment file encoded with base64 algorithm.
Suffix of the attachment file

Application Group

Application group is the standard to incorporate applications.

Wiki Style Namespace Application Group

Bracket Link

Applications have to make links from following bracket links.

The standard format is [[/<type>/<string>]] where type is a name of application, string is defined by the application. '/<type>/' can be skipped, and when it is skipped the type is identified by the application type.

Now the defined application is thread, and we describe bracket links of thread for example.

Link from a thread to the thread named 'THREAD'.
Link from a thread to the record with id '7889e7db' in the thread named 'THREAD'.
Link from any application to the record with id '7889e7db' in the thread named 'THREAD'.

Comment this: [[Development BBS]]

Copyright© 2003-2024 shinGETsu Project. All Rights Reserved. (Legal Notices)