From fe1f911fc417b86346e4c7630bad325b4886295a Mon Sep 17 00:00:00 2001
From: jao <jao@gnu.org>
Date: Sun, 23 Feb 2020 15:43:19 +0000
Subject: new app: signel

---
 net/signel.org | 396 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 396 insertions(+)
 create mode 100644 net/signel.org

(limited to 'net/signel.org')

diff --git a/net/signel.org b/net/signel.org
new file mode 100644
index 0000000..be166ee
--- /dev/null
+++ b/net/signel.org
@@ -0,0 +1,396 @@
+#+title: signel, a barebones signal chat on top of signal-cli
+#+date: <2020-02-23 05:03>
+#+filetags: emacs
+#+PROPERTY: header-args :tangle yes :comments yes :results silent
+
+Unlike most chat systems in common use, [[https://signal.org][Signal]] lacks a decent emacs
+client.   All i could find was [[https://github.com/mrkrd/signal-msg][signal-msg]], which is able only to send
+messages and has a readme that explicitly warns that its is /not/ a chat
+application.  Skimming over signal-msg's code i learnt about
+[[https://github.com/AsamK/signal-cli][signal-cli]], a java-based daemon that knows how to send and receive
+signal messages, and how to link to a nearby phone, or register new
+users.  And playing with it i saw that it can output its activities
+formatted as JSON, and that offers (when run in daemon mode) a DBUS
+service that can be used to send messages.
+
+Now, emacs knows how to run a process and capture its output handling
+it to a filter function, and comes equipped with a JSON parser and
+a set of built-in functions to talk to DBUS buses.
+
+So how about writing a simple Signal chat app for emacs? Let's call it
+/signel/, and write it as [[./signel.ox][a blog post in literate org-mode]].
+
+* Starting a process
+
+We are going to need a variable for our identity (telephone number),
+and a list of contact names (until i discover how to get them directly
+from signal-cli):
+
+#+begin_src emacs-lisp
+(defvar signel-cli-user "+44744xxxxxx")
+(defvar signel-user-names '(("+447xxxxxxxx" . "john")
+                            ("+346xxxxxxxx" . "anna")))
+#+end_src
+
+and a simple function to get a contact name given its telephone
+number:
+
+#+begin_src emacs-lisp
+(defun signel--source-name (src)
+  (or (cdr (assoc src signel-contact-names)) src))
+#+end_src
+
+We are also going to need the path for our signal-cli executable
+
+#+begin_src emacs-lisp
+(defvar signel-cli-exec "signal-cli")
+#+end_src
+
+Starting the signal-cli process is easy: ~make-process~ provides all the
+necessary bits. What we need is essentially calling
+
+#+begin_src shell
+signal-cli -u +44744xxxxxx daemon --json
+#+end_src
+
+associating to the process a buffer selected by the function
+~signel--proc-buffer~ .  While we are at it, we'll write also little
+helpers for users of our API.
+
+#+begin_src emacs-lisp
+(defun signel--proc-buffer ()
+  (get-buffer-create "*signal-cli*"))
+
+(defun signel-signal-cli-buffer ()
+  (get-buffer "*signal-cli*"))
+
+(defun signel-signal-cli-process ()
+  (when-let ((proc (get-buffer-process (signel-signal-cli-buffer))))
+    (and (process-live-p proc) proc)))
+#+end_src
+
+#+begin_src emacs-lisp
+(defun signel-start ()
+  "Start the underlying signal-cli process if needed."
+  (interactive)
+  (if (signel-signal-cli-process)
+      (message "signal-cli is already running!")
+    (let ((b (signel--proc-buffer)))
+      (make-process :name "signal-cli"
+                    :buffer b
+                    :command `(,signel-cli-exec
+                               "-u"
+                               ,signel-cli-user
+                               "daemon" "--json")
+                    :filter #'signel--filter)
+      (message "Listening to signals!"))))
+#+end_src
+
+* Parsing JSON
+
+We've told emacs to handle any ouput of the process to the function
+~signel--filter~, which we're going to write next.  This function will
+receive the process object and its latest output as a string
+representing a JSON object.  Here's an example of the kind of outputs
+that signal-cli emits:
+
+#+begin_src json :tangle no
+{
+  "envelope": {
+    "source": "+4473xxxxxxxx",
+    "sourceDevice": 1,
+    "relay": null,
+    "timestamp": 1582396178696,
+    "isReceipt": false,
+    "dataMessage": {
+      "timestamp": 1582396178696,
+      "message": "Hello there!",
+      "expiresInSeconds": 0,
+      "attachments": [],
+      "groupInfo": null
+    },
+    "syncMessage": null,
+    "callMessage": null,
+    "receiptMessage": null
+  }
+}
+#+end_src
+
+Everything seems to be always inside ~envelope~, which contains objects
+for the possible messages received.  In the example above, we're
+receiving a message from a /source/ contact.  We can also receive
+receipt messages, telling us whether our last message has been
+received or read; e.g.:
+
+#+begin_src json :tangle no
+{
+  "envelope": {
+    "source": "+4473xxxxxxxx",
+    "sourceDevice": 1,
+    "relay": null,
+    "timestamp": 1582397117584,
+    "isReceipt": false,
+    "dataMessage": null,
+    "syncMessage": null,
+    "callMessage": null,
+    "receiptMessage": {
+      "when": 1582397117584,
+      "isDelivery": true,
+      "isRead": false,
+      "timestamps": [
+        1582397111524
+      ]
+    }
+  }
+}
+#+end_src
+
+A bit confusingly, that delivery notification has a ~receiptMessage~,
+but its ~isReceipt~ flag is set to ~false~.  Oh well, i'm sure there's a
+reason, but for now, we're going to ignore that flag.
+
+
+It is very easy to parse JSON in emacs and extract signal-cli's
+envelopes:
+
+#+begin_src emacs-lisp
+(defun signel--msg-contents (str)
+  (cdr (assoc 'envelope (ignore-error 'json-parse-error
+                          (json-parse-string str
+                                             :null-object nil
+                                             :false-object nil
+                                             :object-type 'alist
+                                             :array-type 'list)))))
+#+end_src
+
+Here i am being old-school and opting to receive JSON dicitionaries as
+alists (rather than hash maps, the default), and arrays as lists
+rather than vectors just because lisps are lisps for a reason.  I'm
+also going to do some mild [[https://lispcast.com/nil-punning/][nil punning]],
+hence the choice for null and false representations.
+
+Once the contents of the envelope is extracted, it's trivial (and
+boring) to get into its components:
+
+#+begin_src emacs-lisp
+(defun signel--msg-source (msg) (cdr (assoc 'source msg)))
+
+(defun signel--msg-data (msg)
+  (cdr (assoc 'message (cdr (assoc 'dataMessage msg)))))
+
+(defun signel--msg-timestamp (msg)
+  (if-let (msecs (cdr (assoc 'timestamp msg)))
+      (format-time-string "%H:%M" (/ msecs 1000))
+    ""))
+
+(defun signel--msg-receipt (msg)
+  (cdr (assoc 'receiptMessage msg)))
+
+(defun signel--msg-receipt-timestamp (msg)
+  (when-let (secs (cdr (assoc 'when (signel--msg-receipt msg))))
+    (format-time-string "%H:%M" secs)))
+
+(defun signel--msg-is-delivery (msg)
+  (when-let ((receipt (signel--msg-receipt msg)))
+    (eq t (cdr (assoc 'isDelivery msg)))))
+
+(defun signel--msg-is-read (msg)
+  (when-let ((receipt (signel--msg-receipt msg)))
+    (eq t (cdr (assoc 'isRead msg)))))
+#+end_src
+
+* A process output filter
+
+We're almost ready to write our filter.  It will:
+
+- For debugging purposes, insert the raw JSON string in the process
+  buffer.
+- Parse the received JSON string and extract its envelope contents.
+- Check wether it has a source and either message data or a receipt
+  timestamp.
+- Dispatch to a helper function that will insert the data or
+  notification in a chat buffer.
+
+Or, in elisp:
+
+#+begin_src emacs-lisp
+(defun signel--filter (proc str)
+  (signel--ordinary-insertion-filter proc str)
+  (when-let ((msg (signel--msg-contents str)))
+    (let ((source (signel--msg-source msg))
+          (stamp (signel--msg-timestamp msg))
+          (data (signel--msg-data msg))
+          (rec-stamp (signel--msg-receipt-timestamp msg)))
+      (when (and source (or data rec-stamp))
+        (signel--update-chat-buffer source data stamp rec-stamp msg)))))
+#+end_src
+
+The function to insert the raw contents in the process buffer is
+surprisingly hard to get right, but the emacs manual spells out a
+reasonable implementation, which i just copied:
+
+#+begin_src emacs-lisp
+(defun signel--ordinary-insertion-filter (proc string)
+  (when (buffer-live-p (process-buffer proc))
+    (with-current-buffer (process-buffer proc)
+      (let ((moving (= (point) (process-mark proc))))
+        (save-excursion
+          ;; Insert the text, advancing the process marker.
+          (goto-char (process-mark proc))
+          (insert string)
+          (set-marker (process-mark proc) (point)))
+        (if moving (goto-char (process-mark proc)))))))
+#+end_src
+
+* It's not an emacs app if it doesn't have a new mode
+
+With that out of the way, we just have to insert our data in an
+appropriate buffer.  We are going to associate a separate buffer to
+each /source/, using for that its name:
+
+#+begin_src emacs-lisp
+(defvar-local signel-user nil)
+
+(defun signel--source-buffer (source)
+  (let* ((name (format "*%s" (signel--source-name source)))
+         (buffer (get-buffer name)))
+    (unless buffer
+      (setq buffer (get-buffer-create name))
+      (with-current-buffer buffer
+        (signel-chat-mode)
+        (setq-local signel-user source)))
+    buffer))
+#+end_src
+
+where, as is often the case in emacs, we are going to have a dedicated
+major mode for chat buffers, called ~signel-chat-mode~.  For now, let's
+keep it really simple (for the record, this is essentially a copy of
+what ERC does for its erc-mode):
+
+#+begin_src emacs-lisp
+(defvar signel-prompt ": ")
+
+(define-derived-mode signel-chat-mode fundamental-mode "Signal"
+  "Major mode for Signal chats."
+  (when (boundp 'next-line-add-newlines)
+    (set (make-local-variable 'next-line-add-newlines) nil))
+  (setq line-move-ignore-invisible t)
+  (set (make-local-variable 'paragraph-separate)
+       (concat "\C-l\\|\\(^" (regexp-quote signel-prompt) "\\)"))
+  (set (make-local-variable 'paragraph-start)
+       (concat "\\(" (regexp-quote signel-prompt) "\\)"))
+  (setq-local completion-ignore-case t))
+#+end_src
+
+Note how, in ~signel--source-buffer~, we're storing the user identity
+associated with the buffer (its /source/) in a buffer-local variable
+named ~signel-user~ that is set /after/ enabling ~signel-chat-mode~: order
+here matters because the major mode activation cleans up the values of
+any local variables previously set (i always forget that!).
+
+We have now all the ingredients to write ~signel--update-chat-buffer~,
+the function that inserts the received message data into the chat
+buffer:
+
+#+begin_src emacs-lisp
+(defun signel--update-chat-buffer (source data stamp rec-stamp msg)
+  (when-let ((b (signel--source-buffer source)))
+    (with-current-buffer b
+      (goto-char (point-max))
+      (beginning-of-line)
+      (ignore-errors (kill-line))
+      (if data
+          (let ((p (point)))
+            (insert "[" stamp "] "
+                    (signel--source-name source)
+                    signel-prompt
+                    data
+                    "\n")
+            (fill-region p (point)))
+        (let ((is-delivery (signel--msg-is-delivery msg))
+              (is-read (signel--msg-is-read msg)))
+          (when rec-stamp
+            (insert "[" rec-stamp "] "
+                    (if is-read "(read)" "(delivered)")
+                    "\n"))))
+      (insert signel-prompt))
+    (when (fboundp 'tracking-add-buffer)
+      (tracking-add-buffer b '(erc-pal-face)))))
+#+end_src
+
+There are several rough edges in the above implementation that must
+be polished shold signel ever be released in the wild.  For one,
+proper handling of timestamps and their formats, and some font lock
+for the different parts of the inserted texts.  And of course
+notifications should be much more customizable (here i'm using
+[[https://github.com/jorgenschaefer/circe/blob/master/tracking.el][Circe's tracking.el]] if available).
+
+* The DBUS interface
+
+With that, we're going to receive and display messages and simple
+receipts, and i'm sure that we will feel the urge to answer some of
+them.  As mentioned above, signal-cli let's us send messages via its
+[[https://github.com/AsamK/signal-cli/wiki/DBus-service][DBUS interface]].
+In a nutshell, if you want to send ~MESSAGETEXT~ to a
+~RECIPIENT~ you'd invoke something like:
+
+#+begin_src shell :tangle no
+dbus-send --session --type=method_call \
+          --dest="org.asamk.Signal" \
+          /org/asamk/Signal \
+          org.asamk.Signal.sendMessage \
+          string:MESSAGETEXT array:string: string:RECIPIENT
+#+end_src
+
+That is, call the method ~sendMessage~ of the corresponding service
+interface with three arguments (the second one empty).  Using emacs'
+dbus libray one can write the above as:
+
+#+begin_src emacs-lisp
+(defun signel--send-message (user msg)
+  (dbus-call-method :session "org.asamk.Signal" "/org/asamk/Signal"
+                    "org.asamk.Signal" "sendMessage"
+                    :string msg
+                    '(:array)
+                    :string user))
+#+end_src
+
+The only complicated bit is being careful with the specification of
+the types of the method arguments: if one gets them wrong, DBUS will
+simply complain and say that the method is not defined, which was
+confusing me at first (but of course makes sense because DBUS allows
+overloading method names, so the full method spec must include its
+signature).
+
+We want to read whatever our user writes after the last prompt and
+send it via the little helper above.  Here's our interactive command
+for that:
+
+#+begin_src emacs-lisp
+(defun signel-send ()
+  "Read text inserted in the current buffer after the last prompt and send it.
+
+The recipient of the message is looked up in a local variable set
+when the buffer was created."
+  (interactive)
+  (goto-char (point-max))
+  (beginning-of-line)
+  (let* ((p (point))
+         (msg (buffer-substring (+ p (length signel-prompt)) (point-max))))
+    (signel--send-message signel-user msg)
+    (insert (format-time-string "(%H:%M) "))
+    (fill-region p (point-max))
+    (goto-char (point-max))
+    (insert "\n" signel-prompt)))
+#+end_src
+
+and we can bind it to the return key in signal chat buffers:
+
+#+begin_src emacs-lisp
+(define-key signel-chat-mode-map "\C-m" #'signel-send)
+#+end_src
+
+There are of course lots of rough edges and missing functionality in
+this incipient signel, but it's already usable and a nice
+demonstration of how easy it is to get the ball rolling in this lisp
+machine of ours!
-- 
cgit v1.2.3