shinGETsu Protocol 0.7 draft #1
2007-01-15
Introduction
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:
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
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
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.
Time
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:
http://example.com:8000/server.cgi/ping
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.
- /ping
- Return
PONG\n<sender's IP address> - /node
- 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
WELCOMEorWELCOME\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
YESorNOthat 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
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.
Transmission
Nodes can send /update command when file is updated.
File
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
Record is element of the file. Record format is:
timestamp<>ID<>entity
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.
Signature
See shinGETsu Protocol 0.5 draft#2 PDF.
Signature Fields
- pubkey
- Public key.
- sign
- Signature.
- target
- Signature targets names joined by ','.
Remove Information Field
- remove_stamp
- Target timestamp.
- remove_id
- 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
- Name of the author.
- Mail address of the author.
- body
- Post body. The allowed tag is '<br>' means new line. '<BR>' or '<br />' are not allowed.
- attach
- Attachment file encoded with base64 algorithm.
- suffix
- 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.
- [[THREAD]]
- Link from a thread to the thread named 'THREAD'.
- [[THREAD/7889e7db]]
- Link from a thread to the record with id '7889e7db' in the thread named 'THREAD'.
- [[/thread/THREAD/7889e7db]]
- Link from any application to the record with id '7889e7db' in the thread named 'THREAD'.
Comment this: [[Development BBS]]
RSS 1.0