-
Notifications
You must be signed in to change notification settings - Fork 47
Euphoria Packet Format
The heim API is transmitted via websocket in units called packets. Each packet is serialized to JSON with UTF-8 encoding for transmission.
Packets originating from the client will always receive a packet from the server in response. If a client sends packets A and B, then the server will always send the response to A before it sends the response to B.
The server may also send packets to the client asynchronously. For example, when a user says something in a room, a packet is broadcast to each other session connected to that room. An asynchronous packet could be transmitted before the response to a client packet is transmitted.
Every packet shares a common top-level structure. Here is a sample ping, sent from the the server to the client on connect.
{
type: "ping-event",
data: {
time:1428979816,
next:1428979846
}
}
The type, and data fields are common to all packets. The type field specifies the command or event being communicated, and this determines the expected structure of the data field. This packet is an example of an asynchronous packet.
Non-asynchronous packets use an id field:
{
id: "1",
type: "send",
data: {
content: "hello ezzie!"
}
}
The id should be given in any packet sent by the client, and its value should be unique in the lifetime of the connection. The server must include the same id when it sends the corresponding response packet, if an id was given.
Heim has data that is transmitted in several packet types and has the same format across those packets.
| Field | Type | Description | | ----: | :------- |:--------| | id | string | | | server_id | string | | | server_era | string | | | session_id | string | | Sample: ``` { id: "agent:8ed8e41c4771ca4f", name: "Max", server_id:"heim.4", server_era:"00g5fg7f12ww0", session_id:"8ed8e41c4771ca4f-00000210", } ``` | Field | Type | Description | | ----: | :------- |:--------| | time | string | Timestamp of when the message was received by Heim. | | id | string | Unique identifier for this message (unique within a room). | | parent | string | Message id of the parent of this message. If blank, message is at top level. | | sender | user | See [user](#user). | | content | string | Content of message. | | edited | boolean | If true, this message has been edited (not implemented). | | deleted | boolean | If true, this message has been deleted (not implemented). | Sample: ``` { time: 1418585715, id:"00gd7wc0qgjcw", parent: "" sender: { id: "agent:8ed8e41c4771ca4f", name: "Max", server_id:"heim.4", server_era:"00g5fg7f12ww0", session_id:"8ed8e41c4771ca4f-00000210" }, content: "hi!", edited:null, deleted:null } ```The following commands are available to the client:
| Type | Purpose |
|---|---|
ping-reply |
Respond to a ping from the server. |
nick |
Modify the user's display name for this session. |
who |
Receive a listing of live users in the room. |
log |
Receive the most recent chat history. |
send |
Send a message to the room's chat. |
| data field | Type | Description |
|---|---|---|
| time | integer | GMT timestamp of number of seconds since the start of the epoch |
Request: {id: "1", type: "ping-reply", data: {time: 1431519995}}
Use the nick command to change the user's display name, for subsequent messages sent from the user and for subsequent listings of the room. The user will not be allowed to send messages to a room before sending a nick packet.
Request: {id: "1", type: "nick", data: {name: "Ezzie"}}
Response:
{
id: "1",
type: "nick-reply",
data: {
id: "agent:61ea7b275e1248f5",
name: "Ezzie",
server_id:"heim.3",
server_era:"00g5femcgk0lc",
session_id:"373f7e9af9f00b71-00000236"
}
}
Other users in the room will be notified of your name change. For a detailed description, see nick-event.
Use the who command to fetch the current list of live users in the room.
Request: {id: "2", type: "who"}
Response:
{
id: "2",
type: "who-reply",
data: [
{
id: "agent:61ea7b275e1248f5",
name: "Logan",
server_id:"heim.3",
server_era:"00g5femcgk0lc",
session_id:"61ea7b275e1248f5-00000236"
},
{
id: "agent:8ed8e41c4771ca4f",
name: "Max",
server_id:"heim.4",
server_era:"00g5fg7f12ww0",
session_id:"8ed8e41c4771ca4f-00000210"
}
]
}
Use the log command to fetch the latest n messages from the room's chat.
Request: {id: "1", type: "log", data: {n: 50, before:"00c97lmxzgq9s"}}
Response:
{
id: "1",
type: "log-reply",
data: [
{
time: 1418585715,
id:"00gd7wc0qgjcw",
parent: "",
sender: {
id: "agent:8ed8e41c4771ca4f",
name: "Max",
server_id:"heim.4",
server_era:"00g5fg7f12ww0",
session_id:"8ed8e41c4771ca4f-00000210"
},
content: "hi!",
edited:null,
deleted:null
},
{
time: 1418585515,
id:"00gd7wc7m7z7k",
parent: "00gd7wc0qgjcw",
sender: {
id: "agent:8a55576975ce6e47",
name: "Logan",
server_id:"heim.3",
server_era:"00g5femcgk0lc",
session_id:"61ea7b275e1248f5-00000236"
},
content: "j0!",
edited:null,
deleted:null
}]
}
Use the send command to send a message to the room's chat.
Request:
{id: "1", type: "send", data: {content: "hello ezzie"}}
Response:
{
id: "1",
type: "send-reply",
data: {
time: 1418585715,
id:"00gd6yy9hvksg",
parent:""
sender: {
id: "agent:4da8fa7375215589",
name: "Ezzie",
server_id:"heim.1",
server_era:"00g5fdwjzl91c",
session_id:"4da8fa7375215589-00000246"},
content: "hello ezzie",
edited:null,
deleted:null
}
}
The response will also be broadcast to all other users in the room. For details, see send-event
These packets are sent by the server, sometimes in response to packets from other clients or packets from your client.
Ping events are used by the server to detect clients that have frozen or timed out. They can also be used by clients to detect connection or server failures.| Data Field | Type | Description |
|---|---|---|
| time | integer | GMT timestamp with second-level-precision of server time when this ping was generated |
| next | integer | GMT timestamp with second-level-precision of the next ping-event the server will send |
| Sample: |
{
type: "ping-event",
data: {
time:1428979816,
next:1428979846
}
}
A snapshot event is sent when a client first connects and acts as a combination log-reply and who-reply packet.
| Field | Type | Description |
|---|---|---|
| identity | string | Your clients unique id. This is the same value as id in user. |
| session_id | string | Same data as session_id in user. |
| version | string | Git hash of the current server build. |
| listing | list of user | Current users in this room. |
| log | list of message | Up to 50 messages of backlog. Equivalent to calling log. |
| Sample: |
{
type: "snapshot-event",
data: {
identity:"agent:4da8fa7375215589",
session_id:"4da8fa7375215589-00000246",
version:"801ea89a4e410b11410eb61c91971439904e66c0",
listing: [
{
id: "agent:61ea7b275e1248f5",
name: "Logan",
server_id:"heim.3",
server_era:"00g5femcgk0lc",
session_id:"61ea7b275e1248f5-00000236"
},
{
id: "agent:8ed8e41c4771ca4f",
name: "Max",
server_id:"heim.4",
server_era:"00g5fg7f12ww0",
session_id:"8ed8e41c4771ca4f-00000210"
}],
log:[
{
time: 1418585715,
id:"00gd7wc0qgjcw",
parent: "",
sender: {
id: "agent:8ed8e41c4771ca4f",
name: "Max",
server_id:"heim.4",
server_era:"00g5fg7f12ww0",
session_id:"8ed8e41c4771ca4f-00000210"
},
content: "hi!",
edited:null,
deleted:null
},
{
time: 1418585515,
id:"00gd7wc7m7z7k",
parent: "00gd7wc0qgjcw",
sender: {
id: "agent:8a55576975ce6e47",
name: "Logan",
server_id:"heim.3",
server_era:"00g5femcgk0lc",
session_id:"61ea7b275e1248f5-00000236"
},
content: "j0!",
edited:null,
deleted:null
}]
}
}
For each message sent by a client, Heim will send a send-event packet to the other clients. The sending client will receive a send-reply
{
type: "send-event",
data: {
time: 1418585715,
id:"00gd6yy9hvksg",
parent:""
sender: {
id: "agent:4da8fa7375215589",
name: "Ezzie",
server_id:"heim.1",
server_era:"00g5fdwjzl91c",
session_id:"4da8fa7375215589-00000246"},
content: "hello ezzie",
edited:null,
deleted:null
}
}
Heim sends a nick-event to all clients in the same room as a user who changes their name. The sending client will receive a nick-reply
{
type: "nick-event",
data: {
id: "agent:61ea7b275e1248f5",
to: "Ezzie",
from: "Logan",
server_id:"heim.3",
server_era:"00g5femcgk0lc",
session_id:"373f7e9af9f00b71-00000236"}
}