#+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!