rename README as protocol

1 files changed, 109 insertions, 0 deletions

diff --git a/xul-ext/protocol b/xul-ext/protocol
new file mode 100644
index 0000000..b29e2fd
--- /dev/null
+++ b/xul-ext/protocol
@@ -0,0 +1,109 @@
+Upon startup, Firefox creates and listens on a new UNIX socket (shared
+between 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 string lines
+ending with a newline character `\n'.  (JSON-encoding ensures that
+control characters are escaped properly;  decoding to a string rather
+than an object is allowed here, although it extends RFC4627.)  Each
+response consists of a code (OK, ERROR, or BYE), together with a
+JSON-encoded 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.
+
+An 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 JSON-encoded UTF8 string.  A BYE
+response code indicates an imminent end to client connection.
+
+    S: OK [' ' JSON-encoded-data]
+    S: ERROR ' ' JSON-encoded-string
+    S: BYE
+
+
+The greeting message consists of the the URI (scheme://hostname:port) of
+the active tab of the active window.  (":port" is omitted for default
+ports, e.g., 443 for https.)  Said URI is then cached for the whole
+session, until 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, rather than the
+possibly new active tab.  The URI is a JSON-encoded string.
+
+    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 relative to these forms even if the document has been
+modified.
+
+    C: GETFORMS
+    S: OK JSON-encoded-array
+
+
+The FILL command must be preceded 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, and terminates the connection.
+
+    C: QUIT
+    S: BYE
+
+
+
+Example:
+
+    # client initiates the connection
+    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
+    # client is disconnected