fregante / GhostText

👻 Use your text editor to write in your browser. Everything you type in the editor will be instantly updated in the browser (and vice versa).
https://GhostText.fregante.com
MIT License
3.28k stars 117 forks source link

Add a protocol specification document #107

Closed idanarye closed 6 years ago

idanarye commented 6 years ago

Can you add a PROTOCL.md for describing the protocol between the Chrome extension and the editor extension/script? Without something like this, people who want to write an extension for their favorite editor have to reverse engineer the chrome extension or one of the plugins...

fregante commented 6 years ago

The developer who implemented the protocol is no longer available so for that document to exist, someone has to reverse engineer it. PRs welcome.

fregante commented 6 years ago

Here's how it works in short:

  1. Server starts at localhost:4001, inside the editor. 4001 is the default port but should be customizable on both sides.
  2. Browser sends an empty fetch() towards http://localhost:4001
  3. Server replies with a JSON like {"ProtocolVersion":1, "WebSocketPort":12345}, where 12345 is the editor's new WebSocket server's port.
  4. Server/editor opens a new tab (no info available yet).
  5. Browser sends the first JSON message via WebSocket like:
    {
        title: document.title, // String
        url: location.host, // String
        syntax: '', // unused for now
        text: field.value, // String
        selections: [
            {
                // 0-index positions of selection, integers
                start: this.field.selectionStart
                end: this.field.selectionEnd
            }
        ]
    }
  6. Browser keeps sending the message as the field.value changes.
  7. Editor keeps sending the same JSON message but just with text and selection fields.
  8. Editor or browser may close the WebSocket.