matrix-synapse 1.143.0__cp310-abi3-manylinux_2_28_aarch64.whl

synapse/util/manhole.py

@@ -0,0 +1,191 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright 2016 OpenMarket Ltd
+# Copyright (C) 2023 New Vector, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl-3.0.html>.
+#
+# Originally licensed under the Apache License, Version 2.0:
+# <http://www.apache.org/licenses/LICENSE-2.0>.
+#
+# [This file includes modifications made by New Vector Limited]
+#
+#
+import inspect
+import sys
+import traceback
+from typing import Any
+
+from twisted.conch import manhole_ssh
+from twisted.conch.insults import insults
+from twisted.conch.manhole import ColoredManhole, ManholeInterpreter
+from twisted.conch.ssh.keys import Key
+from twisted.cred import checkers, portal
+from twisted.internet import defer
+from twisted.internet.protocol import ServerFactory
+
+from synapse.config.server import ManholeConfig
+
+PUBLIC_KEY = (
+    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHhGATaW4KhE23+7nrH4jFx3yLq9OjaEs5"
+    "XALqeK+7385NlLja3DE/DO9mGhnd9+bAy39EKT3sTV6+WXQ4yD0TvEEyUEMtjWkSEm6U32+C"
+    "DaS3TW/vPBUMeJQwq+Ydcif1UlnpXrDDTamD0AU9VaEvHq+3HAkipqn0TGpKON6aqk4vauDx"
+    "oXSsV5TXBVrxP/y7HpMOpU4GUWsaaacBTKKNnUaQB4UflvydaPJUuwdaCUJGTMjbhWrjVfK+"
+    "jslseSPxU6XvrkZMyCr4znxvuDxjMk1RGIdO7v+rbBMLEgqtSMNqJbYeVCnj2CFgc3fcTcld"
+    "X2uOJDrJb/WRlHulthCh"
+)
+
+PRIVATE_KEY = """-----BEGIN RSA PRIVATE KEY-----
+MIIEpQIBAAKCAQEAx4RgE2luCoRNt/u56x+Ixcd8i6vTo2hLOVwC6nivu9/OTZS4
+2twxPwzvZhoZ3ffmwMt/RCk97E1evll0OMg9E7xBMlBDLY1pEhJulN9vgg2kt01v
+7zwVDHiUMKvmHXIn9VJZ6V6ww02pg9AFPVWhLx6vtxwJIqap9ExqSjjemqpOL2rg
+8aF0rFeU1wVa8T/8ux6TDqVOBlFrGmmnAUyijZ1GkAeFH5b8nWjyVLsHWglCRkzI
+24Vq41Xyvo7JbHkj8VOl765GTMgq+M58b7g8YzJNURiHTu7/q2wTCxIKrUjDaiW2
+HlQp49ghYHN33E3JXV9rjiQ6yW/1kZR7pbYQoQIDAQABAoIBAQC8KJ0q8Wzzwh5B
+esa1dQHZ8+4DEsL/Amae66VcVwD0X3cCN1W2IZ7X5W0Ij2kBqr8V51RYhcR+S+Ek
+BtzSiBUBvbKGrqcMGKaUgomDIMzai99hd0gvCCyZnEW1OQhFkNkaRNXCfqiZJ27M
+fqvSUiU2eOwh9fCvmxoA6Of8o3FbzcJ+1GMcobWRllDtLmj6lgVbDzuA+0jC5daB
+9Tj1pBzu3wn3ufxiS+gBnJ+7NcXH3E73lqCcPa2ufbZ1haxfiGCnRIhFXuQDgxFX
+vKdEfDgtvas6r1ahGbc+b/q8E8fZT7cABuIU4yfOORK+MhpyWbvoyyzuVGKj3PKt
+KSPJu5CZAoGBAOkoJfAVyYteqKcmGTanGqQnAY43CaYf6GdSPX/jg+JmKZg0zqMC
+jWZUtPb93i+jnOInbrnuHOiHAxI8wmhEPed28H2lC/LU8PzlqFkZXKFZ4vLOhhRB
+/HeHCFIDosPFlohWi3b+GAjD7sXgnIuGmnXWe2ea/TS3yersifDEoKKjAoGBANsQ
+gJX2cJv1c3jhdgcs8vAt5zIOKcCLTOr/QPmVf/kxjNgndswcKHwsxE/voTO9q+TF
+v/6yCSTxAdjuKz1oIYWgi/dZo82bBKWxNRpgrGviU3/zwxiHlyIXUhzQu78q3VS/
+7S1XVbc7qMV++XkYKHPVD+nVG/gGzFxumX7MLXfrAoGBAJit9cn2OnjNj9uFE1W6
+r7N254ndeLAUjPe73xH0RtTm2a4WRopwjW/JYIetTuYbWgyujc+robqTTuuOZjAp
+H/CG7o0Ym251CypQqaFO/l2aowclPp/dZhpPjp9GSjuxFBZLtiBB3DNBOwbRQzIK
+/vLTdRQvZkgzYkI4i0vjNt3JAoGBANP8HSKBLymMlShlrSx2b8TB9tc2Y2riohVJ
+2ttqs0M2kt/dGJWdrgOz4mikL+983Olt/0P9juHDoxEEMK2kpcPEv40lnmBpYU7h
+s8yJvnBLvJe2EJYdJ8AipyAhUX1FgpbvfxmASP8eaUxsegeXvBWTGWojAoS6N2o+
+0KSl+l3vAoGAFqm0gO9f/Q1Se60YQd4l2PZeMnJFv0slpgHHUwegmd6wJhOD7zJ1
+CkZcXwiv7Nog7AI9qKJEUXLjoqL+vJskBzSOqU3tcd670YQMi1aXSXJqYE202K7o
+EddTrx3TNpr1D5m/f+6mnXWrc8u9y1+GNx9yz889xMjIBTBI9KqaaOs=
+-----END RSA PRIVATE KEY-----"""
+
+
+def manhole(settings: ManholeConfig, globals: dict[str, Any]) -> ServerFactory:
+    """Starts a ssh listener with password authentication using
+    the given username and password. Clients connecting to the ssh
+    listener will find themselves in a colored python shell with
+    the supplied globals.
+
+    Args:
+        username: The username ssh clients should auth with.
+        password: The password ssh clients should auth with.
+        globals: The variables to expose in the shell.
+
+    Returns:
+        A factory to pass to ``listenTCP``
+    """
+    username = settings.username
+    password = settings.password.encode("ascii")
+    priv_key = settings.priv_key
+    if priv_key is None:
+        priv_key = Key.fromString(PRIVATE_KEY)
+    pub_key = settings.pub_key
+    if pub_key is None:
+        pub_key = Key.fromString(PUBLIC_KEY)
+
+    checker = checkers.InMemoryUsernamePasswordDatabaseDontUse(**{username: password})
+
+    rlm = manhole_ssh.TerminalRealm()
+    # mypy ignored here because:
+    # - can't deduce types of lambdas
+    # - variable is Type[ServerProtocol], expr is Callable[[], ServerProtocol]
+    rlm.chainedProtocolFactory = lambda: insults.ServerProtocol(  # type: ignore[misc,assignment]
+        SynapseManhole, dict(globals, __name__="__console__")
+    )
+
+    # type-ignore: This is an error in Twisted's annotations. See
+    # https://github.com/twisted/twisted/issues/11812 and /11813 .
+    factory = manhole_ssh.ConchFactory(portal.Portal(rlm, [checker]))  # type: ignore[arg-type]
+
+    # conch has the wrong type on these dicts (says bytes to bytes,
+    # should be bytes to Keys judging by how it's used).
+    factory.privateKeys[b"ssh-rsa"] = priv_key  # type: ignore[assignment]
+    factory.publicKeys[b"ssh-rsa"] = pub_key  # type: ignore[assignment]
+
+    # ConchFactory is a Factory, not a ServerFactory, but they are identical.
+    return factory  # type: ignore[return-value]
+
+
+class SynapseManhole(ColoredManhole):
+    """Overrides connectionMade to create our own ManholeInterpreter"""
+
+    def connectionMade(self) -> None:
+        super().connectionMade()
+
+        # replace the manhole interpreter with our own impl
+        self.interpreter = SynapseManholeInterpreter(self, self.namespace)
+
+        # this would also be a good place to add more keyHandlers.
+
+
+class SynapseManholeInterpreter(ManholeInterpreter):
+    def showsyntaxerror(self, filename: str | None = None) -> None:
+        """Display the syntax error that just occurred.
+
+        Overrides the base implementation, ignoring sys.excepthook. We always want
+        any syntax errors to be sent to the terminal, rather than sentry.
+        """
+        type, value, tb = sys.exc_info()
+        assert value is not None
+        sys.last_type = type
+        sys.last_value = value
+        sys.last_traceback = tb
+        if filename and type is SyntaxError:
+            # Work hard to stuff the correct filename in the exception
+            try:
+                msg, (dummy_filename, lineno, offset, line) = value.args
+            except ValueError:
+                # Not the format we expect; leave it alone
+                pass
+            else:
+                # Stuff in the right filename
+                value = SyntaxError(msg, (filename, lineno, offset, line))
+                sys.last_value = value
+        lines = traceback.format_exception_only(type, value)
+        self.write("".join(lines))
+
+    def showtraceback(self) -> None:
+        """Display the exception that just occurred.
+
+        Overrides the base implementation, ignoring sys.excepthook. We always want
+        any syntax errors to be sent to the terminal, rather than sentry.
+        """
+        sys.last_type, sys.last_value, last_tb = ei = sys.exc_info()
+        sys.last_traceback = last_tb
+        assert last_tb is not None
+
+        try:
+            # We remove the first stack item because it is our own code.
+            lines = traceback.format_exception(ei[0], ei[1], last_tb.tb_next)
+            self.write("".join(lines))
+        finally:
+            # On the line below, last_tb and ei appear to be dead.
+            # It's unclear whether there is a reason behind this line.
+            # It conceivably could be because an exception raised in this block
+            # will keep the local frame (containing these local variables) around.
+            # This was adapted taken from CPython's Lib/code.py; see here:
+            # https://github.com/python/cpython/blob/4dc4300c686f543d504ab6fa9fe600eaf11bb695/Lib/code.py#L131-L150
+            last_tb = ei = None  # type: ignore
+
+    def displayhook(self, obj: Any) -> None:
+        """
+        We override the displayhook so that we automatically convert coroutines
+        into Deferreds. (Our superclass' displayhook will take care of the rest,
+        by displaying the Deferred if it's ready, or registering a callback
+        if it's not).
+        """
+        if inspect.iscoroutine(obj):
+            super().displayhook(defer.ensureDeferred(obj))
+        else:
+            super().displayhook(obj)

synapse/util/metrics.py

@@ -0,0 +1,339 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright 2016 OpenMarket Ltd
+# Copyright (C) 2023 New Vector, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl-3.0.html>.
+#
+# Originally licensed under the Apache License, Version 2.0:
+# <http://www.apache.org/licenses/LICENSE-2.0>.
+#
+# [This file includes modifications made by New Vector Limited]
+#
+#
+
+import logging
+from functools import wraps
+from types import TracebackType
+from typing import (
+    Awaitable,
+    Callable,
+    Generator,
+    Protocol,
+    TypeVar,
+)
+
+from prometheus_client import CollectorRegistry, Counter, Metric
+from typing_extensions import Concatenate, ParamSpec
+
+from synapse.logging.context import (
+    ContextResourceUsage,
+    LoggingContext,
+    current_context,
+)
+from synapse.metrics import SERVER_NAME_LABEL, InFlightGauge
+from synapse.util.clock import Clock
+
+logger = logging.getLogger(__name__)
+
+# Metrics to see the number of and how much time is spend in various blocks of code.
+#
+block_counter = Counter(
+    "synapse_util_metrics_block_count",
+    documentation="The number of times this block has been called.",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""The number of times this block has been called."""
+
+block_timer = Counter(
+    "synapse_util_metrics_block_time_seconds",
+    documentation="The cumulative time spent executing this block across all calls, in seconds.",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""The cumulative time spent executing this block across all calls, in seconds."""
+
+block_ru_utime = Counter(
+    "synapse_util_metrics_block_ru_utime_seconds",
+    documentation="Resource usage: user CPU time in seconds used in this block",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""Resource usage: user CPU time in seconds used in this block"""
+
+block_ru_stime = Counter(
+    "synapse_util_metrics_block_ru_stime_seconds",
+    documentation="Resource usage: system CPU time in seconds used in this block",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""Resource usage: system CPU time in seconds used in this block"""
+
+block_db_txn_count = Counter(
+    "synapse_util_metrics_block_db_txn_count",
+    documentation="Number of database transactions completed in this block",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""Number of database transactions completed in this block"""
+
+# seconds spent waiting for db txns, excluding scheduling time, in this block
+block_db_txn_duration = Counter(
+    "synapse_util_metrics_block_db_txn_duration_seconds",
+    documentation="Seconds spent waiting for database txns, excluding scheduling time, in this block",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""Seconds spent waiting for database txns, excluding scheduling time, in this block"""
+
+# seconds spent waiting for a db connection, in this block
+block_db_sched_duration = Counter(
+    "synapse_util_metrics_block_db_sched_duration_seconds",
+    documentation="Seconds spent waiting for a db connection, in this block",
+    labelnames=["block_name", SERVER_NAME_LABEL],
+)
+"""Seconds spent waiting for a db connection, in this block"""
+
+
+# This is dynamically created in InFlightGauge.__init__.
+class _BlockInFlightMetric(Protocol):
+    """
+    Sub-metrics used for the `InFlightGauge` for blocks.
+    """
+
+    real_time_max: float
+    """The longest observed duration of any single execution of this block, in seconds."""
+    real_time_sum: float
+    """The cumulative time spent executing this block across all calls, in seconds."""
+
+
+in_flight: InFlightGauge[_BlockInFlightMetric] = InFlightGauge(
+    "synapse_util_metrics_block_in_flight",
+    desc="Tracks the number of blocks currently active",
+    labels=["block_name", SERVER_NAME_LABEL],
+    # Matches the fields in the `_BlockInFlightMetric`
+    sub_metrics=["real_time_max", "real_time_sum"],
+)
+"""Tracks the number of blocks currently active"""
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class HasClockAndServerName(Protocol):
+    clock: Clock
+    """
+    Used to measure functions
+    """
+    server_name: str
+    """
+    The homeserver name that this Measure is associated with (used to label the metric)
+    (`hs.hostname`).
+    """
+
+
+def measure_func(
+    name: str | None = None,
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    """Decorate an async method with a `Measure` context manager.
+
+    The Measure is created using `self.clock` and `self.server_name; it should only be
+    used to decorate methods in classes defining an instance-level `clock` and
+    `server_name` attributes.
+
+    Usage:
+
+    @measure_func()
+    async def foo(...):
+        ...
+
+    Which is analogous to:
+
+    async def foo(...):
+        with Measure(...):
+            ...
+
+    Args:
+        name: The name of the metric to report (the block name) (used to label the
+            metric). Defaults to the name of the decorated function.
+    """
+
+    def wrapper(
+        func: Callable[Concatenate[HasClockAndServerName, P], Awaitable[R]],
+    ) -> Callable[P, Awaitable[R]]:
+        block_name = func.__name__ if name is None else name
+
+        @wraps(func)
+        async def measured_func(
+            self: HasClockAndServerName, *args: P.args, **kwargs: P.kwargs
+        ) -> R:
+            with Measure(self.clock, name=block_name, server_name=self.server_name):
+                r = await func(self, *args, **kwargs)
+            return r
+
+        # There are some shenanigans here, because we're decorating a method but
+        # explicitly making use of the `self` parameter. The key thing here is that the
+        # return type within the return type for `measure_func` itself describes how the
+        # decorated function will be called.
+        return measured_func  # type: ignore[return-value]
+
+    return wrapper  # type: ignore[return-value]
+
+
+class Measure:
+    __slots__ = [
+        "clock",
+        "name",
+        "server_name",
+        "_logging_context",
+        "start",
+    ]
+
+    def __init__(self, clock: Clock, *, name: str, server_name: str) -> None:
+        """
+        Args:
+            clock: An object with a "time()" method, which returns the current
+                time in seconds.
+            name: The name of the metric to report (the block name) (used to label the
+                metric).
+            server_name: The homeserver name that this Measure is associated with (used to
+                label the metric) (`hs.hostname`).
+        """
+        self.clock = clock
+        self.name = name
+        self.server_name = server_name
+        curr_context = current_context()
+        if not curr_context:
+            logger.warning(
+                "Starting metrics collection %r from sentinel context: metrics will be lost",
+                name,
+            )
+            parent_context = None
+        else:
+            assert isinstance(curr_context, LoggingContext)
+            parent_context = curr_context
+        self._logging_context = LoggingContext(
+            name=str(curr_context),
+            server_name=self.server_name,
+            parent_context=parent_context,
+        )
+        self.start: float | None = None
+
+    def __enter__(self) -> "Measure":
+        if self.start is not None:
+            raise RuntimeError("Measure() objects cannot be re-used")
+
+        self.start = self.clock.time()
+        self._logging_context.__enter__()
+        in_flight.register((self.name, self.server_name), self._update_in_flight)
+
+        logger.debug("Entering block %s", self.name)
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self.start is None:
+            raise RuntimeError("Measure() block exited without being entered")
+
+        logger.debug("Exiting block %s", self.name)
+
+        duration = self.clock.time() - self.start
+        usage = self.get_resource_usage()
+
+        in_flight.unregister((self.name, self.server_name), self._update_in_flight)
+        self._logging_context.__exit__(exc_type, exc_val, exc_tb)
+
+        try:
+            labels = {"block_name": self.name, SERVER_NAME_LABEL: self.server_name}
+            block_counter.labels(**labels).inc()
+            block_timer.labels(**labels).inc(duration)
+            block_ru_utime.labels(**labels).inc(usage.ru_utime)
+            block_ru_stime.labels(**labels).inc(usage.ru_stime)
+            block_db_txn_count.labels(**labels).inc(usage.db_txn_count)
+            block_db_txn_duration.labels(**labels).inc(usage.db_txn_duration_sec)
+            block_db_sched_duration.labels(**labels).inc(usage.db_sched_duration_sec)
+        except ValueError as exc:
+            logger.warning("Failed to save metrics! Usage: %s Error: %s", usage, exc)
+
+    def get_resource_usage(self) -> ContextResourceUsage:
+        """Get the resources used within this Measure block
+
+        If the Measure block is still active, returns the resource usage so far.
+        """
+        return self._logging_context.get_resource_usage()
+
+    def _update_in_flight(self, metrics: _BlockInFlightMetric) -> None:
+        """Gets called when processing in flight metrics"""
+        assert self.start is not None
+        duration = self.clock.time() - self.start
+
+        metrics.real_time_max = max(metrics.real_time_max, duration)
+        metrics.real_time_sum += duration
+
+        # TODO: Add other in flight metrics.
+
+
+class DynamicCollectorRegistry(CollectorRegistry):
+    """
+    Custom Prometheus Collector registry that calls a hook first, allowing you
+    to update metrics on-demand.
+
+    Don't forget to register this registry with the main registry!
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._server_name_to_pre_update_hooks: dict[
+            str, dict[str, Callable[[], None]]
+        ] = {}
+        """
+        Mapping of server name to a mapping of metric name to metric pre-update
+        hook
+        """
+
+    def collect(self) -> Generator[Metric, None, None]:
+        """
+        Collects metrics, calling pre-update hooks first.
+        """
+
+        for pre_update_hooks in self._server_name_to_pre_update_hooks.values():
+            for pre_update_hook in pre_update_hooks.values():
+                pre_update_hook()
+
+        yield from super().collect()
+
+    def register_hook(
+        self, server_name: str, metric_name: str, hook: Callable[[], None]
+    ) -> None:
+        """
+        Registers a hook that is called before metric collection.
+        """
+
+        server_hooks = self._server_name_to_pre_update_hooks.setdefault(server_name, {})
+        if server_hooks.get(metric_name) is not None:
+            # TODO: This should be an `assert` since registering the same metric name
+            # multiple times will clobber the old metric.
+            #
+            # We currently rely on this behaviour in a few places:
+            #  - We instantiate multiple `SyncRestServlet`, one per listener, and in the
+            #   `__init__` we setup a new `LruCache`.
+            #  - We instantiate multiple `ApplicationService` (one per configured
+            #    application service) which use the `@cached` decorator on some methods.
+            #
+            # Once the above behaviour is changed, this should be changed to an `assert`.
+            logger.error(
+                "Metric named %s already registered for server %s",
+                metric_name,
+                server_name,
+            )
+        server_hooks[metric_name] = hook
+
+    def unregister_hooks_for_homeserver(self, server_name: str) -> None:
+        self._server_name_to_pre_update_hooks.pop(server_name, None)

synapse/util/module_loader.py

@@ -0,0 +1,116 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright (C) 2023 New Vector, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl-3.0.html>.
+#
+# Originally licensed under the Apache License, Version 2.0:
+# <http://www.apache.org/licenses/LICENSE-2.0>.
+#
+# [This file includes modifications made by New Vector Limited]
+#
+#
+
+import importlib
+import importlib.util
+from types import ModuleType
+from typing import Any
+
+import jsonschema
+
+from synapse.config._base import ConfigError
+from synapse.config._util import json_error_to_config_error
+from synapse.types import StrSequence
+
+
+def load_module(provider: dict, config_path: StrSequence) -> tuple[type, Any]:
+    """Loads a synapse module with its config
+
+    Args:
+        provider: a dict with keys 'module' (the module name) and 'config'
+           (the config dict).
+        config_path: the path within the config file. This will be used as a basis
+           for any error message.
+
+    Returns
+        Tuple of (provider class, parsed config object)
+    """
+
+    modulename = provider.get("module")
+    if not isinstance(modulename, str):
+        raise ConfigError("expected a string", path=tuple(config_path) + ("module",))
+
+    # We need to import the module, and then pick the class out of
+    # that, so we split based on the last dot.
+    module_name, clz = modulename.rsplit(".", 1)
+    module = importlib.import_module(module_name)
+    provider_class = getattr(module, clz)
+
+    # Load the module config. If None, pass an empty dictionary instead
+    module_config = provider.get("config") or {}
+    if hasattr(provider_class, "parse_config"):
+        try:
+            provider_config = provider_class.parse_config(module_config)
+        except jsonschema.ValidationError as e:
+            raise json_error_to_config_error(e, tuple(config_path) + ("config",))
+        except ConfigError as e:
+            raise _wrap_config_error(
+                "Failed to parse config for module %r" % (modulename,),
+                prefix=tuple(config_path) + ("config",),
+                e=e,
+            )
+        except Exception as e:
+            raise ConfigError(
+                "Failed to parse config for module %r" % (modulename,),
+                path=tuple(config_path) + ("config",),
+            ) from e
+    else:
+        provider_config = module_config
+
+    return provider_class, provider_config
+
+
+def load_python_module(location: str) -> ModuleType:
+    """Load a python module, and return a reference to its global namespace
+
+    Args:
+        location: path to the module
+
+    Returns:
+        python module object
+    """
+    spec = importlib.util.spec_from_file_location(location, location)
+    if spec is None:
+        raise Exception("Unable to load module at %s" % (location,))
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)  # type: ignore
+    return mod
+
+
+def _wrap_config_error(msg: str, prefix: StrSequence, e: ConfigError) -> "ConfigError":
+    """Wrap a relative ConfigError with a new path
+
+    This is useful when we have a ConfigError with a relative path due to a problem
+    parsing part of the config, and we now need to set it in context.
+    """
+    path = prefix
+    if e.path:
+        path = tuple(prefix) + tuple(e.path)
+
+    e1 = ConfigError(msg, path)
+
+    # ideally we would set the 'cause' of the new exception to the original exception;
+    # however now that we have merged the path into our own, the stringification of
+    # e will be incorrect, so instead we create a new exception with just the "msg"
+    # part.
+
+    e1.__cause__ = Exception(e.msg)
+    e1.__cause__.__cause__ = e.__cause__
+    return e1

synapse/util/msisdn.py

@@ -0,0 +1,51 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright 2017 Vector Creations Ltd
+# Copyright (C) 2023 New Vector, Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl-3.0.html>.
+#
+# Originally licensed under the Apache License, Version 2.0:
+# <http://www.apache.org/licenses/LICENSE-2.0>.
+#
+# [This file includes modifications made by New Vector Limited]
+#
+#
+
+import phonenumbers
+
+from synapse.api.errors import Codes, SynapseError
+
+
+def phone_number_to_msisdn(country: str, number: str) -> str:
+    """
+    Takes an ISO-3166-1 2 letter country code and phone number and
+    returns an msisdn representing the canonical version of that
+    phone number.
+
+    As an example, if `country` is "GB" and `number` is "7470674927", this
+    function will return "447470674927".
+
+    Args:
+        country: ISO-3166-1 2 letter country code
+        number: Phone number in a national or international format
+
+    Returns:
+        The canonical form of the phone number, as an msisdn.
+    Raises:
+        SynapseError if the number could not be parsed.
+    """
+    try:
+        phoneNumber = phonenumbers.parse(number, country)
+    except phonenumbers.NumberParseException:
+        raise SynapseError(400, "Unable to parse phone number", Codes.INVALID_PARAM)
+    return phonenumbers.format_number(phoneNumber, phonenumbers.PhoneNumberFormat.E164)[
+        1:
+    ]