Commit 6bc10cbd authored by irl's avatar irl
Browse files

Merge branch 'documentation' into 'master'

Improve javadoc for ExtraInfoDescriptor classes.

See merge request !4
parents 93c5f849 a73b8947
Pipeline #11117 passed with stage
in 2 minutes and 35 seconds
......@@ -20,14 +20,47 @@ import java.util.Set;
import java.util.SortedMap;
import java.util.TreeMap;
/**
* Contains logic to work with extra-info descriptor files.
*
* <p>The extra-info document format is defined in the dir-spec
* document.</p>
*
* @see <a href="https://github.com/torproject/torspec/blob/main/dir-spec.txt#L893">dir-spec.txt</a>
*
* <p>Descriptor keys are defined and their occurency is checked to
* make sure the descriptor file format is valid.</p>
*
* <p>Descriptor lines are parsed and their values can be accessed
* through the defined methods.</p>
*
* <p>When metrics library learns how to parse a new line for extra-info
* descriptor files all its fields, from the dir-spec document, are
* parsed in this class.</p>
*
* <p>The new key is added to {@link Key} and its occurence is checked in
* {@link ExtraInfoDescriptorImpl} constructor.</p>
*
* @since 1.0.0
*/
public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
implements ExtraInfoDescriptor {
private static final long serialVersionUID = -4720810362228341775L;
/**
* Define keys that MUST occur exactly one time in every
* instance of the document type.
*/
private Set<Key> exactlyOnceKeys = EnumSet.of(
Key.EXTRA_INFO, Key.PUBLISHED);
/**
* Define keys that MAY occur zero or one times in any instance of the
* document type, but MUST NOT occur more than once.
*/
private static final Set<Key> atMostOnceKeys = EnumSet.of(
Key.IDENTITY_ED25519, Key.MASTER_KEY_ED25519, Key.READ_HISTORY,
Key.WRITE_HISTORY, Key.DIRREQ_READ_HISTORY, Key.DIRREQ_WRITE_HISTORY,
......@@ -41,6 +74,11 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
super(descriptorBytes, offsetAndLimit, descriptorFile, false);
this.parseDescriptorBytes();
this.checkExactlyOnceKeys(exactlyOnceKeys);
/**
* When a key is added to {@link Key} it needs to be added here too.
* Either directly or to the methods that check the occurrence of the key.
*/
Set<Key> dirreqStatsKeys = EnumSet.of(
Key.DIRREQ_STATS_END, Key.DIRREQ_V2_IPS, Key.DIRREQ_V3_IPS,
Key.DIRREQ_V2_REQS, Key.DIRREQ_V3_REQS, Key.DIRREQ_V2_SHARE,
......@@ -74,6 +112,12 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
this.clearParsedKeys();
}
/**
* Parse the descriptor file.
*
* @throws DescriptorParseException
*
*/
private void parseDescriptorBytes() throws DescriptorParseException {
Scanner scanner = this.newScanner().useDelimiter(NL);
Key nextCrypto = Key.EMPTY;
......@@ -997,7 +1041,7 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
private int overloadRatelimitsVersion = 0;
@Override
public long getOverloadRatelimitsVersion() {
public int getOverloadRatelimitsVersion() {
return this.overloadRatelimitsVersion;
}
......
......@@ -3,6 +3,18 @@ package org.torproject.descriptor.impl;
import java.util.HashMap;
import java.util.Map;
/**
* Define keys from descriptor document files
*
* <p>The extra-info document format is defined in the dir-spec
* document.</p>
*
* @see <a href="https://github.com/torproject/torspec/blob/main/dir-spec.txt#L893">dir-spec.txt</a>
*
* <p>Occurence of each key is checked in the respective
* implementation class.</p>
*/
public enum Key {
EMPTY("the-empty-key"),
......
......@@ -1238,6 +1238,8 @@ public class ExtraInfoDescriptorImplTest {
String expectedDate = "Sat Jul 24 03:00:00 UTC 2021";
assertEquals(expectedDate,
new Date(descriptor.getOverloadRatelimitsTimestamp()).toString());
assertEquals("1",
Integer.toString(descriptor.getOverloadRatelimitsVersion()));
assertEquals(824,
descriptor.getOverloadRatelimitsReadCount());
assertEquals(650,
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment