From 8ad92a40f82595f8b64f022aa3628fbbc882c3e8 Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@fripost.org>
Date: Mon, 16 Mar 2015 02:58:40 +0100
Subject: Document the protocol.

---
 xul-ext/README | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 xul-ext/README

diff --git a/xul-ext/README b/xul-ext/README
new file mode 100644
index 0000000..1d08374
--- /dev/null
+++ b/xul-ext/README
@@ -0,0 +1,107 @@
+Upon startup, Firefox creates and listens on a new UNIX socket (shared
+accross all tabs and windows) on which commands can be thrown in to fill
+HTML forms.  The greeting message indicates that the server is ready to
+accept commands.  Each command and response are single UTF8-encoded
+lines ending with a newline character `\n'.  Each reponse consists of a
+code (OK, ERROR, or BYE), together with an optional message.  Each
+command line yields to a single a response line, and commands may not be
+sent in parallel: clients must wait for the response of a first command
+before sending a second one.
+
+A OK response code indicates a successful greeting or client command,
+and may be accompanied with a JSON-encoded message data.  An ERROR
+response code indicates a server or client protocol error, the reason of
+which may be given as an accompanying UTF8 string.  A BYE response code
+indicates an imminent end to client connection.
+
+    OK [' ' JSON-encoded-data]
+    ERROR ' ' UTF8String
+    BYE
+
+
+The greeting message consists of the the URI (scheme://hostname:port) of
+the active tab of the active window.  (":port" is ommited for default
+ports, e.g., 443 for https.)  Said URI is then cached for the whole
+session, utils the client disconnects or an REFRESH command is issued.
+Hence subsequent GETFORMS and FILL commands are always relative to the
+greeting or the most recent REFRESH response URI, and not the possibly
+new active tab.  The URI is JSON-encoded (and decodes as a string not an
+object, which is an extension to RFC4627) hence non-printable and
+control characters are excaped properly (but they are not valid in a
+hostname anyway).
+
+    S: OK ' ' JSON-encoded-URI
+
+
+The REFRESH command clears the internal URI and HTML form caches, and
+the server replies with the URI of the currently (active) tab of the
+(currently) active window.  See the greeting message above for details.
+
+    C: REFRESH
+    S: OK ' ' JSON-encoded-URI
+
+
+The GETFORMS command yields a response message data consisting of the list of
+all visible forms, with their method, action URI, and for each field of type
+password, text or email, their name, type, value and maxLength (unless -1)
+values:
+
+    [
+      {
+        "method": "POST",
+        "action": "https://mail.fripost.org/",
+        "fields": [
+          {
+            "name": "_user",
+            "type": "text",
+            "value": "guilhem"
+          },
+          {
+            "name": "_pass",
+            "type": "password",
+            "value": "top secret"
+            "maxLength": 32
+          }
+        ]
+      }
+    ]
+
+The form list is kept in cache until the client closes the connection or
+another GETFORMS command is issued.  This ensure that subsequent FILL commands
+are relatve to these forms even if the document has been modified.
+
+    C: GETFORMS
+    S: OK JSON-encoded-array
+
+
+The FILL command must be preceeded by a GETFORM command, and takes an index and
+a JSON-encoded array of string as arguments.  The index is that of the form one
+wants to fill, and the array must be at most as long as there are of fields in
+that form (as found in the most recent GETFORMS response).  The value of
+each such field is then updated with that found in the array (unless
+null).
+
+    C: FILL index JSON-encoded-array
+    S: OK
+
+
+The QUIT command yields a BYE response.
+
+    R: QUIT
+    S: BYE
+
+
+
+Example:
+
+    S: OK "https://mail.fripost.org"
+    C: GETFORMS
+    S: OK [{"method":"POST","action":"https://mail.fripost.org/","fields":[{"name":"_user","type":"text","value":""},{"name":"_pass","type":"password","value":""}]}]
+    C: FILL 0 ["guilhem","topsecret"]
+    S: OK
+    C: GETFORM
+    S: ERROR Invalid command: GETFORM
+    C: GETFORMS
+    S: OK [{"method":"POST","action":"https://mail.fripost.org/","fields":[{"name":"_user","type":"text","value":"guilhem"},{"name":"_pass","type":"password","value":"topsecret"}]}]
+    C: QUIT
+    S: BYE
-- 
cgit v1.2.3