| summaryrefslogtreecommitdiff |
diff options
| -rw-r--r-- | README.md | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..fe3931c --- /dev/null +++ b/README.md @@ -0,0 +1,226 @@ +# JabberHive Protocol - Version 1 +Additional content may be added to this specification should ambiguities need to +be removed, but the set of Inter-component Communication it defines below +is final and constitutes the version 1 of the protocol. + +## Table of Contents +1. [Introduction] (#introduction) +2. [Components] (#components) +3. [Inter-component Communication] (#inter-component-communication) +4. [Examples] (#examples) +5. [Copyright] (#copyright) + +## 1. Introduction +* *Make each program do one thing well. To do a new job, build afresh rather + than complicate old programs by adding new "features".* +* *Expect the output of every program to become the input to another, as yet + unknown, program.* + +\- Doug MCIlroy + +* *Write programs that do one thing and do it well.* +* *Write programs to work together.* +* *Write programs to handle text streams, because that is a universal + interface.* + +\- Peter H. Salus + +Such is the base of the Unix Philosophy, and such is what tries to follow the +JabberHive protocol. Indeed, there may are plenty of Markov Chain Chatbots +available, but nearly all of them are made of a single program, for a single +communication protocol, with optional features making their code grow in +complexity. Instead of a single program, a JabberHive Chatbot is a network of +interconnected Components that all use the same text-based protocol. This lets +developer add functionalities without having to even look at the existing code, +by simply making a new component (in pretty much any programming language). + +## 2. Components +There are three types of components: servers, filters, and gateways. + +Generally, servers handle requests, filters transform that pass through, and +gateways generate the requests. + +The number of connections accepted by (and initialized by) components may be +higher than one. Refer to a component's manual to know how it embeds itself in +the network. + +### Server +Must accept at least one connection. +Those components are assumed to be the knowledge database. This is where the +actual reply creation, and the learning, are done. + +### Filter +Must accept, and generate, at least one connection. + +### Gateway +Must generate at least one connection. Gateways allow other communication +protocols to communicate with the JabberHive network. Those are expected to be +the main initiator of requests. + +## 3. Inter-component Communication +All messages are text based. Messages structure is as follows: +``` +++++++++++++++++++++++++++++++ ++ TAG + ' ' + CONTENT + '\n' + +++++++++++++++++++++++++++++++ +``` +* TAG is not allowed to contain white spaces. +* TAG and CONTENT are not allowed to contain '\n'. + +Any request leads to at least one reply. Indeed, each sequence of replies is +terminated by either a "Positive" or a "Negative" reply. + +A connection between two components is directional in the sense that +only one of the two component makes requests and the other one gives replies. + +Unless Pipelining is supported by the component to which requests are made, +simultaneous requests on a connection are not permitted: the request making +component must wait for its previous request to be completed before making a +new one. + +Exchanges should be considered as happening between two directly connected +components, not from a gateway to a server through filters. Indeed, filters +may generate any number of requests of their own to handle an incoming request, +as long as it is transparent to the component that made said incoming request. + +Even if there is no CONTENT, the TAG and '\n' are separated by a space. +"Any string" includes empty string. Strings are not null terminated. + +### Requests +#### Request Protocol Version +* **TAG:** `?RPV`. +* **CONTENT:** List of comma separated unsigned integers, in a ascending order. +* **Example(s):** `?RPV 1,66,2910`, `?RPV 1`. + +Upon reception of one such message, one should start using the latest JabberHive +protocol version listed in CONTENT that one can. If none are supported, a +"Negative" reply is sent. Otherwise, a "Confirm Protocol Version" message is +sent, followed by a "Positive" reply. + +#### Request Pipelining Support +* **TAG:** `?RPS` +* **CONTENT:** None. +* **Example(s):** `?RPS `. + +Asks the component if it supports handling simultaneous requests from the same +connection. A "Confirm Pipelining Support" reply is returned, followed by a +"Positive reply" (regardless of whether pipelining is supported or not). + +#### Request Learn +* **TAG:** `?RL` +* **CONTENT:** Any string. +* **Example(s):** `?RL Anything the bot may have to learn.`, `?RL Other.`. + +Requests the learning of CONTENT. Response is either a "Positive" message, or a +"Negative" message. + +#### Request Reply +* **TAG:** `?RR` +* **CONTENT:** Any string. +* **Example(s):** `?RR Generated replies will be based on this.`, `?RR hello`. + +Requests the generation of a reply to CONTENT. Response is be either a +"Positive" message preceded by a "Generated Reply" message, or a "Negative" +message. + +#### Request Learn & Reply +* **TAG:** `?RLR` +* **CONTENT:** Any string. +* **Example(s):** `?RLR Generated replies will be based on this.`, + `?RLR Other.`. + +Requests the learning of CONTENT, followed by the generation of a reply. +Response is either a "Positive: message preceded by a "Generated Reply" message, +or a "Negative" message. + +### Replies +#### Confirm Protocol Version +* **TAG:** `!CPV` +* **CONTENT:** Unsigned integer. +* **Example(s):** `!CPV 1`, `!CPV 29110`. + +Indicates the JabberHive protocol version that will henceforth be used. + +#### Confirm Pipelining Support +* **TAG:** `!CPS` +* **CONTENT:** 1 or 0. +* **Example(s):** `!CPS 0`, `!CPS 1`. + +Indicates that the component supports (if CONTENT is set to 1), or does not +support (if CONTENT is set to 0) handling simultaneous requests from the +same connection. + +#### Generated Reply +* **TAG:** `!GR` +* **CONTENT:** Any string. +* **Example(s):** `!GR I am not a robot.`, `!GR hi dan`. + +This is a string that has been generated because of the previous request. + +#### Additional Information +* **TAG:** `!AI` +* **CONTENT:** Any string. +* **Example(s):** `!AI [E] Would overflow.`, `!AI [W] Could not store data.`. + +Allows the transmission of information for debugging purposes. + +#### Positive +* **TAG:** `!P` +* **CONTENT:** None. +* **Example(s):** `!P `. + +Previous request has been completed (no more messages related to it will be +sent). + +#### Negative +* **TAG:** `!N` +* **CONTENT:** None. +* **Example(s):** `!N `. + +Previous request could not be completed (no more messages related to it will be +sent). + +### Dealing With Unknown Tags +| Component | Request | Reply | +| ----------- | :-------: | :-------: | +| **Server** | Reply !N | N/A | +| **Filter** | Propagate | Propagate | +| **Gateway** | N/A | Discard | + +## 4. Examples +### Networks +``` +++++++++++++++++ +++++++++++++++++ ++ SERVER (RAM) +---+ GATEWAY (IRC) + +++++++++++++++++ +++++++++++++++++ +``` +``` + +++++++++++++++++ +++++++++++++++++++++ + + GATEWAY (CLI) + + GATEWAY (DISCORD) + + +++++++++++++++++ +++++++++++++++++++++ + | | + | | + | | +++++++++++++++++ ++++++++++++++++++++ ++++++++++++++++++++ ++ SERVER (RAM) +---+ FILTER (STORAGE) +---+ FILTER (LIMITER) + +++++++++++++++++ ++++++++++++++++++++ ++++++++++++++++++++ + | | + | | + | | ++++++++++++++++++++++ +++++++++++++++++ ++ GATEWAY (STORAGE) + + GATEWAY (IRC) + ++++++++++++++++++++++ +++++++++++++++++ +``` +``` +++++++++++++++++ ++ SERVER (RAM) +---| +++++++++++++++++ | + | +++++++++++++++++ ++++++++++++++++++++++++++ +++++++++++++++++ ++ SERVER (RAM) +---+ FILTER (ROUND ROBIN) +---+ GATEWAY (CLI) + +++++++++++++++++ ++++++++++++++++++++++++++ +++++++++++++++++ + | +++++++++++++++++ | ++ SERVER (RAM) +---| +++++++++++++++++ +``` |