synapse

Synapse

  • Canonical IS DevOps
Channel Revision Published Runs on
latest/stable 426 20 Sep 2024
Ubuntu 22.04
latest/edge 523 07 Jan 2025
Ubuntu 22.04
2/edge 636 Today
Ubuntu 22.04
1/stable 303 30 Jul 2024
Ubuntu 22.04
1/edge 620 27 Mar 2025
Ubuntu 22.04
juju deploy synapse
Show information

Learn to deploy on juju >

Platform:

charms.synapse.v1.matrix_auth

Library to manage the plugin integrations with the Synapse charm.

This library contains the Requires and Provides classes for handling the integration between an application and a charm providing the matrix_plugin integration.

Summary
Provider

Handles requests from requirers.

  • Observes: relation_changed → Triggers workload reconciliation. relation_departed → Triggers workload reconciliation.
  • During reconciliation: If the unit is the leader, update_relation_data is called. If registration_secrets (IRC registration encrypted content) are present, the required files are created, and Synapse configuration is updated.
Requirer (IRC Bridge, Bidirectional)

Requests data (uses homeserver URL, registration shared secret and encryption key) from the provider and updates its configuration accordingly.

  • Observes: matrix_auth_request_processed (emitted after valid relation_changed) → Triggers workload reconciliation.
  • During reconciliation: Configures IRC using data from get_remote_relation_data. Updates relation data with IRC registration, calling update_relation_data.
Requirer (Maubot, Unidirectional)

Requests data (uses homeserver URL) from the provider but does not send registration data back.

Observes: matrix_auth_request_processed (emitted after valid relation_changed) → Triggers workload reconciliation.

Why setting a encryption key?

In a CMR (Cross-Model Relation), the provider cannot read a secret created by the requirer. To securely share the IRC appservice configuration, the provider generates an encryption key that both sides use: the requirer encrypts the content, and the provider decrypts it.

This key is generated once by the provider and stored as a secret. The same applies to the registration shared secret, as both remain unchanged throughout Synapse's lifecycle.

When the relation is removed, if there are no observers for the secret, it is deleted.

Requirer Charm

from charms.synapse.v0.matrix_auth import MatrixAuthRequires

class MatrixAuthRequirerCharm(ops.CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.plugin_auth = MatrixAuthRequires(self)
        self.framework.observe(self.matrix_auth.on.matrix_auth_request_processed, self._handler)
        ...

    def _handler(self, events: MatrixAuthRequestProcessed) -> None:
        ...

As shown above, the library provides a custom event to handle the scenario in which a matrix authentication (homeserver and shared secret) has been added or updated.

The MatrixAuthRequires provides an update_relation_data method to update the relation data by passing a MatrixAuthRequirerData data object, requesting a new authentication.

Provider Charm

Following the previous example, this is an example of the provider charm.

from charms.synapse.v0.matrix_auth import MatrixAuthProvides

class MatrixAuthProviderCharm(ops.CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.plugin_auth = MatrixAuthProvides(self)
        ...

The MatrixAuthProvides object wraps the list of relations into a relations property and provides an update_relation_data method to update the relation data by passing a MatrixAuthRelationData data object.

class MatrixAuthProviderCharm(ops.CharmBase):
    ...

    def _on_config_changed(self, _) -> None:
        for relation in self.model.relations[self.plugin_auth.relation_name]:
            self.plugin_auth.update_relation_data(relation, self._get_matrix_auth_data())

Index

def encrypt_string(
    key: bytes,
    plaintext: SecretStr
)

Encrypt a string using Fernet.

Arguments

key

encryption key in bytes.

plaintext

text to encrypt.

Returns

encrypted text.

def decrypt_string(
    key: bytes,
    ciphertext: str
)

Decrypt a string using Fernet.

Arguments

key

encryption key in bytes.

ciphertext

encrypted text.

Returns

decrypted text.

class MatrixAuthProviderData

Represent the MatrixAuth provider data.

Attributes

homeserver
the homeserver URL.
shared_secret
the Matrix shared secret.
shared_secret_id
the shared secret Juju secret ID.
encryption_key_secret_id
encryption key secret ID.

Methods

MatrixAuthProviderData. set_shared_secret_id( self , model , relation )

Store the Matrix shared secret as a Juju secret.

Arguments

model

the Juju model

relation

relation to grant access to the secrets to.

Description

If the secret exists, grant access to the relation. If not found, create one.

MatrixAuthProviderData. set_encryption_key_secret_id( self , model , relation )

Store the encryption key to encrypt/decrypt appservice registrations.

Arguments

model

the Juju model

relation

relation to grant access to the secrets to.

MatrixAuthProviderData. get_shared_secret( cls , model , shared_secret_id )

Retrieve the shared secret corresponding to the shared_secret_id.

Arguments

model

the Juju model.

shared_secret_id

the secret ID for the shared secret.

Returns

the shared secret or None if not found.

MatrixAuthProviderData. to_relation_data( self , model , relation )

Convert an instance of MatrixAuthProviderData to the relation representation.

Arguments

model

the Juju model.

relation

relation to grant access to the secrets to.

Returns

Dict containing the representation.

MatrixAuthProviderData. from_relation( cls , model , relation )

Initialize a new instance of the MatrixAuthProviderData class from the relation.

Arguments

relation

the relation.

Returns

A MatrixAuthProviderData instance.

class MatrixAuthRequirerData

Represent the MatrixAuth requirer data.

Attributes

registration
a generated app registration file.

Methods

MatrixAuthRequirerData. get_encryption_key_secret( cls , model , encryption_key_secret_id )

Retrieve the encryption key secret corresponding to the encryption_key_secret_id.

Arguments

model

the Juju model.

encryption_key_secret_id

the secret ID for the encryption key secret.

Returns

the encryption key secret as bytes or None if not found.

MatrixAuthRequirerData. to_relation_data( self , model , relation )

Convert an instance of MatrixAuthRequirerData to the relation representation.

Description

Args: model: the Juju model. relation: relation to grant access to the secrets to.

Returns: Dict containing the representation.

Raises: ValueError if encryption key not found.

MatrixAuthRequirerData. from_relation( cls , model , relation )

Get a MatrixAuthRequirerData from the relation data.

Arguments

model

the Juju model.

relation

the relation.

Returns

the relation data and the processed entries for it.

class MatrixAuthRequestProcessed

Description

MatrixAuth event emitted when a new request is processed. None

Methods

MatrixAuthRequestProcessed. get_matrix_auth_provider_relation_data( self )

Get a MatrixAuthProviderData for the relation data.

Returns

the MatrixAuthProviderData for the relation data.

class MatrixAuthRequestReceived

Description

MatrixAuth event emitted when a new request is made. None

class MatrixAuthRequiresEvents

MatrixAuth requirer events.

Attributes

matrix_auth_request_processed
the MatrixAuthRequestProcessed.

Description

This class defines the events that a MatrixAuth requirer can emit.

class MatrixAuthProvidesEvents

MatrixAuth provider events.

Attributes

matrix_auth_request_received
the MatrixAuthRequestReceived.

Description

This class defines the events that a MatrixAuth provider can emit.

class MatrixAuthProvides

Provider side of the MatrixAuth relation.

Attributes

on
events the provider can emit.

Methods

MatrixAuthProvides. __init__( self , charm , relation_name: str )

Construct.

Arguments

charm

the provider charm.

relation_name

the relation name.

MatrixAuthProvides. get_remote_relation_data( self )

Retrieve the remote relation data.

Returns

MatrixAuthRequirerData

the relation data.

MatrixAuthProvides. update_relation_data( self , relation , matrix_auth_provider_data: MatrixAuthProviderData )

Arguments

relation

the relation for which to update the data.

matrix_auth_provider_data

a MatrixAuthProviderData instance wrapping the data to be updated.

Description

Update the relation data. Since provider values should not be changed while instance exists, this method updates relation data only if invalid or empty.

class MatrixAuthRequires

Requirer side of the MatrixAuth requires relation.

Attributes

on
events the provider can emit.

Methods

MatrixAuthRequires. __init__( self , charm , relation_name: str )

Construct.

Arguments

charm

the provider charm.

relation_name

the relation name.

MatrixAuthRequires. get_remote_relation_data( self )

Retrieve the remote relation data.

Returns

MatrixAuthProviderData

the relation data.

MatrixAuthRequires. update_relation_data( self , relation , matrix_auth_requirer_data: MatrixAuthRequirerData )

Update the relation data.

Arguments

relation

the relation for which to update the data.

matrix_auth_requirer_data

MatrixAuthRequirerData wrapping the data to be updated.