565 lines
9.0 KiB
Markdown
565 lines
9.0 KiB
Markdown
Websocket API
|
|
---
|
|
[JSON RPC 2.0](http://www.jsonrpc.org/specification) protocol is used for client-server
|
|
communication, but:
|
|
- `params` is always json object(never array)
|
|
- server to client notifications are treated as [Events](events.md)
|
|
|
|
the apis described below include some of the following fields:
|
|
```json
|
|
{
|
|
"jsonrpc" : "2.0",
|
|
"method": "...",
|
|
"id": "...",
|
|
"params": { },
|
|
"error" : { },
|
|
"result" : { }
|
|
}
|
|
```
|
|
these fields are part of the protocol so they are not documented.
|
|
|
|
## Process API
|
|
|
|
|
|
### Start process
|
|
|
|
##### Request
|
|
|
|
- __name__ - the name of the command
|
|
- __commandLine__ - command line to execute
|
|
- __type__(optional) - command type
|
|
- __eventTypes__(optional) - comma separated types of events which will be
|
|
received by this channel. By default all the process events will be received.
|
|
Possible values are: `stderr`, `stdout`, `process_status`
|
|
|
|
```json
|
|
{
|
|
"method": "process.start",
|
|
"id": "id1234567",
|
|
"params": {
|
|
"name": "print",
|
|
"commandLine": "printf \"1\n2\n3\"",
|
|
"type": "test"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "id1234567",
|
|
"result": {
|
|
"pid": 1,
|
|
"name": "print",
|
|
"commandLine": "printf \"1\n2\n3\"",
|
|
"type": "test",
|
|
"alive": true,
|
|
"nativePid": 19920
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Errors
|
|
|
|
- when either `name` or `commandLine` is missing, e.g:
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "id1234567",
|
|
"error": {
|
|
"code": -32602,
|
|
"message": "Command line required"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Kill process
|
|
|
|
##### Request
|
|
|
|
- __pid__ - the id of the process to kill
|
|
|
|
```json
|
|
{
|
|
"method": "process.kill",
|
|
"id": "id1234567",
|
|
"params": {
|
|
"pid": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "id1234567",
|
|
"result": {
|
|
"pid": 2,
|
|
"text": "Successfully killed"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Errors
|
|
|
|
- when there is no such process
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "id1234567",
|
|
"error": {
|
|
"code": -32000,
|
|
"message": "Process with id '2' does not exist"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when process with given id is not alive
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "id1234567",
|
|
"error": {
|
|
"code": -32001,
|
|
"message": "Process with id '2' is not alive"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Subscribe to process events
|
|
|
|
##### Request
|
|
|
|
- __pid__ - the id of the process to subscribe to
|
|
- __eventTypes__(optional) - comma separated types of events which will be
|
|
received by this channel. By default all the process events will be received,
|
|
not supported even types are ignored. Possible values are: `stdout`, `stderr`, `process_status`.
|
|
- __after__(optional) - process logs which appeared after given time will
|
|
be republished to the channel. This parameter may be useful when reconnecting to the exec-agent
|
|
|
|
```json
|
|
{
|
|
"method": "process.subscribe",
|
|
"id": "0x12345",
|
|
"params": {
|
|
"pid": 2,
|
|
"eventTypes": "stdout,stderr",
|
|
"after" : "2016-07-26T09:36:44.920890113+03:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
##### Response
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"result": {
|
|
"pid": 2,
|
|
"eventTypes": "stdout,stderr",
|
|
"text": "Successfully subscribed"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Errors
|
|
|
|
- when there is no a single valid event type provided
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32602,
|
|
"message": "Required at least 1 valid event type"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when `after` is not in valid format
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32602,
|
|
"message": "Bad format of 'after', parsing time \"2016-07-26\" as \"2006-01-02T15:04:05.999999999Z07:00\": cannot parse \"\" as \"T\""
|
|
}
|
|
}
|
|
```
|
|
|
|
- when this channel is already subscribed on process events
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32603,
|
|
"message": "Already subscribed"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when there is no such process
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32000,
|
|
"message": "Process with id '2' does not exist"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when process with given id is not alive
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32001,
|
|
"message": "Process with id '2' is not alive"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
|
|
### Unsubscribe from process events
|
|
|
|
##### Request
|
|
|
|
- __pid__ - the id of the process to unsubscribe from
|
|
|
|
```json
|
|
{
|
|
"method": "process.unsubscribe",
|
|
"id": "0x12345",
|
|
"params": {
|
|
"pid": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"result": {
|
|
"pid": 2,
|
|
"text": "Successfully unsubscribed"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Errors
|
|
|
|
- when there is no such process
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32000,
|
|
"message": "Process with id '2' does not exist"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when process with given id is not alive
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32001,
|
|
"message": "Process with id '2' is not alive"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
|
|
### Update process subscriber
|
|
|
|
##### Request
|
|
|
|
- __pid__ - the id of the process which subscriber should be updated
|
|
- __eventTypes__ - comma separated types of events which will be
|
|
received by this channel. Not supported even types are ignored.
|
|
Possible values are: `stdout`, `stderr`, `process_status`.
|
|
|
|
```json
|
|
{
|
|
"method": "process.updateSubscriber",
|
|
"id": "0x12345",
|
|
"params": {
|
|
"pid": 2,
|
|
"eventTypes": "process_status"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"result": {
|
|
"pid": 2,
|
|
"eventTypes": "process_status",
|
|
"text": "Subscriber successfully updated"
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Errors
|
|
|
|
- when there is no such process
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32000,
|
|
"message": "Process with id '2' does not exist"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when process with given id is not alive
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32001,
|
|
"message": "Process with id '2' is not alive"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when this channel is not subscribed on process events
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32603,
|
|
"message": "No subscriber with id 'channel-1'"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
### Get process logs
|
|
|
|
##### Request
|
|
|
|
- __pid__ - the id of the process to get logs
|
|
- __from__(optional) - time to get logs from e.g. _2016-07-12T01:48:04.097980475+03:00_ the format is _RFC3339Nano_
|
|
- __till__(optional) - time to get logs till e.g. _2016-07-12T01:49:04.097980475+03:00_ the format is _RFC3339Nano_
|
|
- __limit__(optional) - the limit of logs in result, the default value is _50_, logs are limited from the
|
|
latest to the earliest
|
|
- __skip__ (optional) - the logs to skip, default value is `0`
|
|
|
|
```json
|
|
{
|
|
"method": "process.getLogs",
|
|
"id": "0x12345",
|
|
"params": {
|
|
"pid": 3,
|
|
"limit": 5,
|
|
"skip": 5
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
For the command `printf "1\n2\n3\n4\n5\n6\n7\n8\n9\n10`, the result will look like
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"result": [
|
|
{
|
|
"kind": "STDOUT",
|
|
"time": "2016-09-24T17:18:30.757623274+03:00",
|
|
"text": "1"
|
|
},
|
|
{
|
|
"kind": "STDOUT",
|
|
"time": "2016-09-24T17:18:30.757701555+03:00",
|
|
"text": "2"
|
|
},
|
|
{
|
|
"kind": "STDOUT",
|
|
"time": "2016-09-24T17:18:30.757721423+03:00",
|
|
"text": "3"
|
|
},
|
|
{
|
|
"kind": "STDOUT",
|
|
"time": "2016-09-24T17:18:30.757841518+03:00",
|
|
"text": "4"
|
|
},
|
|
{
|
|
"kind": "STDOUT",
|
|
"time": "2016-09-24T17:18:30.757851622+03:00",
|
|
"text": "5"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
##### Errors
|
|
|
|
|
|
- when there is no such process
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32000,
|
|
"message": "Process with id '2' does not exist"
|
|
}
|
|
}
|
|
```
|
|
|
|
- when one of the time parameters is invalid, e.g:
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32602,
|
|
"message": "Bad format of 'till', parsing time \"date\" as \"2006-01-02T15:04:05.999999999Z07:00\": cannot parse \"date\" as \"2006\""
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
|
|
### Get process
|
|
|
|
##### Request
|
|
|
|
- __pid__ - the id of the process to get
|
|
|
|
```json
|
|
{
|
|
"method": "process.getProcess",
|
|
"id": "0x12345",
|
|
"params": {
|
|
"pid": 3
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
When everything is okay
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"result": {
|
|
"pid": 1,
|
|
"name": "print",
|
|
"commandLine": "printf \n1\n2\n3\"",
|
|
"type": "test",
|
|
"alive": false,
|
|
"nativePid": 13158
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Errors
|
|
|
|
|
|
- when there is no such process
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "0x12345",
|
|
"error": {
|
|
"code": -32000,
|
|
"message": "Process with id '2' does not exist"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
### Get processes
|
|
|
|
##### Request
|
|
|
|
- __all__(optional) - if `true` then all the processes including _dead_ ones will be returned,
|
|
otherwise only _alive_ processes will be returned
|
|
|
|
```json
|
|
{
|
|
"method": "process.getProcesses",
|
|
"id": "id1234567",
|
|
"params": {
|
|
"all": true
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Response
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": "id1234567",
|
|
"result": [
|
|
{
|
|
"pid": 1,
|
|
"name": "print",
|
|
"commandLine": "printf \"1\n2\n3\"",
|
|
"type": "test",
|
|
"alive": false,
|
|
"nativePid": 13553
|
|
},
|
|
{
|
|
"pid": 2,
|
|
"name": "print2",
|
|
"commandLine": "printf \"\n3\n2\n1\"",
|
|
"type": "test2",
|
|
"alive": false,
|
|
"nativePid": 13561
|
|
}
|
|
]
|
|
}
|
|
```
|