gutenberg / lib / experimental / sync / README.md

README.md in Gutenberg 22.3.0, at lib/experimental/sync/README.md

184 lines 6.3 KB

Raw Download Zip

1	# Signaling Server Documentation
2
3	The signaling server allows multiple clients to exchange messages with each other through various communication topics.
4
5	Topics are not defined upfront, but clients define them by subscribing to them. By subscribing to a given topic, the client tells the server to keep track of its unread messages in the given topic. By unsubscribing from a topic, the client tells the server to free the bookkeeping it maintains for the given client and topic.
6
7	Every client communicates with the server via `GET` or `POST`. Clients must have a unique identifier, which can be randomly generated. This identifier should be included as a parameter named `subscriber_id` in every request.
8
9	Available operations:
10
11	- Subscribe to topics
12	- Unsubscribe from topics
13	- Publish a message
14	- Read pending messages
15	- Ping the server
16
17	## Subscribe to topics
18
19	To subscribe to a set of topics, a client must send a `POST` request with the following parameters:
20
21	- `subscriber_id`: Subscriber ID of the client.
22	- `action`: should be set to `gutenberg_signaling_server`.
23	- `message`:
24	- `type`: should be set to `subscribe`.
25	- `topics`: array of topics that the client is interested in reading messages from, e.g., `[ 'WordPress', 'Drupal' ]`.
26
27	If the action is executed successfully by the server, the server will respond with `{"result":"ok"}`.
28
29	### Sample request
30
31	```js
32	await (
33	await fetch( window.wp.ajax.settings.url, {
34	body: new URLSearchParams( {
35	subscriber_id: '1',
36	action: 'gutenberg_signaling_server',
37	message: JSON.stringify( {
38	type: 'subscribe',
39	topics: [ 'WordPress', 'Drupal' ],
40	} ),
41	} ),
42	method: 'POST',
43	} )
44	).text();
45	```
46
47	## Unsubscribe from topics
48
49	To unsubscribe from a set of topics, a client must send a `POST` request with the following parameters:
50
51	- `subscriber_id`: subscriber ID of the client.
52	- `action`: should be set to `gutenberg_signaling_server`.
53	- `message`:
54	- `type`: should be set as `unsubscribe`.
55	- `topics`: an array of topics that the client is no longer interested in reading messages from, e.g., `['WordPress', 'Drupal']`.
56
57	If the action is executed successfully by the server, the server will respond with `{"result":"ok"}`.
58
59	### Sample request
60
61	```js
62	await (
63	await fetch( window.wp.ajax.settings.url, {
64	body: new URLSearchParams( {
65	subscriber_id: '1',
66	action: 'gutenberg_signaling_server',
67	message: JSON.stringify( {
68	type: 'unsubscribe',
69	topics: [ 'WordPress', 'Drupal' ],
70	} ),
71	} ),
72	method: 'POST',
73	} )
74	).text();
75	```
76
77	## Publish a message
78
79	To publish a message in a specific topic, a client must send a `POST` request with the following parameters:
80
81	- `subscriber_id`: subscriber ID of the client.
82	- `action`: should be set to `gutenberg_signaling_server`.
83	- `message`:
84	- `type`: should be set as `publish`.
85	- `topic`: the topic where the message should be published, e.g., `WordPress`.
86	- `data`: The data to be broadcasted to every client that subscribed to the topic. The data can be any string and may be encrypted to prevent the server from reading the messages.
87
88	If the action is executed successfully by the server, the server will respond with `{"result":"ok"}`.
89
90	### Sample request
91
92	```js
93	await (
94	await fetch( window.wp.ajax.settings.url, {
95	body: new URLSearchParams( {
96	subscriber_id: '1',
97	action: 'gutenberg_signaling_server',
98	message: JSON.stringify( {
99	type: 'publish',
100	topic: 'WordPress',
101	data: 'hello I am client 1!',
102	} ),
103	} ),
104	method: 'POST',
105	} )
106	).text();
107	```
108
109	## Read pending messages
110
111	To read pending messages, the client should send a `GET` request with the following parameters:
112
113	- `subscriber_id`: Subscriber ID of the client.
114	- `action`: should be set to `gutenberg_signaling_server`.
115
116	The server will respond using the [](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_formatEvent stream format](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format), whose content type is set to `text/event-stream;charset=UTF-8`. The Event stream format defines the following fields:
117
118	- `retry`: the reconnection time, in ms. The time after which the client should check again for messages.
119	- `id`: unique identifier for the server response.
120	- `event`: one of `message` or `error`.
121	- `data`:
122	- If `event` is `message`, data is a JSON encoded string containing an array of messages that the given client has not read yet. Each message is similar to the published message object but includes an additional property named `clients`. This property specifies the number of clients for which the message was sent. Note it does not indicate whether they have already received/requested it.
123	- If `event` is `error`, data is a description of the error.
124
125	If there are no pending messages, the server's response only contains the `retry:` field. If there are pending messages, the server will respond including all the fields.
126
127	### Sample request
128
129	```js
130	await (
131	await fetch(
132	window.wp.url.addQueryArgs( window.wp.ajax.settings.url, {
133	subscriber_id: '1',
134	action: 'gutenberg_signaling_server',
135	} )
136	)
137	).text();
138	```
139
140	Sample answer from the server when there are no unread messages:
141
142	```
143	retry: 3000
144	```
145
146	Sample answer from the server when there are unread messages:
147
148	```
149	retry: 3000
150	id: 1694809781
151	event: message
152	data: [{"type":"publish","topic":"WordPress","data":"hello I am client 1!","clients":2},{"type":"publish","topic":"WordPress","data":"Hi client 1 I am client 2","clients":2}]
153	```
154
155	## Ping the server
156
157	To ensure that the server is listening and to indicate that a client is still alive, the client can periodically send a ping to the server. When the server receives a ping from a client, it will respond with a message containing `pong`. The client will receive this `pong` message when it asks the server for new messages.
158
159	To send a ping, the client should send a `POST` request with the following parameters:
160
161	- `subscriber_id`: Subscriber ID of the client.
162	- `action`: should be set to `gutenberg_signaling_server`.
163	- `message`:
164	- `type`: Should be set as `ping`.
165
166	If the action is executed successfully by the server, the server will respond with `{"result":"ok"}`.
167
168	#### Sample request
169
170	```js
171	await (
172	await fetch( window.wp.ajax.settings.url, {
173	body: new URLSearchParams( {
174	subscriber_id: '1',
175	action: 'gutenberg_signaling_server',
176	message: JSON.stringify( {
177	type: 'ping',
178	} ),
179	} ),
180	method: 'POST',
181	} )
182	).text();
183	```
184