Preamble

This messaging Service is pretty similar to the ActiveMQ broker from Apache. This one is written in go and is very simple structured and therefore a fast and easy to use messaging service.

Basic stuff

Topics

This service is based in the so called topics that are familiar since ActiveMQ used them too. A topics is just a key on which you can send or receive messages to/from.

CLients can register themself to a topic and is allowed to receive and send message to it.

All topic names are lowercase letters! A registration with some capital letters (e.g. camel-case like "aCoolTopicName") will be changed into lowercase names.

Messages

A message is the whole data send by the server or the client. The data in the message is sometimes also calles message, because it's the most important thing, but is in the goMS world just the message-data.

The message-data can be everything and of (currently) any size. Normally it would be some XML, JSON or insert-your-favorite-file-format-here data and thats fine.

In the JSON-message (see below) will everything be escaped, but you can send everything you like.

Message types

There're different types of messages, namely register, send, message, logout, close and error.

register

Client → Server

Need the field topics with a list of topics. A client can only connect to topics, that are configured in the server config.

send

Client → Server

Needs the fields topics and data. The field topics contains all topics the data goes to. The field data contains all data that will be send as message to all registered clients.

message

Server → Client

Only contains the data field from the send message.

logout

Client → Server

Needs the field topics which is a list of all topics the client wants to unregister himself of.

close

Client → Server

Needs no fields.

error

Server → Client

Contains the field error-code which is normally a number (like the HTTP status codes) and the field error which contains some data belonging to the error (meaning of error codes below).

Server stuff

Here're some information about the server (usage, configuration and internals).

Configuration

Topics

To limit the amount of topics, a client is not able to create one. This is the responsibility of the server administrator. The file /conf/topics.json contains all available topics. It's a simple json list like this one:

{
  "topics":[
    "technology",
    "goms",
    "golang"
  ]
}

General

{
    "topic-config":"path/to/topics.json",
    "connectors":[
        {
            "protocoll":"tcp",
            "ip":"127.0.0.1",
            "port":55545
        }
    ]
}

The following fields need to be specified:

The Connector

A connector is a specification of a listener, the server is listening on.

Connect with server

The process of connecting and notifying is described below.

It's very important to do these steps in the given order, otheriwse your request will be ignored. For example: If you send a message to a topic before register yourself to it, your request will be ignored.

1.) Connecting to server

1. Client creates normal TCP-connection on the port specified in the connectors of the server configuration (default is 55545)

2.) Register to a topic

1. Client sends the topics as JSON-list to the server:

   {
   "type": "register",
   "topics": [
    "some",
    "topics"
   ]
   }

2. Server saves the client in his internal map

Maybe there'll be an acknowledgement from the server (not implemented yet):

1. Server sends notification that everything is ready:

   {
   "type": "reg-ack"
   }

   It's also possible (for error-correction) to send the list of topics within the acknowledgement (but as mentioned above: not yet implemented):

   {
   "type": "reg-ack",
   "topics": [
    "some",
    "topics"
   ]
   }

3.) Distribute messages

1. Client sends a send request of the following form to the server:

   {
   "type": "send",
   "topics": [
    "some",
    "topics"
   ],
   "data": "This will be the data to send."
   }

2. The server will then look into his map to determine all connections to clients which registeres themselves, and then send the message. The message will have this simple format:

   {
   "type": "message",
   "data": "This is the sent message."
   }

   There will be no acknowledgement from the client about the messages. We trust in the TCP protocoll and the client/server implmenetation.

4.) Logout from a topic

Just send the logout-message:

1. Client removes himself from some topics.

   {
   "type": "logout",
   "topics": [
    "some",
    "topics"
   ]
   }

   The topics list is optional, leaving it out will logout the client from all topics.

5.) Close connection

If you want to be kind to the server, you can use the close-message:

1. Client closes connection, this will remove him from all topics (of course).

   {
   "type": "close"
   }

Errors

Now some words about the error message (s. above).

This list of numbers and codes may not be up-to-date and also may change very quickly, so don't wonder about differeces.

Categories

To structure the whole thing, each message has its own category.

Error-code list

000

001

002

003

004

Planned things

• Create users (with optional password) for server, to allow multiple topics with the same name within a single server. A user can create an account at the service provider (e.g. a website that runs this server) and then setup his/her own message service.
• Do not allow the creation of new topics (only via config-file) implemented
• Every user has it's own directory with own config file
• Cache huge files (e.g. images or huge XML files) and just send a reference. The client then can download it when needed. Therefore new message-types must be created (reference and download). The files are cahced withing the usrers directory