ADD_TEXTILE("developer_arch.textile" "Spectrum 2 - Architecture")

ADD_TEXTILE("developer_lowlevel.textile" "Spectrum 2 - Low level backend creation")

Spectrum 2 consist of several separate parts which cooperates together. This page describes them.

!backend.png!

h2. Where are all those things in git-tree?

|_. Directory|_. Description|

|./src|Libtransport source codes|

|./include/transport|Libtransport headers|

|./plugin/cpp|Libtransport-plugin source codes|

|./backends/*|Various Spectrum 2 backends source codes|

h2. Libtransport

Libtransport is library providing the high-level interface for creating XMPP transports. It's used by the Spectrum 2 and by several transports.

Libtransport contains NetworkPluginServer class, which acts as server to which backends connect. Libtransport spawns the backend's processes when they are needed (for example when new user logs in) and destroys them when they are not needed anymore (for example when there are no active users on the backend).

Libtransport is used by:

|_. Name|_. Reason|

|Spectrum 2|It's the Spectrum 2 core|

|Some backends|Connect the Spectrum2, use of Spectrum 2 database, parsing the config file, ...|

Libtransport uses:

|_. Name|_. Reason|

|Swiften library|Connecting to Jabber sever and sending/receiving data from XMPP users|

|log4cxx|Logging|

|protobuf|Protocol for libtransport - backends communication|

|mysql-client|MySQL support|

|sqlite3|SQLite3 support|

|pqxx|PostgreSQL support|

h2. Libtransport-plugin

Libtransport-plugin is subset of Libtransport library and contains only basic things for backend development. The goal is to have smaller library with the less dependencies than Libtransport.

The Libtransport-plugin contains NetworkPlugin class, which is the base class for every @C++@ backend. Programmer has to create his own class inherited from this one and implement all the virtual methods to create new backend.

Libtransport-plugin is used by:

|_. Name|_. Reason|

|All Backends|Connect the Spectrum 2, parsing the config file|

Libtransport-plugin uses:

|_. Name|_. Reason|

|log4cxx|Logging|

|protobuf|Protocol for libtransport - backends communication|

h2. Spectrum 2

Main Spectrum 2 binary just uses Libtransport and it's core classes to create particular Spectrum 2 instance.

Spectrum2 uses:

|_. Name|_. Reason|

|Libtransport|Core library...|

h2. Backends

Backends allow communication with particular legacy network and implements things like logging the user in, sending/receiving messages from legacy network and so on. Backend's life-cycle is controlled by the Spectrum 2 (or better said by the Libtransport's NetworkPluginServer class).

Spectrum 2 spawns the backend and gives it @"--host localhost --port 32453"@ parameters. Backend then has to connect the Spectrum 2 located at the given host/port and start receiving the commands sent by the Spectrum 2 main instance. For C++, there is wrapper class called NetworkPlugin which does the parsing and allows programmer to code backend just by implementing few virtual methods.

This page is useful only if you want to write backend in a language for which there's no NetworkPlugin class ready or if you just want to know what protocol Spectrum 2 uses to communicate with backends.

h2. Packets

Spectrum 2 main instance and its backends communicate using TCP socket. Packets sent over this socket are serialized using Google Protobuf library. This library has bindings (unofficial) for many programming languages.

Packets look like this:

|_. Byte|_. Description|

|0-4| Length of payload sent in this packet in network byte order as generated by uint32_t htonl(uint32_t hostlong); method.|

|4-x| WrapperMessage payload serialized using Google Protobuf.|

h3. WrapperMessage payload

This Protobuf object is used to contain payloads of different types. Every payload type has its own type and Protobuf object representing it. All payloads are explained later in this document.

All objects which can be used as payload in WrapperMessage object are declared in "include/transport/protocol.proto":https://github.com/hanzz/libtransport/blob/master/include/transport/protocol.proto.

h2. Spawning the backend

1. Spectrum 2 main instance spawns the backend when it's needed. Backend is executed with following arguments: @"--host localhost --port 32453"@.

2. Backend has to initalize itself and connect the Spectrum 2 main instance using @host@ and @port@.

3. Spectrum 2 main instance sends packet with payload of TYPE_PING (stored in WrapperMessage object).

4. Backend answers the TYPE_PING payload with TYPE_PONG payload and since the requests are forwarded to it.

h2. User wants to login the legacy network

1. @Type: TYPE_LOGIN, Payload: Login@ packet is sent to backend, backend starts connecting the user to legacy network.

2. When the user is connected, it populates his roster using @Type: TYPE_BUDDY_CHANGED, Payload: Buddy@ packets.

3. It sends @Type: TYPE_CONNECTED, Payload: Connected@ packet to Spectrum 2 main instance to inform it that user is connected to legacy network.

If something goes bad during the login process or later, backend sends @Type: TYPE_DISCONNECTED, Payload: Disconnected@ packet at any time.

h2. User wants to join the room

1. @Type: TYPE_JOIN_ROOM, Payload: Room@ packet is sent to backend, backend starts joining the user to the room.

2. Backend populates room's participant list using @Type: TYPE_PARTICIPANT_CHANGED, Payload: Participant@ packets. As last Participant it has to send the user itself.

3. Backend can change room subject using @Type: TYPE_ROOM_SUBJECT_CHANGED, Payload: ConversationMessage@.

h2. WrapperMessage payloads sent by Spectrum 2 main instance

This chapter describes all possible payloads which can be sent by Spectrum 2 main instance to backend and therefore received by backend. It also describes what should backend do when it receives payload of that type and what should sends back to Spectrum 2 main instance.

h3. Type: TYPE_PING, Payload: Nothing

Backend has to responds with @Type: TYPE_PONG, Payload: Nothing@ payload. If it does not responds in 20 seconds, it's terminated.

h3. Type: TYPE_LOGIN, Payload: Login

Backend has to login this user to legacy network. When it logins the user, it has to send @Type: TYPE_CONNECTED, Payload: Connected@ back to transport. If the backend is not able to login the user, it has to send @Type: TYPE_DISCONNECTED, Payload: Disconnected@

|_. Variable|_. Description|

|user| JID of XMPP user who wants to login|

|legacyName| Legacy network user name (for example ICQ number) of the user|

|password|Legacy network password|

h3. Type: TYPE_LOGOUT, Payload: Logout

Backend has to logout user from legacy network.

|_. Variable|_. Description|

|user| JID of XMPP user|

|legacyName| Legacy network user name (for example ICQ number) of the user|

h3. Type: TYPE_STATUS_CHANGED, Payload: Status

Backend has to change the legacy network status of this user.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|status| Status as defined by StatusType enum in protocol.proto|

|statusMessage|Status message|

h3. Type: TYPE_JOIN_ROOM, Payload: Room

Backend has to join this user to the room. Backend has to send list of participants back to Spectrum 2 using @Type: TYPE_PARTICIPANT_CHANGED, Payload: Participant@. As a last participant, the user who wanted to join the room has to be sent.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|nickname| Nickname used to join the room|

|room|Name of the room|

|password|password|

h3. Type: TYPE_LEAVE_ROOM, Payload: Room

Backend has to disconnect this user from the room.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|nickname| Nickname used to join the room|

|room|Name of the room|

h3. Type: TYPE_BUDDY_TYPING, Payload: Buddy

Backend should forward to buddy represented by buddyName information that XMPP user is typing now.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_TYPED, Payload: Buddy

Backend should forward to buddy represented by buddyName information that XMPP user paused typing now.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_STOPPED_TYPED, Payload: Buddy

Backend should forward to buddy represented by buddyName information that XMPP user stopped tying and is not typing for some time.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_REMOVED, Payload: Buddy

Backend should remove buddy from the legacy network contact list.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_CHANGED, Payload: Buddy

Backend should change the buddy alias or group according to Buddy payload. If the buddy is not stored in legacy network contact list yet, it should add it there. Backend has to send @Type: TYPE_BUDDY_CHANGED, Payload: Buddy@ back.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|alias|Alias|

|group|Group|

|blocked| True if this buddy should be blocked|

h3. Type: TYPE_ATTENTION, Payload: ConversationMessage

Backend should forward to buddy represented by buddyName information that XMPP user wants his attention.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|message| Message|

h3. Type: TYPE_CONV_MESSAGE, Payload: ConversationMessage

Backend should forward to buddy represented by buddyName message received from user.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|message|Plain text message|

|xhtml|Message formatted using XHTML-IM XEP if available|

h3. Type: TYPE_VCARD, Payload: VCard

If buddyName is empty, backend should update XMPP user's VCard according to VCard payload. If buddyName is not empty, backend has to fetch VCard of buddyName buddy including photo send it back using @Type: TYPE_VCard, Payload: Buddy@

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|id|Id used when sending the response with buddy's photo back. You have to use the same id in response as you received in request.|

|photo| Binary photo|

|nickname|Nickname|

h2. WrapperMessage payloads sent by backend

This chapter describes all possible payloads which can be sent by backend to Spectrum 2 main instance.

h3. Type: TYPE_CONV_MESSAGE, Payload: ConversationMessage

Backend sends this payload when it receives new message from legacy network which should be forwarded to XMPP user.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network who sent the message. If the conversation is room, buddyName is name of the room.|

|message|Plain text message|

|xhtml|Message formatted using XHTML-IM XEP if available|

|nickname| If the conversation is room, this is the nickname of user who sent the original message|

h3. Type: TYPE_ATTENTION, Payload: ConversationMessage

Backend sends this payload when it receives attention request from legacy network which should be forwarded to XMPP user.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|message| Message|

h3. Type: TYPE_VCARD, Payload: VCard

Backend sends this payload as a response to @Type: TYPE_VCARD, Payload: VCard@ received from main Spectrum 2 instance.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|id|You have to use the same id in response as you received in request.|

|photo| Binary photo|

|nickname|Nickname|

h3. Type: TYPE_ROOM_SUBJECT_CHANGED, Payload: ConversationMessage

Backend sends this payload when it receives room subject from legacy network which should be forwarded to XMPP user.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the room.|

|message|Plain text subject.|

|nickname| Nickname of user who set the subject.|

h3. Type: TYPE_BUDDY_TYPING, Payload: Buddy

Backend sends this payload when buddy starts typing.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_TYPED, Payload: Buddy

Backend sends this payload when buddy paused typing.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_STOPPED_TYPED, Payload: Buddy

Backend sends this payload when buddy is not typing anymore.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_BUDDY_CHANGED, Payload: Buddy

Backend sends this payload when some information about Buddy changed.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

|alias|Alias|

|group|Group|

|blocked| True if this buddy should be blocked|

h3. Type: TYPE_BUDDY_REMOVED, Payload: Buddy

Backend sends this payload when it removes buddy from legacy network contact list or the buddy gets removed from the contact lists somehow.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_AUTH_REQUEST, Payload: Buddy

Backend sends this payload when it receives authorization request from legacy network. If XMPP user accepts the authorization request, Spectrum 2 main instances sends @Type: TYPE_BUDDY_CHANGED, Payload: Buddy@ to backend, otherwise it will send @Type: TYPE_BUDDY_REMOVED, Payload: Buddy@.

|_. Variable|_. Description|

|userName| JID of XMPP user|

|buddyName| Name of the buddy in legacy network|

h3. Type: TYPE_CONNECTED, Payload: Connected

Backend sends this payload when it connects the user to legacy network.

h3. Type: TYPE_DISCONNECTED, Payload: Disconnected

Backend sends this payload when it disconnects the user from legacy network.

h2. Development

* "Spectrum 2 architecture":developer_arch.html

* "Low level backend creation":developer_lowlevel.html

code {

	border: 1px solid #FB7A31;

	background: #FFC;

}