Skip to content

Commit 4dc8555

Browse files
renancaraujorenancaraujo
authored
docs: add daemon docs (#837)
1 parent ef6dc7b commit 4dc8555

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

‎docs/docs/advanced/daemon.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
import TOCInline from '@theme/TOCInline';
2+
3+
# 🧰 Daemon
4+
5+
Dart Frog daemon is a standing process that, during its lifetime, will be used by first and
6+
third-party tools to manage, build, and diagnose Dart Frog projects.
7+
8+
By design, the daemon is able to manage multiple projects simultaneously; it can also run multiple
9+
application instances of the same project if necessary.
10+
11+
To start using it, install the Dart Frog CLI and run the `dart_frog daemon` command. Once running, communicating with it can be done via [JSON-RPC](https://www.jsonrpc.org/) over stdin/stdout to receive and send messages.
12+
13+
There are three types of messages:
14+
15+
- **Request**: A request is a message sent by a client to the daemon. The daemon will process the
16+
request and send a response back to the client. A request is essentially a method invocation.
17+
- **Response**: A response is a message sent by the daemon to a client in response to a request.
18+
- **Event**: An event is a message sent by the daemon to a client. The daemon will send an event to
19+
a client when something happens, for example, when a running dev server stops.
20+
21+
Every request should be met with a response as soon as possible so the caller can work with
22+
timeouts. The daemon will send events to the client as they happen.
23+
24+
---
25+
26+
#### Usage example
27+
28+
```json
29+
$ dart_frog daemon
30+
31+
// ready event sent via stdout
32+
[{"event":"daemon.ready","params":{"version":"0.0.1","processId":75941}}]
33+
34+
// request inserted via stdin
35+
[{"method": "daemon.requestVersion", "id": "12"}]
36+
37+
// response sent via stdout
38+
[{"id":"12","result":{"version":"0.0.1"}}]
39+
40+
```
41+
42+
The `id` field on the request is used to match the request with the response. As the client sets it arbitrarily, the client is responsible for ensuring that all request ids are unique.
43+
44+
---
45+
46+
To organize the accepted requests and its parameters as well as events, there are "domains." A
47+
domain is a group of related requests and events.
48+
49+
The domains are:
50+
51+
<TOCInline toc={toc} />
52+
53+
## `daemon` domain
54+
55+
The `daemon` domain is used to manage the daemon itself.
56+
57+
### Method: `requestVersion`
58+
59+
Request the daemon version.
60+
61+
- **Response**:
62+
63+
| Field | type | Description |
64+
| ------- | ------ | ------------------ |
65+
| version | string | The daemon version |
66+
67+
### Method: `kill`
68+
69+
Shuts down the daemon
70+
71+
- **Response**:
72+
73+
| Field | type | Description |
74+
| ------- | ------ | ----------------- |
75+
| message | string | A goodbye message |
76+
77+
### Event: `ready`
78+
79+
Signals that a daemon is ready right after startup
80+
81+
- **Content**:
82+
83+
| Field | type | Description |
84+
| --------- | ------ | --------------------------------------------- |
85+
| version | string | The daemon version |
86+
| processId | int | The process id in which the daemon is running |
87+
88+
## `dev_server` domain
89+
90+
Operations related to running/managing Dart Frog dev servers locally.
91+
92+
### Method: `start`
93+
94+
Start a dev server on a given project.
95+
96+
- **Parameters**:
97+
98+
| Field | Type | Description | Required |
99+
| ----------------- | ------ | -------------------------------------- | -------- |
100+
| workingDirectory | String | The project directory | Yes |
101+
| port | int | The port to run the dev server on | Yes |
102+
| dartVmServicePort | int | The port to run the Dart VM Service on | Yes |
103+
104+
- **Response**:
105+
106+
| Field | Type | Description |
107+
| ------------- | ------ | ---------------------------------------------- |
108+
| applicationId | String | A unique identifier for the devserver instance |
109+
110+
### Method: `reload`
111+
112+
Reload a running dev server.
113+
114+
- **Parameters**:
115+
116+
| Field | Type | Description | Required |
117+
| ------------- | ------ | ------------------------ | -------- |
118+
| applicationId | String | The devserver identifier | Yes |
119+
120+
- **Response**:
121+
122+
| Field | Type | Description |
123+
| ------------- | ------ | ---------------------------------------------- |
124+
| applicationId | String | A unique identifier for the devserver instance |
125+
126+
### Method: `stop`
127+
128+
Stop a running dev server.
129+
130+
- **Parameters**:
131+
132+
| Field | Type | Description | Required |
133+
| ------------- | ------ | ------------------------ | -------- |
134+
| applicationId | String | The devserver identifier | Yes |
135+
136+
- **Response**:
137+
138+
| Field | Type | Description |
139+
| ------------- | ------ | ---------------------------------------------- |
140+
| applicationId | String | A unique identifier for the devserver instance |
141+
| exitCode | int | The exit code of the devserver process |
142+
143+
### Event: `applicationStarting`
144+
145+
Signals that a dev server is starting.
146+
147+
- **Content**:
148+
149+
| Field | Type | Description |
150+
| ------------- | ------ | -------------------------------------------------------------- |
151+
| applicationId | String | A unique identifier for the devserver instance |
152+
| requestId | String | A unique identifier for the request that started the devserver |
153+
154+
### Event: `applicationExit`
155+
156+
Signals that a dev server has exited.
157+
158+
- **Content**:
159+
160+
| Field | Type | Description |
161+
| ------------- | ------ | --------------------------------------------------------------- |
162+
| applicationId | String | A unique identifier for the dev server instance |
163+
| requestId | String | A unique identifier for the request that started the dev server |
164+
| exitCode | int | The exit code of the dev server process |

0 commit comments

Comments
 (0)