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 |