Skip to content

Latest commit

 

History

History
167 lines (130 loc) · 5.71 KB

PROTOCOL.md

File metadata and controls

167 lines (130 loc) · 5.71 KB

Client/Server Communication

Version: 1

Client is defined as the GhostText browser extension.

Server is defined as the Editors' plugin or stand alone daemon.

Because this protocol uses WebSockets this document will outline a conversation between client and server as a series of user interactions.

User activates editing in the Client

The Client sends an HTTP GET / request to localhost to the configured port (default 4001).

GET / HTTP/1.1
Host: http://localhost:4001

The Server responds with a 200 and a content type of application/json.

The JSON payload is an object with the following properties:

Property Type Description
ProtocolVersion Number The protocol version
WebSocketPort Number The port for the listening WebSocket. This ideally is the same configured HTTP port (default 4001) but it doesn’t have to be.

Example

200 OK
Content-Type: application/json

{
  "ProtocolVersion": 1,
  "WebSocketPort": 12345
}

The Client will then establish a new WebSocket connection to ws://localhost:12345/ (replace the port number with the one provided in the previous step).

Once the WebSocket connection is established the Client sends the first message which is the same as a change message described below.

User makes a change in the browser

Each time the user makes a change in the browser (or on first WebSocket connect) the Client sends via the WebSocket a JSON object message with the following properties:

Property Value Description
title String The title of the document
url String The host of the document's url
syntax String Not used
text String The value of the textarea/content
selections Array(SelectionObject) An array of selection objects that describe the user's current cursor selections in the editor

Selection Object

Selection objects have the following properties:

Property Value Description
start Number 0-index start of the selection in UTF-16 code units
end Number 0-index end of the selection in UTF-16 code units

Example

{
	"title": "Test Document",
	"url": "http://example.com/test-document",
	"syntax": "",
	"text": "Adipisicing excepturi voluptate nostrum quas veritatis?",
	"selections": [
		{
			"start": 10,
			"end": 20
		}
	]
}

User makes a change in the editor

Each time the user makes a change in the editor the Server sends via the WebSocket a JSON object message with at least one of the following properties:

Property Value Description
text String The temporary file content
selections Array(SelectionObject) An array of selection objects that describe the user's current cursor selections in the editor

Example

{
	"text": "Adipisicing ea lorem expedita facere nesciunt",
	"selections": [
		{
			"start": 20,
			"end": 30
		}
	]
}
{
	"text": "Adipisicing ea lorem expedita facere nesciunt"
}
{
	"text": "Adipisicing ea lorem expedita facere nesciunt",
	"selections": [
		{
			"start": 20,
			"end": 30
		},
		{
			"start": 50,
			"end": 51
		}
	]
}

User quits the editor, closes the browser tab, or ends the GhostText session

Either the Server or the Client can just disconnect WebSocket at anytime. In cases where the user exits the editor it would be prudent for the Server to send one last change message before disconnecting to prevent possible data loss.

If the Client disconnects it is up to the Server to choose how to handle things (typically closing the temporary file or showing a notification to the user).

Notes

The Server will likely wish to debounce text changes to prevent undue WebSocket traffic.

In cases of using an external editor that does not support live updates the exchange can be quite linear:

  1. Server receives a GET / request
  2. Server opens a WebSocket
  3. Server responds with JSON describing the WS port number
  4. Client establishes a WS connection to the Server with above port number
  5. Client sends first JSON payload
  6. Server creates temporary file with the content provided in JSON payload
  7. Server spawns editor
  8. Server waits for editor to exist
  9. Server reads temp file
  10. Server sends updated JSON payload
  11. Server closes WebSocket
  12. Server deletes temp file