Parsee/README.MD

# Parsee - the jealous XMPP<=>Matrix bridge
Parsee is a Matrix<=>XMPP bridge written in C99, with Cytoplasm, similar to Bifrost, but it is 
NOT a drop-in replacment.
Currently, it is *alpha* stage, which means that I wouldn't recommend using this in production, 
as I can change anything, at any time, and it may behave strangely at times.

## Why?
### Naming
The name 'Parsee' is actually a reference to [Parsee Mizuhashi](https://en.touhouwiki.net/wiki/Parsee_Mizuhashi), 
a "*bridge* princess". The other name you actually can sometimes see explains itself, so I won't 
be talking about it.

### Reasoning (personal to LDA)
I hate Bifrost. I also wanted to dip my toes in XMPP, XML, and bridges a bit. Also, as a sister 
project to KappaChat, this means that I can integrate Parsee with KappaChat however I wish it 
to be, which allows me to mess around with a codebase I'm already familiar with.
A more "up-to-date" reason may be to have a small, 'Just Werks' bridging solution *that is good*, 
and maybe as a testing ground for Cytoplasm features I sometimes add.

(Well, I'm *trying* to do that, at least. 
Please scream at me if that fails(or just doesn't run on a overclocked Raspberry Pi 4B))

### "Why not just use Matrix lol"
### "Why not just use XMPP lol"
These two having the same answer should be enough information.
One could also argue that both sides need to migrate(onboard) the other side, so 
a bridge may be a good way to start.

## BUILDING
```sh
$ cc configure.c -o configure # that or use tcc -run to consolidate these two steps.
$ ./configure # use -s if you want static Parsee+MbedTLS, use -s -l if LMDB is needed
$ make
$ make [PREFIX=...] install # run as root if on a protected dir like /usr
```
If there are any Cytoplasm-related build failures, you may want to check the Makefile to 
change a few variables (you can set `CYTO_INC` and `CYTO_LIB` for Cytoplasm's include and 
library paths specifically.)
If you build with MbedTLS, please mind setting the `CYTO_TLS_CA` env to Parsee.

### DEPENDENCIES
Parsee tries to avoid dependencies aside from [Cytoplasm](https://git.telodendria.io/Telodendria/Cytoplasm). 
Itself optionally depends on a good POSIX implementation, and optionally OpenSSL/LMDB (highly recommended, but 
you can get away without those if you're adventurous).

### BUILDING WITH GUIX
If you have [Guix](https://guix.gnu.org/) installed, you can build Parsee using `guix package -f guix.scm`, or test it
using `guix shell -f guix.scm`. You can also generate a Docker/OCI image.
```sh
guix pack -f docker -S /bin=bin -L.guix/modules parsee
```

## RUNNING
First off, you may want to configure Parsee by running the `config` tool(generally named 
`parsee-config` in most cases), with the correct flags, like here.
```sh
parsee-config \
    -d data/ \
    -m 'https://media.blow.hole/' \ # You will need to reverse proxy media.blow.hole to point 
                                    # to Parsee (port 7642)
    -H 'blow.hole' \ # Matrix homeserver name
    -J 'parsee.blow.hole' \ # XMPP component host, must be reachable
    -s 'A very secure XMPP component secret' \
    -p 5347 \
    -M 65535 # Maximum stanza size. Stanzas larger than this from Parsee will be dropped to avoid stream closures. Leave this empty if you're unsure.
```

If everything goes well, it should generate a `parsee.json` file.

To start Parsee, run it in the same directory as the `parsee.json` with the `-g` flag. It should 
start properly and produce a `parsee.yaml` file, which you can chuck into your Matrix homeserver. 
To test if the homeserver can talk to Parsee, try reaching it over HTTP at the port 7642. If it 
returns with a landing page, then this side works. You can read it for some more information.


## DOCS
Currently, the main sources of documentation are the Ayadocs(for headers) and the manpages
(see `etc/man`).

## TODOS before 1.0 rolls around
- Make Parsee actually go *vroooooooooommmmmmm*.
- Make sure Parsee can easily run on just about any reasonable POSIX 
system.
- Avoid making 'back-puppets' from Matrix as much as possible
- Extension support. I'd need to design a good system, and maybe do it 
with either shared libraries(`dlopen`/`dlclose` on POSIX) or use a 
language like Janet or Lua.
- Add [libomemo](https://github.com/gkdr/libomemo) or something as an optional dependency. 
    - It depends on more stuff anyways, and I don't want to weigh down the 
    dependency list of Parsee for that.
    - Matrix's libolm is deprecated. They replaced it with a Rust version that 
    pulls in *way too many* dependencies, and that lacks a C binding. We may 
    ~~put in the work of either forking off libolm or~~ be making a binding with 
    KappaChat(when I get around to remaking UI :p).
        - Josh did infact tell me that maybe C bindings may happen. I'd be 
        willing to help out, but IDK. In any case, this will at best be an 
        extension packagers may integrate properly.
- Get rid of the '?'-syntax and use another invalid Matrix char/valid XMPP char 
('$'?) for escaped?
- Consider making room/MUC admins/owners be able to plumb instead of it being 
restricted to Parsee admins, with permission from MUC owners, too
    - Limiting to admins may be a way to "control" consent for both, but this is 
    only if Parsee admins are good-willed, which we must assume such statment to 
    be false by default.
    - Currently, MUC owners may kick Parsee out, with the effect of unlinking the 
    MUC.
- Look at XEPS-TBD.TXT for XEPs to be done
- Add a MUC server to Parsee, such that it may be able to hook onto it and therefore 
support XMPP->Matrix bridging.
- Manage MUC DMs in a reasonable manner. Thanks `@freeoffers4u:matrix.org` for being 
a fucking annoyance and DMing an old Parsee semi-anon user for no clear reason.
- Make Parsee cope with stream closures(i.e: XMPP server turning off) better. As of 
now, it just kills itself when that happens, instead of trying to negociate a new 
connection, which would be a better method that would actually fit Parsee's own 
principles.

## DONATING/CONTRIBUTING
If you know things about XMPP or Matrix, yet aren't familiar with C99, or just
want to suggest a feature, you may open an issue.

Packaging Parsee (and Cytoplasm) for your specific platform might be a nice to have,
to make Parsee easier to setup and manage.

If you want, you may want to give this project some word-of-mouth as advertisment.

**(DON'T FOR NOW, THERE IS LITERALLY NOWHERE THIS GOES TO)**
You may also donate to [the LiberaPay](https://en.liberapay.com/Parsee), alongside 
[Telodendria's](https://en.liberapay.com/Telodendria), as it is the project 
currently maintaining Cytoplasm.

## IM chats
Please avoid asking for help/issues there. If you *really* want, you may just open 
an issue and link it over it. Basic respect for others/not being an asshat is required.
(Also, these are temporary room aliases.)
- [#parsee:tedomum.net](https://matrix.to/#/%23parsee:tedomum.net)
- [parsee@conference.monocles.eu](xmpp:parsee@conference.monocles.eu?join)