Merge branch 'overload-general' into 'master'

Parse and expose fields from the overload-general line from the server descriptor.

See merge request !5

src/main/java/org/torproject/descriptor/ServerDescriptor.java

@@ -56,56 +56,68 @@ public interface ServerDescriptor extends Descriptor {
   String getDigestSha1Hex();
 
   /**
-   * Return the SHA-256 descriptor digest, encoded as 43 base64
+   * Get the SHA-256 descriptor digest, encoded as 43 base64
    * characters without padding characters, that may be used to reference
    * this server descriptor from a network status descriptor.
    *
+   * @return descriptor digest
+   *
    * @since 1.7.0
    */
   String getDigestSha256Base64();
 
   /**
-   * Return the server's nickname consisting of 1 to 19 alphanumeric
+   * Get the server's nickname consisting of 1 to 19 alphanumeric
    * characters.
    *
+   * @return nickname
+   *
    * @since 1.0.0
    */
   String getNickname();
 
   /**
-   * Return the server's primary IPv4 address in dotted-quad format.
+   * Get the server's primary IPv4 address in dotted-quad format.
+   *
+   * @return IPv4 address
    *
    * @since 1.0.0
    */
   String getAddress();
 
   /**
-   * Return the TCP port where this server accepts TLS connections for
+   * Get the TCP port where this server accepts TLS connections for
    * the main OR protocol, or 0 if the server does not accept such
    * connections.
    *
+   * @return TCP OR port
+   *
    * @since 1.0.0
    */
   int getOrPort();
 
   /**
-   * Return the TCP port where this server accepts SOCKS connections,
+   * Get the TCP port where this server accepts SOCKS connections,
    * which is deprecated in the Tor Protocol and should always be 0.
    *
+   * @return socks port
+   *
    * @since 1.0.0
    */
   int getSocksPort();
 
   /**
-   * Return the TCP port where this server accepts directory-related HTTP
+   * Get the TCP port where this server accepts directory-related HTTP
    * connections, or 0 if the server does not accept such connections.
    *
+   * @return TCP directory port
+   *
    * @since 1.0.0
    */
   int getDirPort();
 
   /**
-   * Return IP addresses and TCP ports where this server accepts TLS
+   * Get IP addresses and TCP ports where this server accepts TLS
    * connections for the main OR protocol, or an empty list if the server
    * does not support additional addresses or ports; entries are given in
    * the order as they are listed in the descriptor; IPv4 addresses are
@@ -113,182 +125,245 @@ public interface ServerDescriptor extends Descriptor {
    * hexadecimal format surrounded by square brackets, and TCP ports are
    * separated from the IP address using a colon.
    *
+   * @return OR addresses
+   *
    * @since 1.0.0
    */
   List<String> getOrAddresses();
 
   /**
-   * Return the average bandwidth in bytes per second that the server is
+   * Get the average bandwidth in bytes per second that the server is
    * willing to sustain over long periods.
    *
+   * @return bandwidth rate
+   *
    * @since 1.0.0
    */
   int getBandwidthRate();
 
   /**
-   * Return the burst bandwidth in bytes per second that the server is
+   * Get the burst bandwidth in bytes per second that the server is
    * willing to sustain in very short intervals.
    *
+   * @return burst bandwidth limit
+   *
    * @since 1.0.0
    */
   int getBandwidthBurst();
 
   /**
-   * Return the observed bandwidth in bytes per second as an estimate of
+   * Get the observed bandwidth in bytes per second as an estimate of
    * the capacity that the server can handle, or -1 if the descriptor
    * doesn't contain an observed bandwidth value (which is the case for
    * Tor 0.0.8 or older).
    *
+   * @return observed bandwidth
+   *
    * @since 1.0.0
    */
   int getBandwidthObserved();
 
   /**
-   * Return a human-readable string describing the Tor software version
+   * Get a human-readable string describing the Tor software version
    * and the operating system of this server, which may contain non-ASCII
    * characters, typically written as {@code "Tor $version on $system"},
    * or null if this descriptor does not contain a platform line.
    *
+   * @return human-readable Tor and OS version
+   *
    * @since 1.0.0
    */
   String getPlatform();
 
   /**
-   * Return the version numbers of all protocols supported by this server, or
+   * Get the timestamp of when the server was detected in an overloaded
+   * state
+   *
+   * <p>Because this is a binary state, if the line is present, we consider
+   * that it was hit at the very least once somewhere between the
+   * provided timestamp and the "published" timestamp of the document
+   * which is when the document was generated.</p>
+   *
+   * @return timestamp
+   *
+   * @since 2.19.0
+   */
+  long getOverloadGeneralTimestamp();
+
+  /**
+   * Get the version number in the overload-general line.
+   *
+   * @return version
+   *
+   * @since 2.19.0
+   */
+  int getOverloadGeneralVersion();
+
+  /**
+   * Get the version numbers of all protocols supported by this server, or
    * null if this descriptor does not specify supported protocol versions.
    *
+   * @return supported protocols version numbers
+   *
    * @since 1.6.0
    */
   SortedMap<String, SortedSet<Long>> getProtocols();
 
   /**
-   * Return the time in milliseconds since the epoch when this descriptor
+   * Get the time in milliseconds since the epoch when this descriptor
    * and the corresponding extra-info descriptor were generated.
    *
+   * @return time since the descriptors were generated
+   *
    * @since 1.0.0
    */
   long getPublishedMillis();
 
   /**
-   * Return a SHA-1 digest of the server's public identity key, encoded
+   * Get a SHA-1 digest of the server's public identity key, encoded
    * as 40 upper-case hexadecimal characters (without spaces after every 4
    * characters as opposed to the encoding in the descriptor), that is
    * typically used to uniquely identify the server, or null if this
    * descriptor does not contain a fingerprint line.
    *
+   * @return SHA-1 public identity key digest
+   *
    * @since 1.0.0
    */
   String getFingerprint();
 
   /**
-   * Return whether the server was hibernating when this descriptor was
+   * Get whether the server was hibernating when this descriptor was
    * published and should not be used to build circuits.
    *
+   * @return hibernating flag
+   *
    * @since 1.0.0
    */
   boolean isHibernating();
 
   /**
-   * Return the number of seconds that the server process has been
+   * Get the number of seconds that the server process has been
    * running (which might even be negative in a few descriptors due to a
    * bug that was fixed in Tor 0.1.2.7-alpha), or null if the descriptor
    * does not contain an uptime line.
    *
+   * @return seconds since the server process was started
+   *
    * @since 1.0.0
    */
   Long getUptime();
 
   /**
-   * Return the RSA-1024 public key in PEM format used to encrypt CREATE
+   * Get the RSA-1024 public key in PEM format used to encrypt CREATE
    * cells for this server, or null if the descriptor doesn't contain an
    * onion key (which is the case in sanitized bridge descriptors).
    *
+   * @return RSA-1024 public key in PEM format
+   *
    * @since 1.0.0
    */
   String getOnionKey();
 
   /**
-   * Return the RSA-1024 public key in PEM format used by this server as
+   * Get the RSA-1024 public key in PEM format used by this server as
    * long-term identity key, or null if the descriptor doesn't contain a
    * signing key (which is the case in sanitized bridge descriptors).
    *
+   * @return RSA-1024 public key in PEM format
+   *
    * @since 1.0.0
    */
   String getSigningKey();
 
   /**
-   * Return the server's exit policy consisting of one or more accept or
+   * Get the server's exit policy consisting of one or more accept or
    * reject rules that the server follows when deciding whether to allow a
    * new stream to a given IP address and TCP port.
    *
+   * @return exit policy
+   *
    * @since 1.0.0
    */
   List<String> getExitPolicyLines();
 
   /**
-   * Return the RSA-1024 signature of the PKCS1-padded descriptor digest,
+   * Get the RSA-1024 signature of the PKCS1-padded descriptor digest,
    * taken from the beginning of the router line through the newline after
    * the router-signature line, or null if the descriptor doesn't contain
    * a signature (which is the case in sanitized bridge descriptors).
    *
+   * @return RSA-1024 signature
+   *
    * @since 1.0.0
    */
   String getRouterSignature();
 
   /**
-   * Return the contact information for this server, which may contain
+   * Get the contact information for this server, which may contain
    * non-ASCII characters, or null if no contact information is included
    * in the descriptor.
    *
+   * @return contact information
+   *
    * @since 1.0.0
    */
   String getContact();
 
   /**
-   * Return the method how a bridge requests to be distributed by BridgeDB, or
+   * Get the method how a bridge requests to be distributed by BridgeDB, or
    * {@code null} if no such request is contained in the descriptor.
    *
+   * @return bridge distribution method
+   *
    * @since 2.11.0
    */
   String getBridgeDistributionRequest();
 
   /**
-   * Return nicknames, $-prefixed identity fingerprints, or tuples of the
+   * Get nicknames, $-prefixed identity fingerprints, or tuples of the
    * format {@code $fingerprint=nickname} or {@code $fingerprint~nickname}
    * of servers contained in this server's family, or null if the
    * descriptor does not contain a family line.
    *
+   * @return family line
+   *
    * @since 1.0.0
    */
   List<String> getFamilyEntries();
 
   /**
-   * Return the server's history of read bytes, or null if the descriptor
+   * Get the server's history of read bytes, or null if the descriptor
    * does not contain a bandwidth history; current Tor versions include
    * bandwidth histories in their extra-info descriptors
    * ({@link ExtraInfoDescriptor#getReadHistory()}), not in their server
    * descriptors.
+   * @return history of read bytes
    *
    * @since 1.0.0
    */
   BandwidthHistory getReadHistory();
 
   /**
-   * Return the server's history of written bytes, or null if the
+   * Get the server's history of written bytes, or null if the
    * descriptor does not contain a bandwidth history; current Tor versions
    * include bandwidth histories in their extra-info descriptors
    * ({@link ExtraInfoDescriptor#getWriteHistory()}), not in their server
    * descriptors.
    *
+   * @return history of written bytes
+   *
    * @since 1.0.0
    */
   BandwidthHistory getWriteHistory();
 
   /**
-   * Return true if the server uses the enhanced DNS logic, or false if
-   * doesn't use it or doesn't include an eventdns line in its
-   * descriptor; current Tor versions should be presumed to have the evdns
-   * backend.
+   * Get the enhanced DNS logic value for the server. Returns true if the
+   * server uses the enhanced DNS logic, or false if doesn't use it or
+   * doesn't include an eventdns line in its descriptor; current Tor
+   * versions should be presumed to have the evdns backend.
+   *
+   * @return enhanced DNS logic boolean flag
    *
    * @since 1.0.0
    */
@@ -303,32 +378,38 @@ public interface ServerDescriptor extends Descriptor {
   boolean getCachesExtraInfo();
 
   /**
-   * Return the SHA-1 digest of the server's extra-info descriptor,
+   * Get the SHA-1 digest of the server's extra-info descriptor,
    * encoded as 40 upper-case hexadecimal characters, or null if the
    * server did not upload a corresponding extra-info descriptor.
    *
+   * @return SHA-1 digest
+   *
    * @since 1.7.0
    */
   String getExtraInfoDigestSha1Hex();
 
   /**
-   * Return the SHA-256 digest of the server's extra-info descriptor,
+   * Get the SHA-256 digest of the server's extra-info descriptor,
    * encoded as 43 base64 characters without padding characters, or null
    * if the server either did not upload a corresponding extra-info
    * descriptor or did not refer to it using a SHA-256 digest.
    *
+   * @return SHA-256 digest
+   *
    * @since 1.7.0
    */
   String getExtraInfoDigestSha256Base64();
 
   /**
-   * Return the list of hidden service descriptor version numbers that
+   * Get the list of hidden service descriptor version numbers that
    * this server stores and serves, or null if it doesn't store and serve
    * any hidden service descriptors.
    *
    * @deprecated Replaced with {@link #isHiddenServiceDir}, because Tor has
    *     never supported versions in the hidden-service-dir descriptor line.
    *
+   * @return list of version numbers
+   *
    * @since 1.0.0
    */
   @Deprecated
@@ -350,113 +431,139 @@ public interface ServerDescriptor extends Descriptor {
   List<Integer> getLinkProtocolVersions();
 
   /**
-   * Return the list of circuit protocol versions that this server
+   * Get the list of circuit protocol versions that this server
    * supports.
    *
+   * @return list of protocol versions
+   *
    * @since 1.0.0
    */
   List<Integer> getCircuitProtocolVersions();
 
   /**
-   * Return whether this server allows single-hop circuits to make exit
+   * Get whether this server allows single-hop circuits to make exit
    * connections.
    *
+   * @return single-hop allowed flag
+   *
    * @since 1.0.0
    */
   boolean getAllowSingleHopExits();
 
   /**
-   * Return the default policy, {@code "accept"} or {@code "reject"}, of
+   * Get the default policy, {@code "accept"} or {@code "reject"}, of
    * the IPv6 port summary, or null if the descriptor didn't contain an
    * IPv6 exit-policy summary line which is equivalent to rejecting all
    * streams to IPv6 targets.
    *
+   * @return default policy
+   *
    * @since 1.0.0
    */
   String getIpv6DefaultPolicy();
 
   /**
-   * Return the port list of the IPv6 exit-policy summary, or null if the
+   * Get the port list of the IPv6 exit-policy summary, or null if the
    * descriptor didn't contain an IPv6 exit-policy summary line which is
    * equivalent to rejecting all streams to IPv6 targets.
    *
+   * @return IPv6 exit-policy
+   *
    * @since 1.0.0
    */
   String getIpv6PortList();
 
   /**
-   * Return the curve25519 public key, encoded as 43 base64 characters
+   * Get the curve25519 public key, encoded as 43 base64 characters
    * without padding characters, that is used for the ntor circuit
    * extended handshake, or null if the descriptor didn't contain an
-   * ntor-onion-key line. */
+   * ntor-onion-key line.
+   *
+   * @return curve25519 public key
+   *
+   * */
   String getNtorOnionKey();
 
   /**
-   * Return the Ed25519 certificate in PEM format, or null if the
+   * Get the Ed25519 certificate in PEM format, or null if the
    * descriptor doesn't contain one.
    *
+   * @return Ed25519 certificate
+   *
    * @since 1.1.0
    */
   String getIdentityEd25519();
 
   /**
-   * Return the Ed25519 master key, encoded as 43 base64 characters
+   * Get the Ed25519 master key, encoded as 43 base64 characters
    * without padding characters, which was either parsed from the optional
    * {@code "master-key-ed25519"} line or derived from the (likewise
    * optional) Ed25519 certificate following the
    * {@code "identity-ed25519"} line, or null if the descriptor contains
    * neither Ed25519 master key nor Ed25519 certificate.
    *
+   * @return Ed25519 master key
+   *
    * @since 1.1.0
    */
   String getMasterKeyEd25519();
 
   /**
-   * Return the Ed25519 signature of the SHA-256 digest of the entire
+   * Get the Ed25519 signature of the SHA-256 digest of the entire
    * descriptor, encoded as 86 base64 characters without padding
    * characters, from the first character up to and including the first
    * space after the {@code "router-sig-ed25519"} string, prefixed with
    * the string {@code "Tor router descriptor signature v1"}.
    *
+   * @return Ed25519 signature
+   *
    * @since 1.1.0
    */
   String getRouterSignatureEd25519();
 
   /**
-   * Return an RSA-1024 signature in PEM format, generated using the
+   * Get an RSA-1024 signature in PEM format, generated using the
    * server's onion key, that proves that the party creating the
    * descriptor had control over the private key corresponding to the
    * onion key, or null if the descriptor does not contain such a
    * signature.
    *
+   * @return RSA-1024 signature
+   *
    * @since 1.1.0
    */
   String getOnionKeyCrosscert();
 
   /**
-   * Return an Ed25519 signature in PEM format, generated using the
+   * Get an Ed25519 signature in PEM format, generated using the
    * server's ntor onion key, that proves that the party creating the
    * descriptor had control over the private key corresponding to the ntor
    * onion key, or null if the descriptor does not contain such a
    * signature.
    *
+   * @return Ed25519 signature
+   *
    * @since 1.1.0
    */
   String getNtorOnionKeyCrosscert();
 
   /**
-   * Return the sign of the Ed25519 public key corresponding to the ntor
+   * Get the sign of the Ed25519 public key corresponding to the ntor
    * onion key as 0 or 1, or -1 if the descriptor does not contain this
    * information.
    *
+   * @return sign of the Ed25519 public
+   *
    * @since 1.1.0
    */
   int getNtorOnionKeyCrosscertSign();
 
   /**
-   * Return whether the server accepts "tunneled" directory requests using
+   * Get whether the server accepts "tunneled" directory requests using
    * a BEGIN_DIR cell over the server's OR port.
    *
+   * @return "tunneled" directory requests flag
+   *
    * @since 1.3.0
    */
   boolean getTunnelledDirServer();

src/main/java/org/torproject/descriptor/impl/Key.java

@@ -118,8 +118,9 @@ public enum Key {
   ONION_KEY_CROSSCERT("onion-key-crosscert"),
   OPT("opt"),
   OR_ADDRESS("or-address"),
-  OVERLOAD_RATELIMITS("overload-ratelimits"),
   OVERLOAD_FD_EXHAUSTED("overload-fd-exhausted"),
+  OVERLOAD_GENERAL("overload-general"),
+  OVERLOAD_RATELIMITS("overload-ratelimits"),
   P("p"),
   P6("p6"),
   PACKAGE("package"),

src/main/java/org/torproject/descriptor/impl/ServerDescriptorImpl.java

@@ -28,8 +28,8 @@ public abstract class ServerDescriptorImpl extends DescriptorImpl
       Key.IDENTITY_ED25519, Key.MASTER_KEY_ED25519, Key.PLATFORM, Key.PROTO,
       Key.FINGERPRINT, Key.HIBERNATING, Key.UPTIME, Key.CONTACT, Key.FAMILY,
       Key.READ_HISTORY, Key.WRITE_HISTORY, Key.EVENTDNS, Key.CACHES_EXTRA_INFO,
-      Key.EXTRA_INFO_DIGEST, Key.HIDDEN_SERVICE_DIR, Key.PROTOCOLS,
-      Key.ALLOW_SINGLE_HOP_EXITS, Key.ONION_KEY, Key.SIGNING_KEY,
+      Key.EXTRA_INFO_DIGEST, Key.HIDDEN_SERVICE_DIR, Key.OVERLOAD_GENERAL,
+      Key.PROTOCOLS, Key.ALLOW_SINGLE_HOP_EXITS, Key.ONION_KEY, Key.SIGNING_KEY,
       Key.IPV6_POLICY, Key.NTOR_ONION_KEY, Key.ONION_KEY_CROSSCERT,
       Key.NTOR_ONION_KEY_CROSSCERT, Key.TUNNELLED_DIR_SERVER,
       Key.ROUTER_SIG_ED25519, Key.ROUTER_SIGNATURE, Key.ROUTER_DIGEST_SHA256,
@@ -76,6 +76,9 @@ public abstract class ServerDescriptorImpl extends DescriptorImpl
         case BANDWIDTH:
           this.parseBandwidthLine(line, partsNoOpt);
           break;
+        case OVERLOAD_GENERAL:
+          this.parseOverloadGeneralLine(line, partsNoOpt);
+          break;
         case PLATFORM:
           this.parsePlatformLine(lineNoOpt);
           break;
@@ -294,6 +297,24 @@ public abstract class ServerDescriptorImpl extends DescriptorImpl
     }
   }
 
+  private void parseOverloadGeneralLine(String line,
+      String[] partsNoOpt) throws DescriptorParseException {
+    int overloadGeneralVersion = Integer.parseInt(partsNoOpt[1]);
+    if (overloadGeneralVersion != 1) {
+      throw new DescriptorParseException("Unknown version number for line '"
+              + line + "' in extra-info descriptor.");
+    } else {
+      this.overloadGeneralVersion = overloadGeneralVersion;
+    }
+    if (partsNoOpt.length < 4) {
+      throw new DescriptorParseException("Missing fields for line '"
+              + line + "' in extra-info descriptor.");
+    }
+    this.overloadGeneralTimestamp = ParseHelper.parseTimestampAtIndex(line,
+            partsNoOpt, 2, 3);
+
+  }
+
   private void parsePlatformLine(String lineNoOpt) {
     if (lineNoOpt.length() > Key.PLATFORM.keyword.length() + 1) {
       this.platform = lineNoOpt.substring(Key.PLATFORM.keyword.length() + 1);
@@ -726,6 +747,20 @@ public abstract class ServerDescriptorImpl extends DescriptorImpl
     return this.bandwidthObserved;
   }
 
+  private int overloadGeneralVersion = 0;
+
+  @Override
+  public int getOverloadGeneralVersion() {
+    return this.overloadGeneralVersion;
+  }
+
+  private long overloadGeneralTimestamp = -1L;
+
+  @Override
+  public long getOverloadGeneralTimestamp() {
+    return this.overloadGeneralTimestamp;
+  }