#+TITLE:   tools/collab
#+DATE:    September 2, 2022
#+SINCE:   v3.0.0
#+STARTUP: inlineimage nofold

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#maintainers][Maintainers]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
  - [[#with-tunnel][With =+tunnel=]]
    - [[#macos][macOS]]
    - [[#linux][Linux]]
    - [[#windows][Windows]]
- [[#features][Features]]
  - [[#keybindings][Keybindings]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
  - [[#people-outside-my-lan-cant-connect-to-the-collab-session-im-hosting][People outside my LAN can't connect to the collab session I'm hosting]]
  - [[#i-got-an-error-saying-something-including-crdtel-protocol][I got an error saying something including "crdt.el protocol"]]

* Description
This module adds collaborative editing via the [[https://code.librehq.com/qhong/crdt.el][crdt]] plugin.

** Maintainers
+ [[https://github.com/artenator][@artenator]]
+ [[https://github.com/jming422][@jming422]]

** Module Flags
+ =+tunnel= Enables TCP forwarding over the [[https://tox.chat/][Tox]] protocol so that a collaborative
  editing session can be established between machines that are behind a NAT.

** Plugins
+ [[https://code.librehq.com/qhong/crdt.el][crdt]]

* Prerequisites
With no flags, this module requires nothing else to work. The =+tunnel= flag has one dependency:

** With =+tunnel=
Tunneling requires the [[https://github.com/gjedeer/tuntox][tuntox]] program, which is used to establish TCP
connections to your collaborators over the Tox peer-to-peer networking protocol.

*** macOS
tuntox can be installed from Homebrew:
#+BEGIN_SRC bash
brew install tuntox
#+END_SRC

*** Linux
You can download the tuntox binary for most architectures from its [[https://github.com/gjedeer/tuntox/releases][Releases]] page
on GitHub, and it can be found in some [[https://repology.org/project/tuntox/versions][package manager repositories]] as well.

*** Windows
Tuntox is currently not supported on Windows, so Windows users cannot use the
=+tunnel= flag and must choose another networking solution, such as a VPN. For
more options, see [[*People outside my LAN can't connect to the collab session I'm hosting][this Troubleshooting entry]].

* Features
+ Start a collaborative editing session in one of your buffers with =M-x
  crdt-share-buffer= and following the prompts.
+ If you're using =+tunnel=, get the sharable URL of your session using =M-x
  crdt-copy-url=. If not using =+tunnel=, then instead of a URL, others can
  connect using your public IP address and chosen TCP port number (default port
  is 6530)
+ Others can connect to your session using =M-x crdt-connect= and following the
  prompts to pass in your tunnel URL or IP address and port
+ Once connected, some commands you can use are:
  + =crdt-list-buffers= to list shared buffers. Use this after =crdt-connect= to
    open shared buffers for editing!
  + =crdt-share-buffer= Start a new collaboration session, or add more buffers
    to an existing session. Once a session has started, both the host and
    clients can use this function to share buffers!
  + =crdt-goto-user= to jump to another collaborator
  + =crdt-follow-user= / =crdt-stop-follow= to toggle following another
    collaborator
  + =crdt-visualize-author-mode= to add colors to regions of the buffer,
    visualizing who most recently edited each part of the buffer
  + =crdt-stop-session= (host) / =crdt-disconnect= (client) to exit the collab
    session

** Keybindings
When this module is enabled, the `SPC l` leader keymap becomes available, making most of the above functions and more available under that prefix:

| Binding   | Description                                             |
|-----------+---------------------------------------------------------|
| =SPC l b= | Switch to a shared buffer                               |
| =SPC l c= | Connect to a session                                    |
| =SPC l d= | Disconnect from session                                 |
| =SPC l f= | Toggle following another user's cursor                  |
| =SPC l F= | Stop following user if any                              |
| =SPC l g= | Goto another user's cursor                              |
| =SPC l i= | List shared buffers                                     |
| =SPC l k= | Kick a user (host only)                                 |
| =SPC l l= | List sessions                                           |
| =SPC l s= | Share current buffer, optionally starting a new session |
| =SPC l S= | Stop sharing current buffer                             |
| =SPC l u= | List connected users                                    |
| =SPC l x= | Stop a session (host only)                              |
| =SPC l y= | Copy URL of current session                             |
| =SPC l ]= | Goto next user's cursor                                 |
| =SPC l [= | Goto previous user's cursor                             |


* Configuration

This list is not exhaustive; for the full list of config options, type =SPC h V
crdt-= after loading the module.

| Custom variable             | Default                  | Function                                                                                  |
|-----------------------------+--------------------------+-------------------------------------------------------------------------------------------|
| crdt-ask-for-name           | t                        | Set to nil to always use =crdt-default-name= as your name without asking                  |
| crdt-default-name           | ~(user-full-name)~       | Your display name in collaboration sessions                                               |
| crdt-tuntox-executable      | "tuntox"                 | Path to the tuntox binary                                                                 |
| crdt-tuntox-password-in-url | t if =+tunnel=, else nil | Set to t to put your session password (in plaintext) into the URL made by =crdt-copy-url= |


* Troubleshooting

** People outside my LAN can't connect to the collab session I'm hosting
Without =+tunnel= enabled, on most home/work networks you will be unable to have
others join you from across the Internet unless you set something up to
facilitate the connection between collaborators.
You have a lot of options here, but some of the most common are:
+ Enable the =+tunnel= flag to tunnel your traffic using the [[https://tox.chat/][Tox]] peer-to-peer
  networking protocol
+ Use a VPN
+ Use a non-peer-to-peer tunneling method, such as Teredo. One free software
  implementation of this method is called [[https://www.remlab.net/miredo/][Miredo]]
+ Use a TCP reverse proxy server, such as [[https://ngrok.com/][ngrok]]
+ Use SSH port forwarding, if you have access to a server with a public network
  address

** I got an error saying something including "crdt.el protocol"
All collaborators must be using the same version of the crdt package in order to
guarantee stability & support for all features. These types of errors should not
occur if everyone is up to date, so ensure that all collaborators have upgraded
Doom Emacs to the latest version and have not pinned =crdt=.