Introduction
This article contains a reference for the IMPULS communication protocol, used to transfer data between the IMPULS daemon and any client or reader.
Besides the protocol reference, requirements and features of the communication are listed and best practices are shown.
License
This file is part of IMPULS (Instant Messenger Personal User Log Storage).
IMPULS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
You should have received a copy of the GNU General Public License along with IMPULS; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Disclaimer
IMPULS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Document State
This document is, like the whole project, in planning and development state. Any statement might be subject to change and cannot be relied on. However, the information given here somehow reflects the current state of the protocol planning and development and daemon, client and reader software are loosely based on the information provided here.
Requirements
In this section, the requirements for the IMPULS communication protocol are discussed. They are the foundation from which the protocol itself is derived and serve as a contract to the connecting software as well. The requirements listed here are met by the procotol and can be relied on.
Features
Authentification
Authentification ensures that each user is only permitted to see his own data and execute functions he is allowed to. It is also used to identify and distinguish users - a prerequisite to have a multi-user environment with only one IMPULS daemon.
Since authentification is a daemon function, it may and does not rely on transport features, such as HTTP authentification or SSL certificates. However, any transport feature may be used to enhance the security of the process.
- entity storage
- entity retrieval
- status
- statistics
- generic interface
Network environment
- restricted LANs:
- proxy
- ssh
- firewall
Portability
- operating system independend
Security
- do not open new ports
- rely on stable software
- encryption
- automated process
Safety
- transaction safety
- consistency
- host failures
- link failures
Performance
- handle huge amounts of data
- reduce overhead
- timeout issues
- asynchronous?
Protocol
Overview
The goal of the IMPULS transmission part is to keep the IMPULS communication independent from the used transmission protocol, i.e. although a protocol like HTTP (Hyper Text Transport Protocol -- RFC 2616) can be used, it may not depend on any protocol specific feature. This is achieved with a protocol encapsulation introducing two virtual network layers: the IMPULS transmission layer and the IMPULS data layer.
As a design aproach, the transmission mechanism should be encapsulated from the data handling for an easier exchange of the transmission method used. The daemon does not differ between transmission paths, but only evaluates the transmitted data. A client/reader developer should strive for a design flexible enough to change the transport mechanism without touching the rest of his software.
IMPULS transmission layer
The transmission layer uses any protocol operating on the OSI application layer. Although any custom protocol may be used here, it is strongly recommended to stick to well-proven standards. For example, with HTTP with proxy support, one could use any internet connection as long as "normal" HTTP queries, i.e. surfing the web, are available.
IMPULS data layer
The data layer settles in the upper half of the OSI application layer and contains data transported with the IMPULS transmission layer. This data is common to any transport mechanism used and should not depend or change due to requirements made by the transmission layer.
However, to keep modularity, the data layer may differ between a resource, which is the destination for the data sent, and the data itself. In an HTTP based transmission layer, the resource would be sent with the HTTP resource in the request line, where the body is sent as an HTTP entity.
If the protocol used for transmission does not support resources in the metadata section, the data layer must be encapsulated to fit the protocol needs.
Naming Scheme
There's no one and only protocol, at least there will be some kind of development in the protocol itself. To reflact this the protocol version get version numbers. Since a protocol changes not as often it is sufficient to have it with a major and a minor number.
Prototype
For milestone 0.2 and ticket #35 we had to make a quick and dirty protocol, so here it is, version 0.2 of the IMPULS data layer according to a Jabber message of Stefan, I hope self explanatory:
[17:07:06] <Tux> ganz einfache Kommunikation: Client schickt sowas: SET MESSENGER LABEL: licq SET ACCOUNT NETWORK: ICQ UIN: 46938079 SET CONTACT NETWORK: ICQ UIN: 50296980 STORE MESSAGE DIRECTION: SENT DATE: 1208099133 METADATA: CONTENT 2 blubb bla STORE MESSAGE DIRECTION: RECEIVED DATE: 1208099139 METADATA: CONTENT 1 8-)
Resources
Each request to the IMPULS daemon is sent to a specific module, which is (hopefully) capable of handling it. To determine the module, a request must provide a resource identifier.
If, for example, there are a database and a statistics module, requests for storing a message could be sent to /database, while any statistics queries are sent to /statistics.
The data layer has to ensure the correct mapping from resources to modules capable of handling the resource. If no module has been found, an error is returned to the client.
Datagrams
Datagrams transport data from the client to the daemon and reverse. The content of each datagram depends of the module receiving it and may differ between the modules. The transmission layer has to ensure correct encoding and decoding of transmitted data, if necessary.
HTTP implementation
The IMPULS prototype, i.e. the first versions, will stick to HTTP as the Transmission Layer protocol. The transport encapsulation and transport will follow later.
Following the recommendations from RFC 2616, chapter 9.1, the Transmission Layer will use the GET method for data retrieval without any side effects, POST, PUT and DELETE can be used in a reasonable manner at will for actions which result in side effects.
Since the Transmission Layer is only used to transport datagrams and may not contain information relevant to the IMPULS communication, it only uses simple methods for data transport.
For the Data Layer encapsulation, only POST requests will be used to send a datagram. All other methods may be used by functions specific to the HTTP implementation.
