Federation outbound proxy

synapse/config/workers.py

@@ -162,6 +162,10 @@ class OutboundFederationRestrictedTo:
     locations: List[InstanceLocationConfig] = attr.Factory(list)
 
     def __contains__(self, instance: str) -> bool:
+        # It feels a bit dirty to return `True` if `instances` is `None`, but it makes
+        # sense in downstream usage in the sense that if
+        # `outbound_federation_restricted_to` is not configured, then any instance can
+        # talk to federation (no restrictions so always return `True`).
         return self.instances is None or instance in self.instances
 
 

synapse/http/matrixfederationclient.py

@@ -400,6 +400,7 @@ def __init__(
             hs.config.worker.outbound_federation_restricted_to
         )
         if hs.get_instance_name() in outbound_federation_restricted_to:
+            # Talk to federation directly
             federation_agent: IAgent = MatrixFederationAgent(
                 self.reactor,
                 tls_client_options_factory,
@@ -408,6 +409,8 @@ def __init__(
                 hs.config.server.federation_ip_range_blocklist,
             )
         else:
+            # We need to talk to federation via the proxy via one of the configured
+            # locations
             federation_proxies = outbound_federation_restricted_to.locations
             federation_agent = ProxyAgent(
                 self.reactor,
@@ -426,6 +429,8 @@ def __init__(
         self.clock = hs.get_clock()
         self._store = hs.get_datastores().main
         self.version_string_bytes = hs.version_string.encode("ascii")
+        # This is an arbitrary magic value timeout but make sure that if this is
+        # changed, the timeout in `ProxyResource` is set to something higher.
         self.default_timeout = 60
 
         self._cooperator = Cooperator(scheduler=_make_scheduler(self.reactor))

synapse/http/proxy.py

@@ -43,6 +43,12 @@
 
 
 class ProxyResource(_AsyncResource):
+    """
+    A stub resource that proxies any requests with a `matrix-federation://` scheme
+    through the given `federation_agent` to the remote homeserver and ferries back the
+    info.
+    """
+
     isLeaf = True
 
     def __init__(self, reactor: ISynapseReactor, federation_agent: IAgent):
@@ -72,6 +78,9 @@ async def _async_render(self, request: "SynapseRequest") -> Tuple[int, Any]:
         )
         request_deferred = timeout_deferred(
             request_deferred,
+            # This should be set longer than the timeout in `MatrixFederationHttpClient`
+            # so that it has enough time to complete and pass us the data before we give
+            # up.
             timeout=90,
             reactor=self.reactor,
         )
@@ -154,6 +163,11 @@ def connectionLost(self, reason: Failure = connectionDone) -> None:
 
 
 class ProxySite(Site):
+    """
+    Proxies any requests with a `matrix-federation://` scheme through the given
+    `federation_agent`. Otherwise, behaves like a normal `Site`.
+    """
+
     def __init__(
         self,
         resource: IResource,

synapse/http/proxyagent.py

@@ -82,7 +82,8 @@ class ProxyAgent(_AgentBase):
         use_proxy: Whether proxy settings should be discovered and used
             from conventional environment variables.
 
-        federation_proxies: TODO
+        federation_proxies: An optional list of locations to proxy outbound federation
+            traffic through (only requests that use the `matrix-federation://` scheme).
 
     Raises:
         ValueError if use_proxy is set and the environment variables