0k-charms/synapse

Opiniated choice of this charm
==============================

- As API is REST and compatible to be on same port, ``synapse`` server
  and client will be served on the same port 8008. This will allow
  one-port communication that can be reverse-proxified easily and is
  usually open even in tight controlled network environment.

- for simplicity sake, one-responsibility and consistency, SSL support
  is delegated to ``web_proxy``. So any ACME support on synapse side
  is disabled.

- Departing from standard ``8448`` port for federation support requires
  some delegation support to be implemented, either with DNS ``SRV``
  method, or with ``.well-known`` method. The second is chosen as the
  first was declared as temporary, and is flawed (see section talking
  of that). A third reason is that ``DNS`` charm is still not written
  so that is something we don't have control on yet easily whereas
  ``.well-known`` host might be easier to implement in existing ``web-proxy``
  charms (even if not trivial).


Information
===========

As it was difficult to gather information from synapse, here is a quick
recap of most useful concepts and references::

- Ansible recipe: https://github.com/spantaleev/matrix-docker-ansible-deploy

  Which is very complete on a fully featured deployment. With real code that
  is readable. This was a keypoint for a working example providing a
  ``.well-known`` delegation that actually works. But it also sports LDAP
  auth, mxid, or whatsapp and telegram bridges config that might become
  handy soon.



Delegation
==========

To enable federation and having a delegate server (ie:
``matrix.domain.com`` for the server managing ``domain.com``
ids... for instance to use ``@user:domain.com`` for user id instead of
``@user:matrix.domain.com`` even if you matrix server is on
``matrix.domain.com``), there are 2 options, and only one is fully
working as expected (spoiler alert, it is the ``.well-known``
solution).

The reference spec is there:

https://matrix.org/docs/spec/server_server/r0.1.1.html#resolving-server-names


DNS SRV method
--------------

This method uses the ``SRV`` DNS record. It is flawed in the way that
if we provide the delegated hostname, the actual delegated hostname
itself won't be used directly, it will be used only to resolv an IP,
and then the HTTPS will set ``Host:`` header to the former hostname,
not the delegate, (in our example, it'll contact ``matrix.domain.org``'s IP and
will contact this IP asking ``Host: domain.org``).

Which will mess with SSL certificate names of course if you are
actually having 2 separated virtual hosts with separate SSL
certificates.

This is how to set up the DNS record according to synapse docs::

> To use a SRV record, first create your SRV record and publish it in DNS.
>  This should have the format ``_matrix._tcp.<yourdomain.com> <ttl> IN SRV 
> 10 0 <port> <synapse.server.name>``. The DNS record should then look 
> something like:
>
>     $ dig -t srv _matrix._tcp.example.com
>     _matrix._tcp.example.com. 3600  IN   SRV   10 0 8448 synapse.example.com.
>
> Note that the server hostname cannot be an alias (CNAME record): it has 
> to point directly to the server hosting the synapse instance.

Note: DNS ``SRV`` method is said to be temporary.

The rationale behind this "flaw" is laid down here:
https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#interaction-with-srv-records


.well-known method
------------------


https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/matrix-base/templates/static-files/well-known/matrix-server.j2

Troubleshooting
===============

https://matrix.org/federationtester


https://matrix.org/federationtester/api/report?server_name=DOMAIN