Fix typos and increase consistency (#3261)

Multiple typos and text improvements in doc/* and go/beacon_srv/main.go

doc/BeaconService.md

@@ -4,49 +4,50 @@
 
 The beacon server (BS) does path exploration and registration in the scion network. It sends out
 path construction beacons (PCBs) to all neighboring core and child interfaces. The BS periodically
-selects a set of PCBs to propagate and and a set of PCBs to register at a path server. The sets of
-PCBs to propagate or register are selected according to an AS level policy.
+selects a set of PCBs to propagate and a set of PCBs to register at a path server. The sets of
+PCBs to propagate or register are selected according to an AS-level policy.
 
-Additionally the BS is also responsible to determine the state of all interfaces in the AS. For this
-each BS pings the neighbouring AS' BS over each interface. If a ping isn't received for a certain
-amount of time on an interface, the BS will assume the interface is down and sends a revocation to
-all BRs in the AS, to the local PS and to all core PSes.
+Additionally, the BS is also responsible for determining the state of all interfaces in the AS. For this,
+each BS pings the neighboring AS' BS over each interface. If a ping isn't received for a certain
+amount of time on an interface, the BS assumes the interface is down and sends a revocation to
+all border routers (BRs) in the AS, to the local [path server (PS)](PathService.md), and to all core
+PSes.
 
 ## General Structure
 
 The BS is structured similar to the existing go infra services.
 It reuses the existing building blocks for go services:
 
-* go/lib/env: Is used for configuration and setup of the service
-* go/lib/infra/modules/trust: Is used for TRCs and other crypto material
-* go/lib/infra: Is used for the messenger to send and receive messages.
-* go/lib/periodic: Is used for periodic tasks.
-* etc ...
+* [go/lib/env](../go/lib/env): Is used for configuration and setup of the service.
+* [go/lib/infra/modules/trust](../go/lib/infra/modules/trust): Is used for TRCs and other crypto material.
+* [go/lib/infra](../go/lib/infra): Is used for the messenger to send and receive messages.
+* [go/lib/periodic](../go/lib/periodic): Is used for periodic tasks.
+* etc. ...
 
-The main parts of the BS are:
+The main parts of the BS are
 
-* **handlers** to handle incoming PCBs, Revocations and interface state keeping
+* **handlers** to handle incoming PCBs, revocations, and interface state keeping,
 * **periodic tasks** for PCB propagation, segment registration, interface keepalive and revocation,
 * **beacon storage**.
 
 Each part is described in a separate chapter below. These parts can be grouped together into two
-subjects. Beaconing and Interface state keeping.
+subjects: *beaconing* and *interface state keeping*.
 
-The Beaconing part takes care of handling beacons and registering them.
+The beaconing part takes care of handling beacons and registering them.
 The following diagram shows an overview of the components related to beaconing and their dependency
 relation.
 
 ![beaconing parts overview](fig/beacon_srv/beaconing_overview.png).
 
-The interface state keeping part takes care of IfId state of the AS and issuing revocations as
+The interface-state-keeping part takes care of IfId state of the AS and issuing revocations as
 needed. The diagram shows an overview of the components related to IfId state and their dependency
 relation.
 
 ![ifstate parts overview](fig/beacon_srv/ifstate_overview.png)
 
 ### Beacon Store
 
-The beacon store is the heart of the beacon server.
+The beacon store is the heart of the BS.
 It stores the received verified beacons according to the configured path policies.
 Also, it handles the verified revocations.
 The interface definition for handlers and periodic tasks to interact with the store is listed below.
@@ -86,40 +87,41 @@ type BeaconStore interface {
 ### Policy
 
 A policy contains the parameters for the selection heuristic and the filters for inserting the
-beacon into the BeaconDB. Beacon servers have multiple policies for different purposes. Beacons that
-are filtered by all policies are not added to the beaconDB.
+beacon into the BeaconDB. BSes have multiple policies for different purposes. Beacons that
+are filtered by all policies are not added to the BeaconDB.
 
-* In a non-core beacon server, there is a policy for propagation, up-segment registration and
+* In a non-core BS, there is a policy for propagation, up-segment registration and
   down-segment registration.
-* In a core beacon server, there is a policy for propagation and for core-segment registration.
+* In a core BS, there is a policy for propagation and for core-segment registration.
 
-### Beacon DB
+### BeaconDB
 
 ![beacon db overview](fig/beacon_srv/db_overview.png)
 
 The BeaconDB consists of three tables:
 
-* Beacons: This table stores the raw beacons with some additional metadata used to select the
+* `Beacons`: This table stores the raw beacons with some additional metadata used to select the
   beacons.
-* IntfToBeacons: This table maps the (ISD-AS, IfId)-pair to all beacons containing that IfId.
-* Revocations: This table contains all revocations that are not expired.
+* `IntfToBeacons`: This table maps the (ISD-AS, IfId) pair to all beacons containing that IfId.
+* `Revocations`: This table contains all revocations that are not expired.
 
-#### Beacon insertion
+#### Beacon Insertion
 
-Before inserting, the beacon store checks that at least one policy does not filter the beacon.
-(i.e. does not contain a blacklisted AS or ISD, and the hops length does not exceed MaxHopsLength).
+Before inserting, the beacon store checks that at least one policy does not filter the beacon
+(i.e., the beacon does not contain a blacklisted AS or ISD and the `HopsLength` does not exceed
+`MaxHopsLength`).
 If that is not the case, the beacon is discarded.
-Otherwise, the beacon and the IntfToBeacon mappings are inserted.
+Otherwise, the beacon and the `IntfToBeacon` mappings are inserted.
 
-#### Beacon selection
+#### Beacon Selection
 
 Beacon selection is done in-memory and ad-hoc.
 The heuristic is as follows:
 
 1. Select at most *n* beacons with the least amount of hops that do not contain a revoked interface
    and are not expired.
-1. Choose the *k-1* paths with the least amount of hops from the set
-1. Choose the maximum disjoint path compared to the shortest path from the set
+1. Choose the *k-1* paths with the least amount of hops from the set.
+1. Choose the maximum disjoint path compared to the shortest path from the set.
 
 #### Policy Updates
 
@@ -132,11 +134,11 @@ The necessary deletions are cascaded to the other tables.
 
 #### Beacon Eviction
 
-The beacon server periodically evicts beacons that contain revoked interfaces.
+The BS periodically evicts beacons that contain revoked interfaces.
 
 ### Interfaces State
 
-The interfaces state keeps track of the state of all interfaces of an AS in the beacon server.
+The interfaces state keeps track of the state of all interfaces of an AS in the BS.
 It is used by the BS to issue revocations and decide where to propagate new beacons to.
 
 ```go
@@ -194,19 +196,19 @@ const (
 )
 ```
 
-### Trust handlers
+### Trust Handlers
 
 #### TRC/Chain Request
 
 Use existing handler from trust module.
 
-### Beaconing handlers
+### Beaconing Handlers
 
 #### PCB Handler
 
-*(uses: BeaconStore.InsertBeacon).*
+*(uses: `BeaconStore.InsertBeacon`).*
 
-When receiving a PCB the BS first checks if it has the required TRC and Chain to verify it, if not
+When receiving a PCB, the BS first checks if it has the required TRC and chain to verify it; if not,
 it will fetch it from the beaconing AS. In the initial version, the beaconing BS is contacted to be
 compatible with the python version of the code. In a second stage, we will move to requesting the
 crypto from the CS. (This requires message acks for infra messages to ensure crypto is registered
@@ -215,32 +217,32 @@ crypto material (with retries on timeout), the PCB is discarded.
 
 The BS then verifies the PCB and passes it to the beacon store.
 
-#### Revocation handler
+#### Revocation Handler
 
-*(uses: BeaconStore.InsertRevocation).*
+*(uses: `BeaconStore.InsertRevocation`).*
 
-Under some circumstances, the border router extracts revocations from SCMP errors and pushes them to
-the beacon server. Store verified revocations in the beacon store, which adds the revocation to the
-shared beaconDB.
+Under some circumstances, the BR extracts revocations from SCMP errors and pushes them to
+the BS. The BS stores verified revocations in the beacon store, which adds the revocation to the
+shared BeaconDB.
 
-### Interface state keeping handlers
+### Interface-State-Keeping Handlers
 
 #### IFStateInfoRequest Handler
 
-*(uses: Interfaces.All).*
+*(uses: `Interfaces.All`).*
 
 The reply contains the state of the interfaces from the in-memory interface state seen by the BS.
-Currently BRs send those requests periodically to cover lost IFStateInfo pushes by the BS. Once we
+Currently, BRs send those requests periodically to cover lost IFStateInfo pushes by the BS. Once we
 have acks for infra messages, we can change the model to BRs only requesting the information at the
-start-up. Since, in regular operation, the state is then reliably pushed with IfStateInfo messages
-by the BS.
+start-up. This is possible as, in regular operation, the state is then reliably pushed with IfStateInfo
+messages by the BS.
 
 #### IfId Keepalive Handler
 
-*(uses: Interface.Activate, Interfaces.All, BeaconStore.DeleteRevocation).*
+*(uses: `Interface.Activate`, `Interfaces.All`, `BeaconStore.DeleteRevocation`).*
 
 Update the interface state of the given IfId. If it changes, send IfStateInfo to all BRs, remove
-associated revocations from the BeaconDB (if any) and immediately beacon on that interface (in a
+associated revocations from the BeaconDB (if any), and immediately beacon on that interface (in a
 core AS this also includes sending an origination beacon). The associated revocations include both
 the local and the remote interface.
 
@@ -250,50 +252,50 @@ the local and the remote interface.
 
 #### PCB Propagator
 
-*(uses: BeaconStore.BeaconsToPropagate, Interfaces.All).*
+*(uses: `BeaconStore.BeaconsToPropagate`, `Interfaces.All`).*
 
 This periodic task propagates the PCBs provided by the beacon store.
-The periodic task has an interval that is less than the PropagateTime.
-Beacons are propagated on all interfaces that do not have a propagation in the last PropagateTime.
+The periodic task has an interval that is less than the `PropagateTime`.
+Beacons are propagated on all interfaces that do not have a propagation in the last `PropagateTime`.
 This ensures that beacons are propagated quickly after a stale period.
 
-Non-Core BSes
+##### Non-core BSes
 
-1. Get beacons to propagate from beacon store
+1. Get beacons to propagate from beacon store.
 1. For each PCB and non-revoked child interface:
-    1. Copy the PCB
+    1. Copy the PCB.
     1. Add AS entry for the current AS with the appropriate external interface.
-    1. Sign the new PCB
+    1. Sign the new PCB.
     1. Anycast the new PCB to a BS in the child AS.
 
-Core BSes
+##### Core BSes
 
 1. Get core beacons to propagate from beacon store and propagate to neighboring core ASes. (similar
    to step 2. above)
 
 #### PCB Initiator
 
-*(uses: Interfaces.All).*
+*(uses: `Interfaces.All`).*
 
 Core BSes originate new beacons to child and neighboring core ASes.
-The periodic task has an interval that is less than the OriginateTime.
-Beacons are originated on all interfaces that do not have a origination in the last OriginateTime.
+The periodic task has an interval that is less than the `OriginateTime`.
+Beacons are originated on all interfaces that do not have an origination in the last `OriginateTime`.
 
-1. Create a new PCB using the local IA and the current timestamp
+1. Create a new PCB using the local IA and the current timestamp.
 1. Propagate the PCB on all core and child interfaces.
 
 #### Segment Registration
 
-*(uses: BeaconStore.SegmentsToRegister).*
+*(uses: `BeaconStore.SegmentsToRegister`).*
 
-This periodic task registers the best PCB as path segments with the appropriate PS. Note that once
-we have app level acks in place, segment registration should use them and retry registering the
+This periodic task registers the best PCBs as path segments with the appropriate PS. Note that once
+we have app-level acks in place, segment registration should use them and retry registering the
 segments until it an ack is received (or a specified timeout is hit). Similar to beacon propagation,
-the interval is less than RegisterTime. Whenever no path has been registered in the last
-RegisterTime, paths are registered immediately. This ensures that segments are registered quickly
+the interval is less than `RegisterTime`. Whenever no path has been registered in the last
+`RegisterTime`, paths are registered immediately. This ensures that segments are registered quickly
 after a stale period.
 
-Non-Core BSes
+##### Non-core BSes
 
 1. Get PCBs for up and down direction from the beacon store.
 1. Remove non signed fields to create a path segment.
@@ -302,53 +304,53 @@ Non-Core BSes
 1. Sign the segments.
 1. Send up-segments to local PS, down-segments to core PS.
 
-Core BSes
+##### Core BSes
 
 1. Get PCBs towards each core AS observed so far from the beacon store.
 1. Remove non signed fields to create a path segment.
 1. Set current AS entry as terminal AS for all segments.
 1. Sign the segments.
 1. Share all segments with any local PS.
 
-### Interface State keeping
+### Interface State Keeping
 
 #### Interface Revocation
 
-*(uses: Interfaces.All, Interface.Expire,  Interface.Revoke, Beaconstore.InsertRevocation).*
+*(uses: `Interfaces.All`, `Interface.Expire`,  `Interface.Revoke`, `BeaconStore.InsertRevocation`).*
 
 Each BS instance keeps track of the interface state in an in-memory structure. When a configurable
-amount of keepalive messages for a given interface are not received, the interface is revoked by the
+amount of keepalive messages for a given interface is not received, the interface is revoked by the
 BS.
 
-1. Call Interface.Expire on all infos.
-1. Revoke all expired interfaces in InterfaceState, update the revocation if necessary (certain
-   amount of previous revocation period has passed)
-1. Insert revocation in beacon store
+1. Call `Interface.Expire` on all infos.
+1. Revoke all expired interfaces in `InterfaceState`, update the revocation if necessary (certain
+   amount of previous revocation period has passed).
+1. Insert revocation in beacon store.
 1. Send revocation to all BRs in the local AS.
-1. Send revocation to local PS as SignedRevInfo
+1. Send revocation to local PS as `SignedRevInfo`.
 1. Send revocation to PS in all core ASes, if in non-core AS.
 
 #### IfId Keepalive Sender
 
-*(uses: itopo.Get).*
+*(uses: `itopo.Get`).*
 
 Periodically send an IfId Keepalive message to the neighboring BS for each interface in the
 topology. This is done by using a one hop path extension.
 
-### Delete Expired data from DB
+### Delete Expired Data From DB
 
-*(uses: BeaconStore.DeleteExpired).*
+*(uses: `BeaconStore.DeleteExpired`).*
 
-Periodically delete data that is no longer relevant. That includes:
+Periodically delete data that is no longer relevant. That includes
 
-* PCBs that are expired
-* Revocations that are expired
+* PCBs that are expired,
+* Revocations that are expired.
 
 ## Events
 
 ### Topology Reload
 
-*(uses: InterfaceState.Update).*
+*(uses: `InterfaceState.Update`).*
 
 Update the interface states according to the changes in the new topology.
 The BS then immediately sends IfStateInfos to all BRs.