# Pear-On

<img src="https://git.sr.ht/~meejah/pear-on/blob/main/assets/images/icon.png" alt= "(A picture of 
two excited anthropomorphic pears in front of a computer monitor)" />

## Motivation

Pair-programming can be a great and producive way to collaborate.

Many ways of doing this involve central services and although these are frequently using Free/Open software to run them, setting up one own services is an impediment.

Pear-On uses Magic Wormhole with Dilation to enable peer-to-peer collaborative sessions.


## Origin Story

We often use `tty-share` (https://tty-share.com/) to join a collaborative pair-programming session (either one-on-one or one-to-many).
This is a great program!

However, having a live and interactive terminal session running through a third-party-run server doesn't leave the best feelings.

Knowing about Magic Wormhole, an obvious use of its "Dilation" feature is to forward TCP streams back (or forth).
Since `tty-share` is using WebSockets, has an open-source and easy-to-run server, this is a perfect test-bed.

Terminal-sharing is interesting and useful -- but of course not an entire "pair programming" toolkit by itself.
We hope to expand Pear-On to include other streaming features (such as audio, video, etc).


## The Technical Details

Looking just at the `tty-share` use-case, we have:

- the "host" runs `tty-share` as a server
- one or more "guests" run ``tty-share` as the client
- required: some way to stream data between the two

Now comes an unfortunately longstanding Internet problem: securely connecting two peers is hard (still, for various network reasons)!

### A Public Service

The author of `tty-share` runs infrastructure allowing the host and any guests to connect via a public Web site.
This is a great service!
We have no reason to believe it is malicious in any way -- but it would be very nice not to depend on it.

Hosting a service on a public-routed IP address is a popular way around the issue of connecting peers on the Internet.


### Magic Wormhole

Consider [Magic Wormhole](https://magic-wormhole.readthedocs.io/en/latest/welcome.html): it *also* solves the peer problem by having a public service.

However, it is a little more general-purpose: with the Dilation feature, we can use Magic Wormhole's public service for _any_ kind of peer communication (not just terminal-sharing, or whatever).

Magic Wormhole also does _end-to-end encryption_, meaning that the service cannot see the contents of our messages even if the operator is malicious (or is compromised by a malicious actor).


### Connecting the Pieces

Pear-On consists of:

- a GUI (written in Haskell + monomer)
- a way to start a Dilated Magic Wormhole (currently [fowl](https://github.com/meejah/fowl)
- glue to connect `tty-share` via the Wormholes

#### Why Not Pure Haskell?

Note that there *is* a [Haskell Magic-Wormhole library](https://hackage.haskell.org/package/magic-wormhole) but it does not yet support Dilation.

`fowl` is my attempt to give authors a way to leverage the full-featured Python implementation of Dilation + Magic Wormhole from a "black box" CLI program -- no need for Python bindings, etc!

That said, I'd love to see the Haskell Wormhole library grow a Dilation implementation -- then Pear-On could be pure Haskell!


## Running the Software

Okay, great, lets use the software!

Currently you must have `fowl` in your `PATH`.
I use a "virtualenv" to accomplish this::

    python -m venv venv
    ./venv/bin/pip install fowl
    source venv/bin/activate
    fowl --help

Once `fowl` is in your `PATH` and can be run as a normal program, you can start "pear-on" using cabal::

    cabal run

Note that you might need to `export PYTHONUNBUFFERED=1` into the shell to get things working (see https://github.com/meejah/fowl/issues/6 ).

This should pop up the GUI (such as it is so far)