Fix Federation Docs errata

docs/src/how-to/install/configure-federation.md

@@ -14,7 +14,7 @@ detailed in the sections below:
 
 -   Choose a backend domain name
 
--   DNS setup for federation (including a `SRV` record)
+-   DNS setup for federation (including an `SRV` record)
 
 -   Generate and configure TLS certificates:
 
@@ -31,7 +31,7 @@ detailed in the sections below:
 ## Choose a Backend Domain
 
 As of the release \[helm chart 0.129.0, Wire docker version 2.94.0\] from
-2020-12-15, the `federationDomain` is a mandatory configuration setting, which
+2020-12-15, `federationDomain` is a mandatory configuration setting, which
 defines the {ref}`backend domain <glossary_backend_domain>` of your
 installation. Regardless of whether you want to enable federation for a backend
 or not, you must decide what its domain is going to be. This helps in keeping
@@ -118,7 +118,7 @@ The fields of the SRV record need to be populated as follows
 -   `weight`: \>0 for your server to be reachable. A good default value
     could be 10
 -   `port`: `443`
--   `target`: the infra domain
+-   `target`: the infrastructure domain
 
 To give an example, assuming
 
@@ -237,7 +237,7 @@ trust when interacting with other backends.
 ### (B) Manual server and client certificates
 
 Use your usual method of obtaining X.509 certificates for your {ref}`federation
-infra domain <glossary_infra_domain>` (alongside the other domains needed for a
+infrastructure domain <glossary_infra_domain>` (alongside the other domains needed for a
 wire-server installation).
 
 You can use one single certificate and key for both server and client
@@ -266,7 +266,7 @@ X509v3 extensions:
         TLS Web Server Authentication, TLS Web Client Authentication
 ```
 
-And your {ref}`federation infra domain <glossary_infra_domain>` (e.g.
+And your {ref}`federation infrastructure domain <glossary_infra_domain>` (e.g.
 `federator.wire.example.com` from the running example) needs to either figure
 explictly in the list of your SAN (Subject Alternative Name):
 
@@ -304,7 +304,7 @@ The *server certificate* and *private key* need to be configured in
 just the federator component. If you have installed wire-server before
 without federation, server certificates may already be configured
 *(though you probably need to create new certificates to include the
-federation infra domain if you\'re not making use of wildcard
+federation infrastructure domain if you\'re not making use of wildcard
 certificates)*. Server certificates go here:
 
 ``` yaml
@@ -515,7 +515,7 @@ Ensure that the IP matches where your backend ingress runs.
 
 Refer to {ref}`how-to-see-tls-certs` and set
 DOMAIN to your
-{ref}`federation infra domain <glossary_infra_domain>`. They should include your domain as part of the SAN (Subject
+{ref}`federation infrastructure domain <glossary_infra_domain>`. They should include your domain as part of the SAN (Subject
 Alternative Names) and not have expired.
 
 ### Manually test that federation works 

docs/src/understand/federation/api.md

@@ -231,9 +231,9 @@ their precise inputs and outputs.
 
 In the following the interactions between *Federator* and *Federation Ingress*
 components of the backends involved are omitted for simplicity. Also the backend
-domain and infra domain are assumed the same.
+domain and infrastructure domain are assumed the same.
 
-Additionally we assume that the backend domain and the infra domain of
+Additionally we assume that the backend domain and the infrastructure domain of
 the respective backends involved are the same and each domain identifies
 a distinct backend.
 

docs/src/understand/federation/architecture.md

@@ -6,19 +6,18 @@
 ## Backends
 
 In the following we call a **backend** the set of servers, databases and DNS
-configurations that together form one single Wire Server entity as seen from
+configurations that together form one single Wire Server entity as seen from the
 outside. It can also be called a Wire \"instance\" or \"server\" or \"Wire
 installation\". Every resource (e.g. users, conversations, assets and teams)
 exists and is *owned* by a single backend, which we can refer to as that
 resource\'s backend.
 
 The communication between federated backends is facilitated by two components in
-each backend: {ref}`federation_ingress` and {ref}`federator`. The
-*Federation Ingress* is, as the name suggests the
-ingress point for incoming connections from other backends, which are then
-forwarded to the *Federator*. The *Federator* forwards requests
-to internal components. It also acts as a *egress* point for requests from
-internal backend components to other, remote backends.
+each backend: {ref}`federation_ingress` and {ref}`federator`. The *Federation
+Ingress* is, as the name suggests, the ingress point for incoming connections
+from other backends, which are then forwarded to the *Federator*. The
+*Federator* forwards requests to internal components. It also acts as a *egress*
+point for requests from internal backend components to other, remote backends.
 
 ![image](img/federated-backend-architecture.png)
 
@@ -32,7 +31,7 @@ internal backend components to other, remote backends.
 Each backend has two domain: an {ref}`infrastructure domain <glossary_infra_domain>` and a
 {ref}`backend domain <glossary_backend_domain>`.
 
-The **infrastructure domain** (short **infra domain**) is the domain name under which the backend
+The **infrastructure domain** is the domain name under which the backend
 is actually reachable via the network. It is also the domain name that
 each backend uses in authenticating itself to other backends.
 
@@ -42,7 +41,7 @@ context of federation.
 
 The distinction between the two domains allows the owner of a backend
 domain, e.g. `example.com`, to host their Wire backend under a
-different infra domain, e.g. `wire.infra.example.com`.
+different infrastructure domain, e.g. `wire.infra.example.com`.
 
 (federation_ingress)=
 
@@ -53,7 +52,7 @@ ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
 and uses [nginx](https://nginx.org/en/) as its underlying software.
 
 It is configured with a set of X.509 certificates, which acts as root of
-trust for the authentication of the infra domain of remote backends, as
+trust for the authentication of the infrastructure domain of remote backends, as
 well as with a certificate, which it uses to authenticate itself toward
 other backends.
 
@@ -74,7 +73,7 @@ point for other backend components. It can be configured to use an
 {ref}`allow list
 <allow-list>` to authorize incoming and
 outgoing connections, and it keeps an X.509 client certificate for the
-backend\'s infra domain to authenticate itself towards other backends.
+backend\'s infrastructure domain to authenticate itself towards other backends.
 Additionally, it requires a connection to a DNS resolver to
 {ref}`discover<discovery>` other backends.
 
@@ -97,7 +96,7 @@ from remote backends (forwarded via the local
 1.  Discover the mapping
     between backend domain claimed by the remote backend and its infra
     domain,
-2.  Verify that the discovered infra domain matches the domain in the
+2.  Verify that the discovered infrastructure domain matches the domain in the
     remote backend\'s client certificate,
 3.  If enabled, ensure that the backend domain of the other backend is
     in the allow list.

docs/src/understand/federation/backend-communication.md

@@ -9,7 +9,7 @@ need to ensure the following:
 
 - **Authentication**
 
-    Determine the identity (infra domain name) of the other backend.
+    Determine the identity (infrastructure domain name) of the other backend.
 
 - **Discovery**
 
@@ -36,7 +36,7 @@ Conversely, every *Federator* needs to be provisioned with a client
 certificate which it uses to authenticate itself towards other backends.
 
 Note that the client certificate is required to be issued with the backend\'s
-infra domain as one of the subject alternative names (SAN), which is defined in
+infrastructure domain as one of the subject alternative names (SAN), which is defined in
 [RFC 5280](https://tools.ietf.org/html/rfc5280).
 
 See {ref}`federation-certificate-setup` for technical instructions.
@@ -48,29 +48,27 @@ with an `AuthenticationFailure` error.
 
 ## Discovery
 
-The discovery process allows a backend to determine the infra domain of
+The discovery process allows a backend to determine the infrastructure domain of
 a given backend domain.
 
 This step is necessary in two scenarios:
 
 -   A backend would like to establish a connection to another backend
     that it only knows the backend domain of. This is the case, for
     example, when a user of a local backend searches for a
-    {ref}`qualified username <qualified-identifiers-and-names>`, which only includes that user\'s backend\'s backend
-    domain.
+    {ref}`qualified username <qualified-identifiers-and-names>`, which only includes the backend domain of that user's backend.
 -   When receiving a message from another backend that authenticates
-    with a given infra domain and claims to represent a given backend
+    with a given infrastructure domain and claims to represent a given backend
     domain, a backend would like to ensure the backend domain owner
-    authorized the owner of the infra domain to run their Wire backend.
+    authorized the owner of the infrastructure domain to run their Wire backend.
 
 To make discovery possible, any party hosting a Wire backend has to
-announce the infra domain via a DNS *SRV* record as defined in [RFC
+announce the infrastructure domain via a DNS *SRV* record as defined in [RFC
 2782](https://tools.ietf.org/html/rfc2782) with
 `service = wire-server-federator, proto = tcp` and with `name` pointing
-to the backend\'s domain and *target* to the backend\'s infra domain.
+to the backend\'s domain and *target* to the backend\'s infrastructure domain.
 
-For example, Company A with backend domain *company-a.com* and infra
-domain *wire.company-a.com* could publish
+For example, Company A with backend domain *company-a.com* and infrastructure domain *wire.company-a.com* could publish
 
 ``` bash
 _wire-server-federator._tcp.company-a.com. 600  IN  SRV 10 5 443 federator.wire.company-a.com.
@@ -83,34 +81,24 @@ In case this process fails the Federator fails to forward the request with a `Di
 
 (dns-scope)=
 
-### DNS Scope
-
-The network scope of the SRV record (as well as that of the DNS records
-for backend and infra domain), depends on the desired federation
-topology in the same way as other parameters such as the availability of
-the CA certificate that allows authentication of the *Federation
-Ingress*\' server certificate or the *Federator*\'s client certificate.
-The general rule is that the SRV entry should be \"visible\" from the
-point of view of the desired federation partners. The exact scope
-strongly depends on the network architecture of the backends involved.
 
 (srv-ttl-and-caching)=
 
 ### SRV TTL and Caching
 
 After retrieving the SRV record for a given domain, the local backend
-caches the *backend domain \<\--\> infra domain* mapping for the
+caches the *backend domain \<\--\> infrastructure domain* mapping for the
 duration indicated in the TTL field of the record.
 
 Due to this caching behavior, the TTL value of the SRV record dictates
 at which intervals remote backends will refresh their mapping of the
-local backend\'s backend domain to infra domain. As a consequence a
+local backend\'s backend domain to infrastructure domain. As a consequence a
 value in the order of magnitude of 24 hours will reduce the amount of
 overhead for remote backends.
 
-On the other hand in the setup phase of a backend, or when a change of infra
+On the other hand in the setup phase of a backend, or when a change of infrastructure
 domain is required, a TTL value in the magnitude of a few minutes allows remote
-backends to recover more quickly from a change of the infra domain.
+backends to recover more quickly from a change of the infrastructure domain.
 
 (authorization)=
 
@@ -122,10 +110,10 @@ After an incoming connection is authenticated the backend authorizes the
 request. It does so by verifying that the backend domain of the sender is
 contained in the {ref}`domain allow list <configure-federation-allow-list>`.
 
-Since the request is authenticated only by the infra domain the sending backend
+Since the request is authenticated only by the infrastructure domain the sending backend
 is required to add its backend domain as a `Wire-Origin-Domain` header to the
 request. The receiving backend follows the process described in {ref}`discovery`
-and verifies that the discovered infra domain for the backend domain indicated
+and verifies that the discovered infrastructure domain for the backend domain indicated
 in the `Wire-Origin-Domain` header is one of the Subject Alternative Names
 contained in the client certificate used to sign the request. If this is not the
 case, the receiving backend fails the request with a `ValidationError`.
@@ -150,8 +138,8 @@ details.
 ## Example
 
 The following is an example for the message and information flow between
-a backend with backend domain `a.com` and infra domain `infra.a.com` and
-another backend with backend domain `b.com` and infra domain
+a backend with backend domain `a.com` and infrastructure domain `infra.a.com` and
+another backend with backend domain `b.com` and infrastructure domain
 `infra.b.com`.
 
 The content and format of the message is meant to be representative. For