SReject/IRE Example.md

Invoke, Response, Event

The goal of the Invoke, Response, Event protocol is to provide a generic meaningful format for communications while providing mechanisms related to querying resources and transmiting 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 or rely upon any property not defined in this 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, or allowed to passed through.

Invoke

Invoke messages are used to query or update a remote resource. These messages must always result in a Response from the recipient.

Invoke messages 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`	`"invoke"`	no	Literal text `invoke`
`id`*	`number` \| `string`	no	A sender-generated ID
`name`	`string`	no	The resource identifier to query
`data`**	`Array<any>`	no	A list of values(arguments) to pass to the resource handler

*: The id must be unique to other pending innvocations 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 Invoke message, the recipiant should process the innvocation and respond with a response-message. Responses may be transmitted in any order regardless of order in which the originating requests were received.

Invoke messages that result in a state change that would generate an event should generate the Event as well as the Response

Success

Property	Type	Nullable	Description
`type`	`"response"`	no	Literal text `response`
`id`	`number` \| `string`	no	The `id` property received with the invoke-message
`name`	`"success"`	no	Literal text `success`
`data`	any	yes	Resulting value from processing the query

Error

Property	Type	Nullable	Description
`type`	`"response"`	no	Literal text `response`
`id`	`number` \| `string`	no	The `id` property received with the invoke-message
`name`	`"error"`	no	Literal text `error`
`data`	any	yes	Error information detailing why the invocation 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`	`"event"`	no	Literal text `event`
`id`*	`string`	yes	Ignored
`name`	`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 heavily inspired by jsonrpc with a focus on the format and ignoring implementation.

Example Communications

Client sends a 'authorize' invocation to server:
{
    "type": "invoke",
    "id":   "authMe",
    "name": "authorize",
    "data": ["guest"]
}

[Server begins processing the authorize innvocation]

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

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

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

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

Client resends 'add' invocation:
{
    "type": "invoke",
    "id":   "add2and3again",
    "name": "add",
    "data": [2, 3]
}

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