Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(538)

Side by Side Diff: runtime/vm/service/service.md

Issue 1257943003: Support JSON-RPC 2.0-compatible VM service events. (Closed) Base URL: git@github.com:dart-lang/sdk.git@master
Patch Set: cr Created 5 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « runtime/vm/service.cc ('k') | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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
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
OLDNEW
« no previous file with comments | « runtime/vm/service.cc ('k') | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698