| OLD | NEW |
| 1 # Dart VM Service Protocol 1.0 (Draft 1) | 1 # Dart VM Service Protocol 1.0 (Draft 1) |
| 2 | 2 |
| 3 > Please post feedback to the [observatory-discuss group][discuss-list] | 3 > Please post feedback to the [observatory-discuss group][discuss-list] |
| 4 | 4 |
| 5 This document describes _draft 1_ of _version 1.0_ of the Dart VM | 5 This document describes _draft 1_ of _version 1.0_ of the Dart VM |
| 6 Service Protocol. This protocol is used to communicate with a running | 6 Service Protocol. This protocol is used to communicate with a running |
| 7 Dart Virtual Machine. | 7 Dart Virtual Machine. |
| 8 | 8 |
| 9 To use the Service Protocol, start the VM with the *--observe* flag. | 9 To use the Service Protocol, start the VM with the *--observe* flag. |
| 10 The VM will start a webserver which services protocol requests via WebSocket. | 10 The VM will start a webserver which services protocol requests via WebSocket. |
| 11 It is possible to make HTTP (non-WebSocket) requests, | 11 It is possible to make HTTP (non-WebSocket) requests, |
| 12 but this does not allow access to VM _events_ and is not documented | 12 but this does not allow access to VM _events_ and is not documented |
| 13 here. | 13 here. |
| 14 | 14 |
| 15 The Service Protocol is based on JSON-RPC 2.0 | 15 The Service Protocol uses [JSON-RPC 2.0][]. |
| 16 (http://www.jsonrpc.org/specification). The Service Protocol has been | 16 |
| 17 extended to support pushing _events_ to the client, which is | 17 [JSON-RPC 2.0]: http://www.jsonrpc.org/specification |
| 18 apparently outside the scope of the JSON-RPC specification. | |
| 19 | 18 |
| 20 **Table of Contents** | 19 **Table of Contents** |
| 21 | 20 |
| 22 - [RPCs, Requests, and Responses](#rpcs-requests-and-responses) | 21 - [RPCs, Requests, and Responses](#rpcs-requests-and-responses) |
| 23 - [Events](#events) | 22 - [Events](#events) |
| 24 - [Types](#types) | 23 - [Types](#types) |
| 25 - [IDs and Names](#ids-and-names) | 24 - [IDs and Names](#ids-and-names) |
| 26 - [Versioning](#versioning) | 25 - [Versioning](#versioning) |
| 27 - [Private RPCs, Types, and Properties](#private-rpcs-types-and-properties) | 26 - [Private RPCs, Types, and Properties](#private-rpcs-types-and-properties) |
| 28 - [Public RPCs](#public-rpcs) | 27 - [Public RPCs](#public-rpcs) |
| (...skipping 153 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 182 | 181 |
| 183 By using the [streamListen](#streamlisten) and [streamCancel](#streamcancel) RPC
s, a client may | 182 By using the [streamListen](#streamlisten) and [streamCancel](#streamcancel) RPC
s, a client may |
| 184 request to be notified when an _event_ is posted to a specific | 183 request to be notified when an _event_ is posted to a specific |
| 185 _stream_ in the VM. Every stream has an associated _stream id_ which | 184 _stream_ in the VM. Every stream has an associated _stream id_ which |
| 186 is used to name that stream. | 185 is used to name that stream. |
| 187 | 186 |
| 188 Each stream provides access to certain kinds of events. For example the _Isolate
_ stream provides | 187 Each stream provides access to certain kinds of events. For example the _Isolate
_ stream provides |
| 189 access to events pertaining to isolate births, deaths, and name changes. See [st
reamListen](#streamlisten) | 188 access to events pertaining to isolate births, deaths, and name changes. See [st
reamListen](#streamlisten) |
| 190 for a list of the well-known stream ids and their associated events. | 189 for a list of the well-known stream ids and their associated events. |
| 191 | 190 |
| 192 Events arrive asynchronously over the WebSocket and always have the | 191 Stream events arrive asynchronously over the WebSocket. They're structured as |
| 193 _streamId_ and _event_ properties: | 192 JSON-RPC 2.0 requests with no _id_ property. The _method_ property will be |
| 193 _streamNotify_, and the _params_ will have _streamId_ and _event_ properties: |
| 194 | 194 |
| 195 ``` | 195 ```json |
| 196 { | 196 { |
| 197 "event": { | 197 "json-rpc": "2.0", |
| 198 "type": "Event", | 198 "method": "streamNotify", |
| 199 "kind": "IsolateExit", | 199 "params": { |
| 200 "isolate": { | 200 "streamId": "Isolate", |
| 201 "type": "@Isolate", | 201 "event": { |
| 202 "id": "isolates/33", | 202 "type": "Event", |
| 203 "number": "51048743613", | 203 "kind": "IsolateExit", |
| 204 "name": "worker-isolate" | 204 "isolate": { |
| 205 "type": "@Isolate", |
| 206 "id": "isolates/33", |
| 207 "number": "51048743613", |
| 208 "name": "worker-isolate" |
| 209 } |
| 205 } | 210 } |
| 206 } | 211 } |
| 207 "streamId": "Isolate" | |
| 208 } | 212 } |
| 209 ``` | 213 ``` |
| 210 | 214 |
| 211 It is considered a _backwards compatible_ change to add a new type of event to a
n existing stream. | 215 It is considered a _backwards compatible_ change to add a new type of event to a
n existing stream. |
| 212 Clients should be written to handle this gracefully. | 216 Clients should be written to handle this gracefully. |
| 213 | 217 |
| 214 | 218 |
| 219 |
| 215 ## Types | 220 ## Types |
| 216 | 221 |
| 217 By convention, every result and event provided by the Service Protocol | 222 By convention, every result and event provided by the Service Protocol |
| 218 is a subtype of [Response](#response) and has the _type_ property. | 223 is a subtype of [Response](#response) and has the _type_ property. |
| 219 This allows the client to distinguish different kinds of responses. For example, | 224 This allows the client to distinguish different kinds of responses. For example, |
| 220 information about a Dart function is returned using the [Function](#function) ty
pe. | 225 information about a Dart function is returned using the [Function](#function) ty
pe. |
| 221 | 226 |
| 222 If the type of a response begins with the _@_ character, then that | 227 If the type of a response begins with the _@_ character, then that |
| 223 response is a _reference_. If the type name of a response does not | 228 response is a _reference_. If the type name of a response does not |
| 224 begin with the _@_ character, it is the an _object_. A reference is | 229 begin with the _@_ character, it is the an _object_. A reference is |
| (...skipping 1762 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1987 ``` | 1992 ``` |
| 1988 | 1993 |
| 1989 ## Revision History | 1994 ## Revision History |
| 1990 | 1995 |
| 1991 version | comments | 1996 version | comments |
| 1992 ------- | -------- | 1997 ------- | -------- |
| 1993 1.0 draft 1 | initial revision | 1998 1.0 draft 1 | initial revision |
| 1994 | 1999 |
| 1995 | 2000 |
| 1996 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observato
ry-discuss | 2001 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observato
ry-discuss |
| OLD | NEW |