SReject/IRE Example.md

Request, Response, Event

The goal of the Request, Response, Event protocol is to provide a generic meaningful format for communications while providing mechanisms related to querying resources and state change notifications.

Message Formats

Messages are transmitted as valid JSON-parsable strings and must conform to one of the message-formats given below.

All format-defined properties are required to be part of the resulting JSON string. If a defined property does not have an applicable value, it's value should default to null.

Implementations should NOT define/rely upon any property not defined in a format. Any non format-defined properties in the message's JSON string are to be ignored by the recipient.

Messages that are non-conformant may be treated as invalid, discarded/ignored, or allowed to passed through.

Request

Request-messages are used to query a remote resource. These messages must always result in a Response from the recipient.

Requests may be processed in any order regardless of the order in which they were received; this is to allow for parallel and asynchronous processing of messages.

Property	Type	Nullable	Description
`type`	`String="request"`	no	Literal text `request`
`id`*	`String`	no	A sender-generated ID
`meta`	`String`	no	The resource identifier to query
`data`**	`Array<any>`	no	A list of values(arguments) to pass to the resource handler

*: The id should be unique to the connection session but may be reused once a response has been received.
**: If no values are to be provided to the resource data should be an empty array.

Response

Upon receiving a Request, the recipiant should process the request and respond with a response-message. Responses may be transmitted in any order regardless of order in which the originating requests were received.

Success

Property	Type	Nullable	Description
`type`	`String="response"`	no	Literal text `response`
`id`	`String`	no	The `id` property received with the request-message
`meta`	`String="ok"`	no	Literal text `ok`
`data`	any	yes	Resulting value from processing the query

Error

Property	Type	Nullable	Description
`type`	`String="response"`	no	Literal text `response`
`id`	`String`	no	The `id` property received with the request-message
`meta`	`String="error"`	no	Literal text `error`
`data`	`String`	yes	Error message detailing why the query failed

Event

An event-message is used to notify the recipient of a state change. Event-messages infer the sender does not care about the actions taken by recipient as a result of receiving the message.

Property	Type	Nullable	Description
`type`	`String="event"`	no	Literal text `event`
`id`*	`String`	no	Ignored
`meta`	`String`	no	Event name/Notification identifier
`data`	any	yes	The data accompanying the event

*: To keep the formats consistent, the id parameter must be specified but its value is ignored by the recipient.

Notes

This is based heavily on jsonrpc with the caveat of keeping a strict structure to all messages

Example Communications

Client sends a 'authorize' request to server:
{
    "type": "request",
    "id":   "authMe",
    "meta": "authorize",
    "data": ["guest"]
}

[Server begins processing the authorize request]

Client sends an 'add' request before server finishes processing the authorize request:
{
    "type": "request",
    "id":   "add2and3",
    "meta": "add",
    "data": [2, 3]
}

Server Responds to 'add' request (authorize request still pending):
{
    "type": "response",
    "id":   "add2and3",
    "meta": "error",
    "data": "not authorized"
}

Server finishes authorizing user:
{
    "type": "response",
    "id":   "authMe",
    "meta": "ok",
    "data": null
}

Server broadcasts a message to all clients:
{
    "type": "event",
    "id":   "",
    "meta": "userConnect",
    "data": {"type": "guest"}
}

Client resends 'add' request:
{
    "type": "request",
    "id":   "add2and3again",
    "meta": "add",
    "data": [2, 3]
}

Server processes the 'add' request and responds:
{
    "type": "response",
    "id":   "add2and3again",
    "meta": "ok",
    "data": 5
}