From fd91555f1af0becf41f6ecc7a276de6114aefc04 Mon Sep 17 00:00:00 2001 From: Azrenbeth Date: Tue, 7 Sep 2021 16:19:34 +0000 Subject: deploy: e7b78dcc4a6bf8fdb71782640932da8dff7cc5ed --- latest/print.html | 650 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 404 insertions(+), 246 deletions(-) (limited to 'latest/print.html') diff --git a/latest/print.html b/latest/print.html index 53931652ab..85964f0f41 100644 --- a/latest/print.html +++ b/latest/print.html @@ -101,7 +101,7 @@ @@ -184,65 +184,6 @@

Welcome to the documentation repository for Synapse, the reference Matrix homeserver implementation.

Installation Instructions

-

There are 3 steps to follow under Installation Instructions.

-

Choosing your server name

It is important to choose the name for your server before you install Synapse, because it cannot be changed later.

@@ -886,6 +827,9 @@ to proxied traffic.)

server_name matrix.example.com; location ~* ^(\/_matrix|\/_synapse\/client) { + # note: do not add a path (even a single /) after the port in `proxy_pass`, + # otherwise nginx will canonicalise the URI and cause signature verification + # errors. proxy_pass http://localhost:8008; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; @@ -897,9 +841,7 @@ to proxied traffic.)

} } -

NOTE: Do not add a path after the port in proxy_pass, otherwise nginx will -canonicalise/normalise the URI.

-

Caddy 1

+

Caddy v1

matrix.example.com {
   proxy /_matrix http://localhost:8008 {
     transparent
@@ -916,7 +858,7 @@ example.com:8448 {
   }
 }
-

Caddy 2

+

Caddy v2

matrix.example.com {
   reverse_proxy /_matrix/* http://localhost:8008
   reverse_proxy /_synapse/client/* http://localhost:8008
@@ -1545,6 +1487,25 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
+

Upgrading to v1.42.0

+

Removal of old Room Admin API

+

The following admin APIs were deprecated in Synapse 1.25 +(released on 2021-01-13) and have now been removed:

+ +

Any scripts still using the above APIs should be converted to use the +Delete Room API.

+

User-interactive authentication fallback templates can now display errors

+

This may affect you if you make use of custom HTML templates for the +reCAPTCHA or +terms fallback pages.

+

The template is now provided an error variable if the authentication +process failed. See the default templates linked above for an example.

+

Removal of out-of-date email pushers

+

Users will stop receiving message updates via email for addresses that were +once, but not still, linked to their account.

Upgrading to v1.41.0

Add support for routing outbound HTTP requests via a proxy for federation

Since Synapse 1.6.0 (2019-11-26) you can set a proxy for outbound HTTP requests via @@ -3086,20 +3047,6 @@ presence: # #enabled: false - # Presence routers are third-party modules that can specify additional logic - # to where presence updates from users are routed. - # - presence_router: - # The custom module's class. Uncomment to use a custom presence router module. - # - #module: "my_custom_router.PresenceRouter" - - # Configuration options of the custom module. Refer to your module's - # documentation for available options. - # - #config: - # example_option: 'something' - # Whether to require authentication to retrieve profile data (avatars, # display names) of other users through the client API. Defaults to # 'false'. Note that profile data is also available via the federation @@ -3785,6 +3732,8 @@ log_config: "CONFDIR/SERVERNAME.log.config" # is using # - one for registration that ratelimits registration requests based on the # client's IP address. +# - one for checking the validity of registration tokens that ratelimits +# requests based on the client's IP address. # - one for login that ratelimits login requests based on the client's IP # address. # - one for login that ratelimits login requests based on the account the @@ -3813,6 +3762,10 @@ log_config: "CONFDIR/SERVERNAME.log.config" # per_second: 0.17 # burst_count: 3 # +#rc_registration_token_validity: +# per_second: 0.1 +# burst_count: 5 +# #rc_login: # address: # per_second: 0.17 @@ -4161,6 +4114,15 @@ url_preview_accept_language: # #enable_3pid_lookup: true +# Require users to submit a token during registration. +# Tokens can be managed using the admin API: +# https://matrix-org.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html +# Note that `enable_registration` must be set to `true`. +# Disabling this option will not delete any tokens previously generated. +# Defaults to false. Uncomment the following to require tokens: +# +#registration_requires_token: true + # If set, allows registration of standard or admin accounts by anyone who # has the shared secret, even if registration is otherwise disabled. # @@ -6167,7 +6129,7 @@ Edit your Synapse config file and change the oidc_config section: -

Dex

+

Dex

Dex is a simple, open-source, certified OpenID Connect Provider. Although it is designed to help building a full-blown provider with an external database, it can be configured with static passwords in a config file.

@@ -6196,7 +6158,7 @@ to install Dex.

localpart_template: "{{ user.name }}" display_name_template: "{{ user.name|capitalize }}" -

Keycloak

+

Keycloak

Keycloak is an opensource IdP maintained by Red Hat.

Follow the Getting Started Guide to install Keycloak and set up a realm.

    @@ -6245,7 +6207,8 @@ to install Dex.

    localpart_template: "{{ user.preferred_username }}" display_name_template: "{{ user.name }}" -

    Auth0

    +

    Auth0

    +

    Auth0 is a hosted SaaS IdP solution.

    1. Create a regular web application for Synapse

      @@ -6288,7 +6251,7 @@ to install Dex.

      display_name_template: "{{ user.name }}"

      GitHub

      -

      GitHub is a bit special as it is not an OpenID Connect compliant provider, but +

      GitHub is a bit special as it is not an OpenID Connect compliant provider, but just a regular OAuth2 provider.

      The /user API endpoint can be used to retrieve information on the authenticated user. As the Synapse @@ -6317,11 +6280,12 @@ does not return a sub property, an alternative subject_claim< localpart_template: "{{ user.login }}" display_name_template: "{{ user.name }}" -

      Google

      +

      Google

      +

      Google is an OpenID certified authentication and authorisation provider.

      1. Set up a project in the Google API Console (see https://developers.google.com/identity/protocols/oauth2/openid-connect#appsetup).
        2. -
      2. add an "OAuth Client ID" for a Web Application under "Credentials".
        3. +
      3. Add an "OAuth Client ID" for a Web Application under "Credentials".
      4. Copy the Client ID and Client Secret, and add the following to your synapse config: 
        oidc_providers:
   - idp_id: google
@@ -6499,6 +6463,54 @@ documentation on setting up SiWA.
        
       config:
         email_template: "{{ user.email }}"
        +

        Django OAuth Toolkit

        +

        django-oauth-toolkit is a +Django application providing out of the box all the endpoints, data and logic +needed to add OAuth2 capabilities to your Django projects. It supports +OpenID Connect too.

        +

        Configuration on Django's side:

        +
          +
        1. Add an application: https://example.com/admin/oauth2_provider/application/add/ and choose parameters like this:
          2. +
        +
          +
        • Redirect uris: https://synapse.example.com/_synapse/client/oidc/callback
          • +
        • Client type: Confidential
          • +
        • Authorization grant type: Authorization code
          • +
        • Algorithm: HMAC with SHA-2 256
          • +
        +
          +
        1. +

          You can customize the claims Django gives to synapse (optional):

          +
          + Code sample +
          class CustomOAuth2Validator(OAuth2Validator):
+
+    def get_additional_claims(self, request):
+        return {
+            "sub": request.user.email,
+            "email": request.user.email,
+            "first_name": request.user.first_name,
+            "last_name": request.user.last_name,
+        }
+
          +
          +
          2. +
        +

        Your synapse config is then:

        +
        oidc_providers:
+  - idp_id: django_example
+    idp_name: "Django Example"
+    issuer: "https://example.com/o/"
+    client_id: "your-client-id"  # CHANGE ME
+    client_secret: "your-client-secret"  # CHANGE ME
+    scopes: ["openid"]
+    user_profile_method: "userinfo_endpoint"  # needed because oauth-toolkit does not include user information in the authorization response
+    user_mapping_provider:
+      config:
+        localpart_template: "{{ user.email.split('@')[0] }}"
+        display_name_template: "{{ user.first_name }} {{ user.last_name }}"
+        email_template: "{{ user.email }}"
+

        SSO Mapping Providers

        A mapping provider is a Python class (loaded via a Python module) that works out how to map attributes of a SSO response to Matrix-specific @@ -7691,6 +7703,40 @@ for a list of possible parameters), and a boolean indicating whether the user pe the request is a server admin.

        Modules can modify the request_content (by e.g. adding events to its initial_state), or deny the room's creation by raising a module_api.errors.SynapseError.

        +

        Presence router callbacks

        +

        Presence router callbacks allow module developers to specify additional users (local or remote) +to receive certain presence updates from local users. Presence router callbacks can be +registered using the module API's register_presence_router_callbacks method.

        +

        The available presence router callbacks are:

        +
        async def get_users_for_states(
+    self,
+    state_updates: Iterable["synapse.api.UserPresenceState"],
+) -> Dict[str, Set["synapse.api.UserPresenceState"]]:
+
        +

        Requires get_interested_users to also be registered

        +

        Called when processing updates to the presence state of one or more users. This callback can +be used to instruct the server to forward that presence state to specific users. The module +must return a dictionary that maps from Matrix user IDs (which can be local or remote) to the +UserPresenceState changes that they should be forwarded.

        +

        Synapse will then attempt to send the specified presence updates to each user when possible.

        +
        async def get_interested_users(
+        self, 
+        user_id: str
+) -> Union[Set[str], "synapse.module_api.PRESENCE_ALL_USERS"]
+
        +

        Requires get_users_for_states to also be registered

        +

        Called when determining which users someone should be able to see the presence state of. This +callback should return complementary results to get_users_for_state or the presence information +may not be properly forwarded.

        +

        The callback is given the Matrix user ID for a local user that is requesting presence data and +should return the Matrix user IDs of the users whose presence state they are allowed to +query. The returned users can be local or remote.

        +

        Alternatively the callback can return synapse.module_api.PRESENCE_ALL_USERS +to indicate that the user should receive updates from all known users.

        +

        For example, if the user @alice:example.org is passed to this method, and the Set +{"@bob:example.com", "@charlie:somewhere.org"} is returned, this signifies that Alice +should receive presence updates sent by Bob and Charlie, regardless of whether these users +share a room.

        Porting an existing module that uses the old interface

        In order to port a module that uses Synapse's old module interface, its author needs to:

          @@ -7858,7 +7904,12 @@ action is blocked when at least one of the configured spam checkers flags it.

          The Mjolnir project is a full fledged example using the Synapse spam checking API, including a bot for dynamic configuration.

          -

          Presence Router Module

          +

          +This page of the Synapse documentation is now deprecated. For up to date +documentation on setting up or writing a presence router module, please see +this page. +

          +

          Presence Router Module

          Synapse supports configuring a module that can specify additional users (local or remote) to should receive certain presence updates from local users.

          @@ -8250,6 +8301,7 @@ expressions:

          # Registration/login requests ^/_matrix/client/(api/v1|r0|unstable)/login$ ^/_matrix/client/(r0|unstable)/register$ +^/_matrix/client/unstable/org.matrix.msc3231/register/org.matrix.msc3231.login.registration_token/validity$ # Event sending requests ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/redact @@ -9112,19 +9164,6 @@ server admin.

          To reclaim the disk space and return it to the operating system, you need to run VACUUM FULL; on the database.

          https://www.postgresql.org/docs/current/sql-vacuum.html

          -

          Deprecated: Purge room API

          -

          The old Purge room API is deprecated and will be removed in a future release. -See the new Delete Room API for more details.

          -

          This API will remove all trace of a room from your database.

          -

          All local users must have left the room before it can be removed.

          -

          The API is:

          -
          POST /_synapse/admin/v1/purge_room
-
-{
-    "room_id": "!room:id"
-}
-
          -

          You must authenticate using the access token of an admin user.

          Shared-Secret Registration

          This API allows for the creation of users in an administrative and non-interactive way. This is generally used for bootstrapping a Synapse @@ -9186,6 +9225,243 @@ def generate_mac(nonce, user, password, admin=False, user_type=None): return mac.hexdigest() +

          Registration Tokens

          +

          This API allows you to manage tokens which can be used to authenticate +registration requests, as proposed in MSC3231. +To use it, you will need to enable the registration_requires_token config +option, and authenticate by providing an access_token for a server admin: +see Admin API. +Note that this API is still experimental; not all clients may support it yet.

          +

          Registration token objects

          +

          Most endpoints make use of JSON objects that contain details about tokens. +These objects have the following fields:

          +
            +
          • token: The token which can be used to authenticate registration.
            • +
          • uses_allowed: The number of times the token can be used to complete a +registration before it becomes invalid.
            • +
          • pending: The number of pending uses the token has. When someone uses +the token to authenticate themselves, the pending counter is incremented +so that the token is not used more than the permitted number of times. +When the person completes registration the pending counter is decremented, +and the completed counter is incremented.
            • +
          • completed: The number of times the token has been used to successfully +complete a registration.
            • +
          • expiry_time: The latest time the token is valid. Given as the number of +milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch). +To convert this into a human-readable form you can remove the milliseconds +and use the date command. For example, date -d '@1625394937'.
            • +
          +

          List all tokens

          +

          Lists all tokens and details about them. If the request is successful, the top +level JSON object will have a registration_tokens key which is an array of +registration token objects.

          +
          GET /_synapse/admin/v1/registration_tokens
+
          +

          Optional query parameters:

          +
            +
          • valid: true or false. If true, only valid tokens are returned. +If false, only tokens that have expired or have had all uses exhausted are +returned. If omitted, all tokens are returned regardless of validity.
            • +
          +

          Example:

          +
          GET /_synapse/admin/v1/registration_tokens
+
          +
          200 OK
+
+{
+    "registration_tokens": [
+        {
+            "token": "abcd",
+            "uses_allowed": 3,
+            "pending": 0,
+            "completed": 1,
+            "expiry_time": null
+        },
+        {
+            "token": "pqrs",
+            "uses_allowed": 2,
+            "pending": 1,
+            "completed": 1,
+            "expiry_time": null
+        },
+        {
+            "token": "wxyz",
+            "uses_allowed": null,
+            "pending": 0,
+            "completed": 9,
+            "expiry_time": 1625394937000    // 2021-07-04 10:35:37 UTC
+        }
+    ]
+}
+
          +

          Example using the valid query parameter:

          +
          GET /_synapse/admin/v1/registration_tokens?valid=false
+
          +
          200 OK
+
+{
+    "registration_tokens": [
+        {
+            "token": "pqrs",
+            "uses_allowed": 2,
+            "pending": 1,
+            "completed": 1,
+            "expiry_time": null
+        },
+        {
+            "token": "wxyz",
+            "uses_allowed": null,
+            "pending": 0,
+            "completed": 9,
+            "expiry_time": 1625394937000    // 2021-07-04 10:35:37 UTC
+        }
+    ]
+}
+
          +

          Get one token

          +

          Get details about a single token. If the request is successful, the response +body will be a registration token object.

          +
          GET /_synapse/admin/v1/registration_tokens/<token>
+
          +

          Path parameters:

          +
            +
          • token: The registration token to return details of.
            • +
          +

          Example:

          +
          GET /_synapse/admin/v1/registration_tokens/abcd
+
          +
          200 OK
+
+{
+    "token": "abcd",
+    "uses_allowed": 3,
+    "pending": 0,
+    "completed": 1,
+    "expiry_time": null
+}
+
          +

          Create token

          +

          Create a new registration token. If the request is successful, the newly created +token will be returned as a registration token object in the response body.

          +
          POST /_synapse/admin/v1/registration_tokens/new
+
          +

          The request body must be a JSON object and can contain the following fields:

          +
            +
          • token: The registration token. A string of no more than 64 characters that +consists only of characters matched by the regex [A-Za-z0-9-_]. +Default: randomly generated.
            • +
          • uses_allowed: The integer number of times the token can be used to complete +a registration before it becomes invalid. +Default: null (unlimited uses).
            • +
          • expiry_time: The latest time the token is valid. Given as the number of +milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch). +You could use, for example, date '+%s000' -d 'tomorrow'. +Default: null (token does not expire).
            • +
          • length: The length of the token randomly generated if token is not +specified. Must be between 1 and 64 inclusive. Default: 16.
            • +
          +

          If a field is omitted the default is used.

          +

          Example using defaults:

          +
          POST /_synapse/admin/v1/registration_tokens/new
+
+{}
+
          +
          200 OK
+
+{
+    "token": "0M-9jbkf2t_Tgiw1",
+    "uses_allowed": null,
+    "pending": 0,
+    "completed": 0,
+    "expiry_time": null
+}
+
          +

          Example specifying some fields:

          +
          POST /_synapse/admin/v1/registration_tokens/new
+
+{
+    "token": "defg",
+    "uses_allowed": 1
+}
+
          +
          200 OK
+
+{
+    "token": "defg",
+    "uses_allowed": 1,
+    "pending": 0,
+    "completed": 0,
+    "expiry_time": null
+}
+
          +

          Update token

          +

          Update the number of allowed uses or expiry time of a token. If the request is +successful, the updated token will be returned as a registration token object +in the response body.

          +
          PUT /_synapse/admin/v1/registration_tokens/<token>
+
          +

          Path parameters:

          +
            +
          • token: The registration token to update.
            • +
          +

          The request body must be a JSON object and can contain the following fields:

          +
            +
          • uses_allowed: The integer number of times the token can be used to complete +a registration before it becomes invalid. By setting uses_allowed to 0 +the token can be easily made invalid without deleting it. +If null the token will have an unlimited number of uses.
            • +
          • expiry_time: The latest time the token is valid. Given as the number of +milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch). +If null the token will not expire.
            • +
          +

          If a field is omitted its value is not modified.

          +

          Example:

          +
          PUT /_synapse/admin/v1/registration_tokens/defg
+
+{
+    "expiry_time": 4781243146000    // 2121-07-06 11:05:46 UTC
+}
+
          +
          200 OK
+
+{
+    "token": "defg",
+    "uses_allowed": 1,
+    "pending": 0,
+    "completed": 0,
+    "expiry_time": 4781243146000
+}
+
          +

          Delete token

          +

          Delete a registration token. If the request is successful, the response body +will be an empty JSON object.

          +
          DELETE /_synapse/admin/v1/registration_tokens/<token>
+
          +

          Path parameters:

          +
            +
          • token: The registration token to delete.
            • +
          +

          Example:

          +
          DELETE /_synapse/admin/v1/registration_tokens/wxyz
+
          +
          200 OK
+
+{}
+
          +

          Errors

          +

          If a request fails a "standard error response" will be returned as defined in +the Matrix Client-Server API specification.

          +

          For example, if the token specified in a path parameter does not exist a +404 Not Found error will be returned.

          +
          GET /_synapse/admin/v1/registration_tokens/1234
+
          +
          404 Not Found
+
+{
+    "errcode": "M_NOT_FOUND",
+    "error": "No such registration token: 1234"
+}
+

          Edit Room Membership API

          This API allows an administrator to join an user account with a given user_id to a room with a given room_id_or_alias. You can only modify the membership of @@ -9851,94 +10127,6 @@ ignored in the same way as with PUT /_matrix/client/r0/rooms/{roomId}/send

          Note that server notices must be enabled in homeserver.yaml before this API can be used. See the server notices documentation for more information.

          -

          Deprecated: Shutdown room API

          -

          The old Shutdown room API is deprecated and will be removed in a future release. -See the new Delete Room API for more details.

          -

          Shuts down a room, preventing new joins and moves local users and room aliases automatically -to a new room. The new room will be created with the user specified by the -new_room_user_id parameter as room administrator and will contain a message -explaining what happened. Users invited to the new room will have power level --10 by default, and thus be unable to speak. The old room's power levels will be changed to -disallow any further invites or joins.

          -

          The local server will only have the power to move local user and room aliases to -the new room. Users on other servers will be unaffected.

          -

          API

          -

          You will need to authenticate with an access token for an admin user.

          -

          URL

          -

          POST /_synapse/admin/v1/shutdown_room/{room_id}

          -

          URL Parameters

          -
            -
          • room_id - The ID of the room (e.g !someroom:example.com)
            • -
          -

          JSON Body Parameters

          -
            -
          • new_room_user_id - Required. A string representing the user ID of the user that will admin -the new room that all users in the old room will be moved to.
            • -
          • room_name - Optional. A string representing the name of the room that new users will be -invited to.
            • -
          • message - Optional. A string containing the first message that will be sent as -new_room_user_id in the new room. Ideally this will clearly convey why the -original room was shut down.
            • -
          -

          If not specified, the default value of room_name is "Content Violation -Notification". The default value of message is "Sharing illegal content on -othis server is not permitted and rooms in violation will be blocked."

          -

          Response Parameters

          -
            -
          • kicked_users - An integer number representing the number of users that -were kicked.
            • -
          • failed_to_kick_users - An integer number representing the number of users -that were not kicked.
            • -
          • local_aliases - An array of strings representing the local aliases that were migrated from -the old room to the new.
            • -
          • new_room_id - A string representing the room ID of the new room.
            • -
          -

          Example

          -

          Request:

          -
          POST /_synapse/admin/v1/shutdown_room/!somebadroom%3Aexample.com
-
-{
-    "new_room_user_id": "@someuser:example.com",
-    "room_name": "Content Violation Notification",
-    "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service."
-}
-
          -

          Response:

          -
          {
-    "kicked_users": 5,
-    "failed_to_kick_users": 0,
-    "local_aliases": ["#badroom:example.com", "#evilsaloon:example.com],
-    "new_room_id": "!newroomid:example.com",
-},
-
          -

          Undoing room shutdowns

          -

          Note: This guide may be outdated by the time you read it. By nature of room shutdowns being performed at the database level, -the structure can and does change without notice.

          -

          First, it's important to understand that a room shutdown is very destructive. Undoing a shutdown is not as simple as pretending it -never happened - work has to be done to move forward instead of resetting the past. In fact, in some cases it might not be possible -to recover at all:

          -
            -
          • If the room was invite-only, your users will need to be re-invited.
            • -
          • If the room no longer has any members at all, it'll be impossible to rejoin.
            • -
          • The first user to rejoin will have to do so via an alias on a different server.
            • -
          -

          With all that being said, if you still want to try and recover the room:

          -
            -
          1. For safety reasons, shut down Synapse.
            2. -
          2. In the database, run DELETE FROM blocked_rooms WHERE room_id = '!example:example.org'; -
              -
            • For caution: it's recommended to run this in a transaction: BEGIN; DELETE ...;, verify you got 1 result, then COMMIT;.
              • -
            • The room ID is the same one supplied to the shutdown room API, not the Content Violation room.
              • -
            -
            3. -
          3. Restart Synapse.
            4. -
          -

          You will have to manually handle, if you so choose, the following:

          -
            -
          • Aliases that would have been redirected to the Content Violation room.
            • -
          • Users that would have been booted from the room (and will have been force-joined to the Content Violation room).
            • -
          • Removal of the Content Violation room if desired.
            • -

          Users' media usage statistics

          Returns information about all local media usage of users. Gives the possibility to filter them by time and user.

          @@ -10029,11 +10217,15 @@ server admin: Admin APIKKKK/LLLL/MMMM/NNNN/OOOO - the others will be awaiting the first query to return a response and will simultaneously return with the first request, but with very small processing times.

          -
          -

          Contributing

          -

          Welcome to Synapse

          -

          This document aims to get you started with contributing to this repo!

          - +

          Contributing

          +

          This document aims to get you started with contributing to Synapse!

          1. Who can contribute to Synapse?

          Everyone is welcome to contribute code to matrix.org projects, provided that they are willing to @@ -11320,7 +11470,7 @@ follow a simple 'inbound=outbound' model for contributions: the act of submitting an 'inbound' contribution means that the contributor agrees to license the code under the same terms as the project's overall 'outbound' license - in our case, this is almost always Apache Software License v2 (see -LICENSE).

          +LICENSE).

          2. What do I need?

          The code of Synapse is written in Python 3. To do pretty much anything, you'll need a recent version of Python 3.

          The source code of Synapse is hosted on GitHub. You will also need a recent version of git.

          @@ -11353,19 +11503,27 @@ pip install tox

          6. Pick an issue.

          Fix your favorite problem or perhaps find a Good First Issue to work on.

          -

          7. Turn coffee and documentation into code and documentation!

          -

          Synapse's code style is documented here. Please follow -it, including the conventions for the sample configuration -file.

          -

          There is a growing amount of documentation located in the docs -directory. This documentation is intended primarily for sysadmins running their +

          7. Turn coffee into code and documentation!

          +

          There is a growing amount of documentation located in the +docs +directory, with a rendered version available online. +This documentation is intended primarily for sysadmins running their own Synapse instance, as well as developers interacting externally with -Synapse. docs/dev exists primarily to house documentation for -Synapse developers. docs/admin_api houses documentation +Synapse. +docs/development +exists primarily to house documentation for +Synapse developers. +docs/admin_api houses documentation regarding Synapse's Admin API, which is used mostly by sysadmins and external service developers.

          -

          If you add new files added to either of these folders, please use GitHub-Flavoured -Markdown.

          +

          Synapse's code style is documented here. Please follow +it, including the conventions for the sample configuration +file.

          +

          We welcome improvements and additions to our documentation itself! When +writing new pages, please +build docs to a book +to check that your contributions render correctly. The docs are written in +GitHub-Flavoured Markdown.

          Some documentation also exists in Synapse's GitHub Wiki, although this is primarily contributed to by community authors.

          @@ -11607,7 +11765,7 @@ flag to git commit, which uses the name and email set in your

          By now, you know the drill!

          Notes for maintainers on merging PRs etc

          There are some notes for those with commit access to the project on how we -manage git here.

          +manage git here.

          Conclusion

          That's it! Matrix is a very open and collaborative project as you might expect given our obsession with open communication. If we're going to successfully @@ -12535,7 +12693,7 @@ connection errors.

          received for each stream so that on reconneciton it can start streaming from the correct place. Note: not all RDATA have valid tokens due to batching. See RdataCommand for more details.

          -

          Example

          +

          Example

          An example iteraction is shown below. Each line is prefixed with '>' or '<' to indicate which side is sending, these are not included on the wire:

          @@ -12831,7 +12989,7 @@ graph), and one where we remove redundant links (the transitive reduction of the links graph) e.g. if we have chains C3 -> C2 -> C1 then the link C3 -> C1 would not be stored. Synapse uses the former implementations so that it doesn't need to recurse to test reachability between chains.

          -

          Example

          +

          Example

          An example auth graph would look like the following, where chains have been formed based on type/state_key and are denoted by colour and are labelled with (chain ID, sequence number). Links are denoted by the arrows (links in grey -- cgit 1.5.1