APE Protocol overview

Louis Charette edited this page Apr 19, 2014 · 1 revision

The APE Protocol is the gateway of the communication between the APE Server and the APE JavaScript Framework.

Raw and Command

The APE Protocol works with a system of Raw and Command. Raws and commands are in JSON format. They are always sent as JSON arrays, each entry of the array is a JSON object representing a raw or a command. As a mnenonic:

  • Client requests [Protocol CMD],
  • Server sends [Protocol RAW] Both are related and 'mirror' each behaviour at the client - server side.

Error handling

See Protocol errors

Event handling

See Protocol event

Communication

The distribuation of messages to the users is done via clever objects

Pipes

A pipe is the main feature of APE communication system. Pipe are a communication conduit to exchange data between Client and Sever. There are two main type of pipe:

  • Multi pipe or Channel
  • Uni pipe or User Each pipe is identified by a pubid (pseudo-random value generated by the Server, a 32 character key). The pubid is used when you exchange data with server to set on which pipe data is exchanged.

Channels

A channel is a communication conduit that can be directly created by the server or by a user. A channel is automatically created if a user subscribes to a non-existing channel. The APE Server answers directly while sending the pubid of the channel. (Allowing the user to communicate via the pipe of this channel). Each channel has a list of properties, and on the APE default working, that list only contains the name of the channel. Properties can be added via server modules or authorised entities. A channel has two ways of working :

  • Interactive Channel
  • Non-Interactive Channel

Interactive channel

When a user subscribes to an alreay-existing interactive channel, he recieves the list of all the other users who have subscribed to this channel, and can directly communicate with them via the channel pipe.

Non-Interactive channel

The communication pipe of a non-interactive channel is read-only, meaning that users do not know each other, and can't communicate via the channel. Only authorized entities are allowed to do so. A non-interactive channel is automaticaly created when the first character of its name is a wildcard (*)

Users

When a user connects to APE, a pipe is created to facilitate communication with other entities, and a unique sessid is assigned to the pipe. The sessid allows Server to identify the user that sent each command. As channels, a user has a list of properties, empty by default. A user can perform actions (CMD's) that allow them, by default, to :

  • Post a message on a pipe (channel or another user)
  • Subscribe to a channel (also called 'join a channel')
  • Unsubscribe a channel (also called 'leave a channel')
  • Create a channel (If they subscribe to an non-existent channel)

Server side storage

The protocol allows storage of variables on the server side. The client can store key/value pairs on the server. Values stored are kept until the user disconnects or timeouts. For more information see store raw and retreive command.

Sessions

The APE Protocol has a session feature. This feature is used to handle multiple windows/tabs. Each window/tab must use a different url to connect to server. If the server in the http header detects a different host from the same client (client is identified with pubid) it must first send a raw IDENT and CHANNEL (if user are on any channel). Each raw sent by server must be forwarded to other client. This feature is also used to restore the state of an application after a user refreshes the page. See [Protocol Session] for an example.

Channels

A user can join (or be forced to join) a channel. There is no limit to the number of a channels that a user can join. What are channels for, you ask? They're just a way to send data to multiple users at once.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.