-
Notifications
You must be signed in to change notification settings - Fork 104
APE Protocol overview
The APE Protocol is the gateway of the communication between the APE Server and the APE JavaScript Framework.
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.
See Protocol errors
See Protocol event
The distribuation of messages to the users is done via clever objects
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.
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
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.
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 (*)
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)
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.
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.
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.