client-runtime.md 4.59 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
# The Web Client Runtime

## Introduction
The web-based user interfaces of iTasks are generated by applications, not directly as html, css and javascript, but as abstract user interface descriptions. These interface descriptions are interpreted by a generic run-time system, written in javascript that runs in a web browser and manages one or multiple iTasks 'viewports' in a web page. iTask applications don't have to use the full browser window, they can be just as easily embedded as part of another web-page.

## The basic idea 
TODO

## The connection pool
TODO

## The Task-UI Protocol 
Steffen Michels's avatar
typos  
Steffen Michels committed
13
In the current web run-time, websockets are used to communicate between web-browsers and iTask applications. Over these sockets a custom protocol is implemented that lets browsers create and attach to task instances.
14

Steffen Michels's avatar
typos  
Steffen Michels committed
15
The protocol mixes two communication styles. To control the connection, there are a number of RPC-like commands. These are initiated by the client framework and the server responds with an acknowledgement or a response. Once the connection is set up, the server also pushes messages to the client framework.
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
These are used to synchronize the UI and to notify clients of server-side exceptions

### Commands
All commands are send as a triplet encoded in a JSON array. The first part is a unique command identifier (> 0). This is followed by the command name. The last part is a JSON object with parameters.
For example:
```
[42,"new",{}]
```
The server responds with a similar triplet. The first two parts match the command. The last part contains potential response data.
For example:
```
[42,"new",{instanceNo: 23423, instanceKey: 'asdfasdfasuasdfasdf'}]
```
If a command fails for some reason, the server responds with a message that has the same command identifier but has the string ```"exception"``` as second part, followed by an object with a description of the exception.
For example:
```
[42,"exception",{description: "Failed to create task instance"}]
```

The following commands are possible:
| Command    | Description                              | Parameters                               | Example                                  | Response attributes         |
| ---------- | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | --------------------------- |
| `new`      | Create a new session task instance.      | none                                     | `[23,"new",{}]`                          | `instanceNo`, `instanceKey` |
| `attach`   | Link a task instance to the current connection. Each task instance can only be attached to one connection at a time. When a task instance is attached to a connection, that connection will accept events and receives UI changes. | `instanceNo`,`instanceKey`               | `[18,"attach",{instanceNo: 364}]`        | none                        |
| `detach`   | Unlink a task instance from this connection | `instanceNo`                             | `[58,"detach",{instanceNo: 628}]`        | none                        |
| `ui-event` | Send a UI event for one of the attached task instances. | `instanceNo` , `taskNo`, `action`, `edit`,`value` | `[58,"ui-event",{"instanceNo": 34, "taskNo": 5,"edit": "0-23-4-2","value": null}]` | none                        |
| `ping`     | Let the server know that the attached instances are still alive. If the client framework has no events and does not send a ping event at regular intervals, the server will remove session task instances | none                                     | `[67,"ping",{}]`                         | none                        |

### Notifications

Notifications have the same format as responses to commands. The only difference is that  the command identifier is always `0`. Because they are not responses to specific commands, there is no identifier.

The following notifications are possible:

| Notification | Description                              | Attributes                 | Example                                  |
| ------------ | ---------------------------------------- | -------------------------- | ---------------------------------------- |
| `ui-change`  | Update the UI of one of the attached task instances | `instanceNo`, `change`     | `[0,"ui-change",{"instanceNo": 395,change: []}]` |
| `exception`  | One of the task had an uncaught exception. | `instanceNo`,`description` | `[0,"exception",{"instanceNo":65,"description":"Could ot read file x"}]` |
| `detach`     | A task instance has been attached to another session, and is therefore detached from the current connection. | `instanceNo`               | `[0,"detach",{"instanceNo": 47}]`        |