bandwidth-file: Add scanner and destination country

Closes: #29354

1 files changed, 44 insertions, 0 deletions

diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt
index a241108..ba6cff2 100644
--- a/bandwidth-file-spec.txt
+++ b/bandwidth-file-spec.txt
@@ -103,6 +103,10 @@
     MasterKey ::= a base64-encoded Ed25519 public key, with
                   padding characters omitted.
     DateTime ::= "YYYY-MM-DDTHH:MM:SS", as in ISO 8601
+    CountryCode ::= Two capital ASCII letters ([A-Z]{2}), as defined in
+                    ISO 3166-1 alpha-2 plus "ZZ" to denote unknown country.
+    CountryCodeList ::= One or more CountryCode(s) separated by a comma
+                        ([A-Z]{2}(,[A-Z]{2})*).
 
   Note that key_value and value are defined in Tor directory protocol
   with different formats to KeyValue and Value here.
@@ -278,6 +282,28 @@
 
       This Line was added in version 1.2.0 of this specification.
 
+    "scanner_country=" CountryCode NL
+
+      [Zero or one time.]
+
+      The country, as in political geolocation, where the generator is run.
+
+      This Line was added in version 1.3.0 of this specification.
+
+    "destinations_countries=" CountryCodeList NL
+
+      [Zero or one time.]
+
+      The country, as in political geolocation, or countries where the
+      destination Web server(s) are located.
+      The destination Web Servers serve the data that the generator retrieves
+      to measure the bandwidth.
+
+      The code "ZZ" is used here to denote that the country is unknown.
+      For instance, when the destination is in a Content Delivery Network.
+
+      This Line was added in version 1.3.0 of this specification.
+
     KeyValue NL
 
       [Zero or more times.]
@@ -618,6 +644,24 @@ software=sbws
 software_version=1.0.3
 =====
 
+A.4. Headers generated by sbws version 1.0.4
+
+1523911758
+version=1.3.0
+latest_bandwidth=2018-04-16T20:49:18
+destinations_countries=TH,ZZ
+file_created=2018-04-16T21:49:18
+generator_started=2018-04-16T15:13:25
+earliest_bandwidth=2018-04-16T15:13:26
+minimum_number_eligible_relays=3862
+minimum_percent_eligible_relays=60
+number_consensus_relays=6436
+number_eligible_relays=6000
+percent_eligible_relays=93
+scanner_country=SN
+software=sbws
+software_version=1.0.4
+
 B. Scaling bandwidths
 
 B.1. Scaling requirements