commit 7a8f1ffd2d95388892efe0f4198ffae0c076aa34
Author: Karsten Loesing <karsten.loesing(a)gmx.net>
Date: Tue Aug 18 09:52:36 2015 +0200
Add "alleged_family" and "indirect_family" fields.
Implements #16750.
---
build.xml | 2 +-
.../torproject/onionoo/docs/DetailsDocument.java | 16 +++
.../org/torproject/onionoo/docs/DetailsStatus.java | 16 +++
.../org/torproject/onionoo/docs/NodeStatus.java | 83 ++++++++++-----
.../torproject/onionoo/server/ResponseBuilder.java | 6 +-
.../onionoo/updater/NodeDetailsStatusUpdater.java | 84 +++++++++++----
.../onionoo/writer/DetailsDocumentWriter.java | 20 ++++
.../onionoo/writer/SummaryDocumentWriter.java | 5 +-
.../torproject/onionoo/docs/NodeStatusTest.java | 112 ++++++++++++++++++++
web/protocol.html | 34 ++++++
10 files changed, 326 insertions(+), 52 deletions(-)
diff --git a/build.xml b/build.xml
index f82b49d..03a97f1 100644
--- a/build.xml
+++ b/build.xml
@@ -1,6 +1,6 @@
<project default="dist" name="onionoo" basedir=".">
- <property name="onionoo.protocol.version" value="2.5"/>
+ <property name="onionoo.protocol.version" value="2.6"/>
<property name="release.version"
value="${onionoo.protocol.version}.0"/>
<property name="javasources" value="src/main/java"/>
diff --git a/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java b/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java
index aa410d8..69d8efe 100644
--- a/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java
+++ b/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java
@@ -289,6 +289,14 @@ public class DetailsDocument extends Document {
return this.family;
}
+ private SortedSet<String> alleged_family;
+ public void setAllegedFamily(SortedSet<String> allegedFamily) {
+ this.alleged_family = allegedFamily;
+ }
+ public SortedSet<String> getAllegedFamily() {
+ return this.alleged_family;
+ }
+
private SortedSet<String> effective_family;
public void setEffectiveFamily(SortedSet<String> effectiveFamily) {
this.effective_family = effectiveFamily;
@@ -297,6 +305,14 @@ public class DetailsDocument extends Document {
return this.effective_family;
}
+ private SortedSet<String> indirect_family;
+ public void setIndirectFamily(SortedSet<String> indirectFamily) {
+ this.indirect_family = indirectFamily;
+ }
+ public SortedSet<String> getIndirectFamily() {
+ return this.indirect_family;
+ }
+
private Float consensus_weight_fraction;
public void setConsensusWeightFraction(Float consensusWeightFraction) {
if (consensusWeightFraction == null ||
diff --git a/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java b/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java
index 0a97fd3..62e621b 100644
--- a/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java
+++ b/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java
@@ -110,6 +110,14 @@ public class DetailsStatus extends Document {
return this.family;
}
+ private SortedSet<String> alleged_family;
+ public void setAllegedFamily(SortedSet<String> allegedFamily) {
+ this.alleged_family = allegedFamily;
+ }
+ public SortedSet<String> getAllegedFamily() {
+ return this.alleged_family;
+ }
+
private SortedSet<String> effective_family;
public void setEffectiveFamily(SortedSet<String> effectiveFamily) {
this.effective_family = effectiveFamily;
@@ -118,6 +126,14 @@ public class DetailsStatus extends Document {
return this.effective_family;
}
+ private SortedSet<String> indirect_family;
+ public void setIndirectFamily(SortedSet<String> indirectFamily) {
+ this.indirect_family = indirectFamily;
+ }
+ public SortedSet<String> getIndirectFamily() {
+ return this.indirect_family;
+ }
+
private Map<String, List<String>> exit_policy_v6_summary;
public void setExitPolicyV6Summary(
Map<String, List<String>> exitPolicyV6Summary) {
diff --git a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java
index 51fc678..6e51190 100644
--- a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java
+++ b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java
@@ -46,13 +46,12 @@ public class NodeStatus extends Document {
return this.contact;
}
- private String[] familyFingerprints;
- public void setFamilyFingerprints(
- SortedSet<String> familyFingerprints) {
- this.familyFingerprints = collectionToStringArray(familyFingerprints);
+ private String[] declaredFamily;
+ public void setDeclaredFamily(SortedSet<String> declaredFamily) {
+ this.declaredFamily = collectionToStringArray(declaredFamily);
}
- public SortedSet<String> getFamilyFingerprints() {
- return stringArrayToSortedSet(this.familyFingerprints);
+ public SortedSet<String> getDeclaredFamily() {
+ return stringArrayToSortedSet(this.declaredFamily);
}
private static String[] collectionToStringArray(
@@ -301,7 +300,8 @@ public class NodeStatus extends Document {
return this.lastRdnsLookup;
}
- /* Computed effective family */
+ /* Computed effective and extended family and derived subsets alleged
+ * and indirect family */
private String[] effectiveFamily;
public void setEffectiveFamily(SortedSet<String> effectiveFamily) {
@@ -311,6 +311,28 @@ public class NodeStatus extends Document {
return stringArrayToSortedSet(this.effectiveFamily);
}
+ private String[] extendedFamily;
+ public void setExtendedFamily(SortedSet<String> extendedFamily) {
+ this.extendedFamily = collectionToStringArray(extendedFamily);
+ }
+ public SortedSet<String> getExtendedFamily() {
+ return stringArrayToSortedSet(this.extendedFamily);
+ }
+
+ public SortedSet<String> getAllegedFamily() {
+ SortedSet<String> allegedFamily = new TreeSet<String>(
+ stringArrayToSortedSet(this.declaredFamily));
+ allegedFamily.removeAll(stringArrayToSortedSet(this.effectiveFamily));
+ return allegedFamily;
+ }
+
+ public SortedSet<String> getIndirectFamily() {
+ SortedSet<String> indirectFamily = new TreeSet<String>(
+ stringArrayToSortedSet(this.extendedFamily));
+ indirectFamily.removeAll(stringArrayToSortedSet(this.effectiveFamily));
+ return indirectFamily;
+ }
+
/* Constructor and (de-)serialization methods: */
public NodeStatus(String fingerprint) {
@@ -412,17 +434,33 @@ public class NodeStatus extends Document {
nodeStatus.setRecommendedVersion(parts[21].equals("true"));
}
if (!parts[22].equals("null")) {
- SortedSet<String> familyFingerprints = new TreeSet<String>();
- for (String familyMember : parts[22].split("[;:]")) {
- if (familyMember.length() > 0) {
- familyFingerprints.add(familyMember);
- }
+ /* The relay's family is encoded in three ':'-separated groups:
+ * 0. declared, not-mutually agreed family members,
+ * 1. effective, mutually agreed family members, and
+ * 2. indirect members that can be reached via others only.
+ * Each group contains zero or more ';'-separated fingerprints. */
+ String[] groups = parts[22].split(":", -1);
+ SortedSet<String> allegedFamily = new TreeSet<String>(),
+ effectiveFamily = new TreeSet<String>(),
+ indirectFamily = new TreeSet<String>();
+ if (groups[0].length() > 0) {
+ allegedFamily.addAll(Arrays.asList(groups[0].split(";")));
+ }
+ if (groups.length > 1 && groups[1].length() > 0) {
+ effectiveFamily.addAll(Arrays.asList(groups[1].split(";")));
}
- nodeStatus.setFamilyFingerprints(familyFingerprints);
- if (parts[22].contains(":")) {
- nodeStatus.setEffectiveFamily(new TreeSet<String>(
- Arrays.asList(parts[22].split(":", 2)[1].split(";"))));
+ if (groups.length > 2 && groups[2].length() > 0) {
+ indirectFamily.addAll(Arrays.asList(groups[2].split(";")));
}
+ SortedSet<String> declaredFamily = new TreeSet<String>();
+ declaredFamily.addAll(allegedFamily);
+ declaredFamily.addAll(effectiveFamily);
+ nodeStatus.setDeclaredFamily(declaredFamily);
+ nodeStatus.setEffectiveFamily(effectiveFamily);
+ SortedSet<String> extendedFamily = new TreeSet<String>();
+ extendedFamily.addAll(effectiveFamily);
+ extendedFamily.addAll(indirectFamily);
+ nodeStatus.setExtendedFamily(extendedFamily);
}
return nodeStatus;
} catch (NumberFormatException e) {
@@ -483,16 +521,9 @@ public class NodeStatus extends Document {
sb.append("\t" + (this.contact != null ? this.contact : ""));
sb.append("\t" + (this.recommendedVersion == null ? "null" :
this.recommendedVersion ? "true" : "false"));
- if (this.effectiveFamily != null && this.effectiveFamily.length > 0) {
- SortedSet<String> mutual = this.getEffectiveFamily();
- SortedSet<String> notMutual = new TreeSet<String>(
- this.getFamilyFingerprints());
- notMutual.removeAll(mutual);
- sb.append("\t" + StringUtils.join(notMutual, ";") + ":"
- + StringUtils.join(mutual, ";"));
- } else {
- sb.append("\t" + StringUtils.join(this.familyFingerprints, ";"));
- }
+ sb.append("\t" + StringUtils.join(this.getAllegedFamily(), ";") + ":"
+ + StringUtils.join(this.getEffectiveFamily(), ";") + ":"
+ + StringUtils.join(this.getIndirectFamily(), ";"));
return sb.toString();
}
}
diff --git a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
index ffd6ddb..b8aafc3 100644
--- a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
+++ b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
@@ -70,7 +70,7 @@ public class ResponseBuilder {
return this.charsWritten;
}
- private static final String PROTOCOL_VERSION = "2.5";
+ private static final String PROTOCOL_VERSION = "2.6";
private static final String NEXT_MAJOR_VERSION_SCHEDULED = null;
@@ -271,6 +271,10 @@ public class ResponseBuilder {
dd.setEffectiveFamily(detailsDocument.getEffectiveFamily());
} else if (field.equals("measured")) {
dd.setMeasured(detailsDocument.getMeasured());
+ } else if (field.equals("alleged_family")) {
+ dd.setAllegedFamily(detailsDocument.getAllegedFamily());
+ } else if (field.equals("indirect_family")) {
+ dd.setIndirectFamily(detailsDocument.getIndirectFamily());
}
}
/* Don't escape HTML characters, like < and >, contained in
diff --git a/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java b/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java
index fdcd419..d28e249 100644
--- a/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java
+++ b/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java
@@ -140,7 +140,7 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
}
}
- private Map<String, SortedSet<String>> familyFingerprints =
+ private Map<String, SortedSet<String>> declaredFamilies =
new HashMap<String, SortedSet<String>>();
private void processRelayServerDescriptor(
@@ -174,14 +174,16 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
detailsStatus.setPlatform(descriptor.getPlatform());
detailsStatus.setFamily(descriptor.getFamilyEntries());
if (descriptor.getFamilyEntries() != null) {
- SortedSet<String> noPrefixUpperCase = new TreeSet<String>();
+ SortedSet<String> declaredFamily = new TreeSet<String>();
for (String familyMember : descriptor.getFamilyEntries()) {
if (familyMember.startsWith("$") && familyMember.length() >= 41) {
- noPrefixUpperCase.add(
+ declaredFamily.add(
familyMember.substring(1, 41).toUpperCase());
+ } else {
+ declaredFamily.add(familyMember);
}
}
- this.familyFingerprints.put(fingerprint, noPrefixUpperCase);
+ this.declaredFamilies.put(fingerprint, declaredFamily);
}
if (descriptor.getIpv6DefaultPolicy() != null &&
(descriptor.getIpv6DefaultPolicy().equals("accept") ||
@@ -382,8 +384,8 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
log.info("Looked up cities and ASes");
this.calculatePathSelectionProbabilities();
log.info("Calculated path selection probabilities");
- this.computeEffectiveFamilies();
- log.info("Computed effective families");
+ this.computeEffectiveAndExtendedFamilies();
+ log.info("Computed effective and extended families");
this.finishReverseDomainNameLookups();
log.info("Finished reverse domain name lookups");
this.updateNodeDetailsStatuses();
@@ -479,10 +481,12 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
}
updatedNodeStatus.setLastRdnsLookup(
nodeStatus.getLastRdnsLookup());
- updatedNodeStatus.setFamilyFingerprints(
- nodeStatus.getFamilyFingerprints());
+ updatedNodeStatus.setDeclaredFamily(
+ nodeStatus.getDeclaredFamily());
updatedNodeStatus.setEffectiveFamily(
nodeStatus.getEffectiveFamily());
+ updatedNodeStatus.setExtendedFamily(
+ nodeStatus.getExtendedFamily());
} else {
updatedNodeStatus = nodeStatus;
this.knownNodes.put(fingerprint, nodeStatus);
@@ -511,13 +515,13 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
* safe to override whatever is in node statuses. */
for (Map.Entry<String, NodeStatus> e : this.knownNodes.entrySet()) {
String fingerprint = e.getKey();
- if (this.familyFingerprints.containsKey(fingerprint)) {
+ if (this.declaredFamilies.containsKey(fingerprint)) {
NodeStatus nodeStatus = e.getValue();
- nodeStatus.setFamilyFingerprints(
- this.familyFingerprints.get(fingerprint));
+ nodeStatus.setDeclaredFamily(
+ this.declaredFamilies.get(fingerprint));
}
}
- this.familyFingerprints.clear();
+ this.declaredFamilies.clear();
}
/* Step 3: perform lookups and calculate path selection
@@ -664,16 +668,14 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
}
}
- private void computeEffectiveFamilies() {
+ private void computeEffectiveAndExtendedFamilies() {
SortedMap<String, SortedSet<String>> declaredFamilies =
new TreeMap<String, SortedSet<String>>();
for (String fingerprint : this.currentRelays) {
NodeStatus nodeStatus = this.knownNodes.get(fingerprint);
- if (nodeStatus != null &&
- nodeStatus.getFamilyFingerprints() != null &&
- !nodeStatus.getFamilyFingerprints().isEmpty()) {
- declaredFamilies.put(fingerprint,
- nodeStatus.getFamilyFingerprints());
+ if (nodeStatus != null && nodeStatus.getDeclaredFamily() != null &&
+ !nodeStatus.getDeclaredFamily().isEmpty()) {
+ declaredFamilies.put(fingerprint, nodeStatus.getDeclaredFamily());
}
}
SortedMap<String, SortedSet<String>> effectiveFamilies =
@@ -694,17 +696,55 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
effectiveFamilies.put(fingerprint, effectiveFamily);
}
}
+ SortedMap<String, SortedSet<String>> extendedFamilies =
+ new TreeMap<String, SortedSet<String>>();
+ SortedSet<String> visited = new TreeSet<String>();
+ for (String fingerprint : effectiveFamilies.keySet()) {
+ if (visited.contains(fingerprint)) {
+ continue;
+ }
+ SortedSet<String> toVisit = new TreeSet<String>();
+ toVisit.add(fingerprint);
+ SortedSet<String> extendedFamily = new TreeSet<String>();
+ while (!toVisit.isEmpty()) {
+ String visiting = toVisit.first();
+ toVisit.remove(visiting);
+ extendedFamily.add(visiting);
+ SortedSet<String> members = effectiveFamilies.get(visiting);
+ if (members != null) {
+ for (String member : members) {
+ if (!toVisit.contains(member) && !visited.contains(member)) {
+ toVisit.add(member);
+ }
+ }
+ }
+ visited.add(visiting);
+ }
+ if (extendedFamily.size() > 1) {
+ for (String member : extendedFamily) {
+ SortedSet<String> extendedFamilyWithoutMember =
+ new TreeSet<String>(extendedFamily);
+ extendedFamilyWithoutMember.remove(member);
+ extendedFamilies.put(member, extendedFamilyWithoutMember);
+ }
+ }
+ }
for (String fingerprint : this.currentRelays) {
NodeStatus nodeStatus = this.knownNodes.get(fingerprint);
if (nodeStatus == null) {
continue;
}
- if (effectiveFamilies.containsKey(fingerprint)) {
+ if (effectiveFamilies.containsKey(fingerprint) ||
+ extendedFamilies.containsKey(fingerprint)) {
nodeStatus.setEffectiveFamily(effectiveFamilies.get(fingerprint));
+ nodeStatus.setExtendedFamily(extendedFamilies.get(fingerprint));
this.updatedNodes.add(fingerprint);
- } else if (nodeStatus.getEffectiveFamily() != null ||
- !nodeStatus.getEffectiveFamily().isEmpty()) {
+ } else if ((nodeStatus.getEffectiveFamily() != null &&
+ !nodeStatus.getEffectiveFamily().isEmpty()) ||
+ (nodeStatus.getIndirectFamily() != null &&
+ !nodeStatus.getIndirectFamily().isEmpty())) {
nodeStatus.setEffectiveFamily(null);
+ nodeStatus.setExtendedFamily(null);
this.updatedNodes.add(fingerprint);
}
}
@@ -774,7 +814,9 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,
nodeStatus.getOrAddresses());
nodeStatus.setExitAddresses(exitAddressesWithoutOrAddresses);
+ detailsStatus.setAllegedFamily(nodeStatus.getAllegedFamily());
detailsStatus.setEffectiveFamily(nodeStatus.getEffectiveFamily());
+ detailsStatus.setIndirectFamily(nodeStatus.getIndirectFamily());
if (this.geoIpLookupResults.containsKey(fingerprint)) {
LookupResult lookupResult = this.geoIpLookupResults.get(
diff --git a/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java
index 6f60958..6747c2c 100644
--- a/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java
+++ b/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java
@@ -112,6 +112,18 @@ public class DetailsDocumentWriter implements DocumentWriter {
detailsDocument.setContact(detailsStatus.getContact());
detailsDocument.setPlatform(detailsStatus.getPlatform());
detailsDocument.setFamily(detailsStatus.getFamily());
+ if (detailsStatus.getAllegedFamily() != null &&
+ !detailsStatus.getAllegedFamily().isEmpty()) {
+ SortedSet<String> allegedFamily = new TreeSet<String>();
+ for (String familyMember : detailsStatus.getAllegedFamily()) {
+ if (familyMember.length() >= 40) {
+ allegedFamily.add("$" + familyMember);
+ } else {
+ allegedFamily.add(familyMember);
+ }
+ }
+ detailsDocument.setAllegedFamily(allegedFamily);
+ }
if (detailsStatus.getEffectiveFamily() != null &&
!detailsStatus.getEffectiveFamily().isEmpty()) {
SortedSet<String> effectiveFamily = new TreeSet<String>();
@@ -120,6 +132,14 @@ public class DetailsDocumentWriter implements DocumentWriter {
}
detailsDocument.setEffectiveFamily(effectiveFamily);
}
+ if (detailsStatus.getIndirectFamily() != null &&
+ !detailsStatus.getIndirectFamily().isEmpty()) {
+ SortedSet<String> indirectFamily = new TreeSet<String>();
+ for (String familyMember : detailsStatus.getIndirectFamily()) {
+ indirectFamily.add("$" + familyMember);
+ }
+ detailsDocument.setIndirectFamily(indirectFamily);
+ }
detailsDocument.setExitPolicyV6Summary(
detailsStatus.getExitPolicyV6Summary());
detailsDocument.setHibernating(detailsStatus.getHibernating());
diff --git a/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java
index ddb3003..1be752a 100644
--- a/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java
+++ b/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java
@@ -84,13 +84,12 @@ public class SummaryDocumentWriter implements DocumentWriter {
long firstSeenMillis = nodeStatus.getFirstSeenMillis();
String aSNumber = nodeStatus.getASNumber();
String contact = nodeStatus.getContact();
- SortedSet<String> familyFingerprints =
- nodeStatus.getFamilyFingerprints();
+ SortedSet<String> declaredFamily = nodeStatus.getDeclaredFamily();
SortedSet<String> effectiveFamily = nodeStatus.getEffectiveFamily();
SummaryDocument summaryDocument = new SummaryDocument(isRelay,
nickname, fingerprint, addresses, lastSeenMillis, running,
relayFlags, consensusWeight, countryCode, firstSeenMillis,
- aSNumber, contact, familyFingerprints, effectiveFamily);
+ aSNumber, contact, declaredFamily, effectiveFamily);
if (this.documentStore.store(summaryDocument, fingerprint)) {
this.writtenDocuments++;
};
diff --git a/src/test/java/org/torproject/onionoo/docs/NodeStatusTest.java b/src/test/java/org/torproject/onionoo/docs/NodeStatusTest.java
new file mode 100644
index 0000000..e3a6fca
--- /dev/null
+++ b/src/test/java/org/torproject/onionoo/docs/NodeStatusTest.java
@@ -0,0 +1,112 @@
+package org.torproject.onionoo.docs;
+
+import static org.junit.Assert.assertEquals;
+
+import java.util.Arrays;
+import java.util.SortedSet;
+import java.util.TreeSet;
+
+import org.junit.Test;
+
+public class NodeStatusTest {
+
+ private static final String GABELMOO_NODE_STATUS =
+ "r\tgabelmoo\tF2044413DAC2E02E3D6BCF4735A19BCA1DE97281\t"
+ + "131.188.40.189;[2001:638:a000:4140::ffff:189]:443;\t2015-08-13\t"
+ + "08:00:00\t443\t80\tAuthority,HSDir,Running,Stable,V2Dir,Valid\t"
+ + "20\tde\t\t-1\treject\t1-65535\t2015-08-04\t12:00:00\t"
+ + "2015-08-04\t12:00:00\tAS680\t"
+ + "4096r/261c5fbe77285f88fb0c343266c8c2d7c5aa446d sebastian hahn "
+ + "<tor(a)sebastianhahn.net> - 12nbrajag5u3llwetsf7fstcdaz32mu5cn\t"
+ + "true\tnull";
+
+ private void assertFamiliesCanBeDeSerialized(
+ String[] declaredFamilyArray, String[] effectiveFamilyArray,
+ String[] extendedFamilyArray) {
+ SortedSet<String> declaredFamily = new TreeSet<String>(
+ Arrays.asList(declaredFamilyArray));
+ SortedSet<String> effectiveFamily = new TreeSet<String>(
+ Arrays.asList(effectiveFamilyArray));
+ SortedSet<String> extendedFamily = new TreeSet<String>(
+ Arrays.asList(extendedFamilyArray));
+ NodeStatus nodeStatus = NodeStatus.fromString(GABELMOO_NODE_STATUS);
+ nodeStatus.setDeclaredFamily(declaredFamily);
+ nodeStatus.setEffectiveFamily(effectiveFamily);
+ nodeStatus.setExtendedFamily(extendedFamily);
+ String serialized = nodeStatus.toString();
+ NodeStatus deserialized = NodeStatus.fromString(serialized);
+ assertEquals("Declared families don't match", declaredFamily,
+ deserialized.getDeclaredFamily());
+ assertEquals("Effective families don't match", effectiveFamily,
+ deserialized.getEffectiveFamily());
+ assertEquals("Extended families don't match", extendedFamily,
+ deserialized.getExtendedFamily());
+ }
+
+ private final String A = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+ B = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+ C = "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC",
+ D = "DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD",
+ E = "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE",
+ F = "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",
+ N = "nickname";
+
+ @Test
+ public void testFamiliesEmpty() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] {}, new String[] {}, new String[] {});
+ }
+
+ @Test
+ public void testFamiliesOneNotMutual() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A }, new String[] {}, new String[] {});
+ }
+
+ @Test
+ public void testFamiliesTwoNotMutual() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A, B }, new String[] {}, new String[] {});
+ }
+
+ @Test
+ public void testFamiliesOneNotMutualOneMutual() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A, B }, new String[] { B }, new String[] { B });
+ }
+
+ @Test
+ public void testFamiliesOneMutualOneIndirect() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A }, new String[] { A }, new String[] { A, B });
+ }
+
+ @Test
+ public void testFamiliesOneNotMutualOneIndirect() {
+ /* This case is special, because B is both in this relay's alleged and
+ * extended family, but it's not in an effective family relationship
+ * with this relay. It's a valid case, because B can be in a mutual
+ * family relationship with A. */
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A, B }, new String[] { A }, new String[] { A, B });
+ }
+
+ @Test
+ public void testFamiliesOneNotMutualOneMutualOneIndirect() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A, B }, new String[] { B }, new String[] { B, C });
+ }
+
+ @Test
+ public void testFamiliesTwoNotMutualTwoMutualTwoIndirect() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { A, B, C, D }, new String[] { C, D },
+ new String[] { C, D, E, F });
+ }
+
+ @Test
+ public void testFamiliesNickname() {
+ assertFamiliesCanBeDeSerialized(
+ new String[] { N }, new String[] {}, new String[] {});
+ }
+}
diff --git a/web/protocol.html b/web/protocol.html
index 6681faf..ab06fe9 100644
--- a/web/protocol.html
+++ b/web/protocol.html
@@ -180,6 +180,9 @@ documents on March 22, 2015.</li>
details documents on July 3, 2015.</li>
<li><strong>2.5</strong>: Added optional "measured" field to details
documents on August 13, 2015.</li>
+<li><strong>2.6</strong>: Added optional "alleged_family" and
+"indirect_family" fields and deprecated optional "family" field in details
+documents on August 25, 2015.</li>
</ul>
</div> <!-- box -->
@@ -1185,6 +1188,7 @@ relay part of their family, so that the effective family of this relay may
be smaller.
Omitted if empty or if descriptor containing this information cannot be
found.
+<font color="blue">Deprecated on August 25, 2015.</font>
</p>
</li>
@@ -1195,6 +1199,8 @@ found.
<p>
Array of $-prefixed fingerprints of relays that are in an effective,
mutual family relationship with this relay.
+These relays are part of this relay's family and they consider this relay
+to be part of their family.
Omitted if empty or if descriptor containing this information cannot be
found.
<font color="blue">Added on July 3, 2015.</font>
@@ -1202,6 +1208,34 @@ found.
</li>
<li>
+<b><font color="blue">alleged_family</font></b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of $-prefixed fingerprints of relays that are not in an effective,
+mutual family relationship with this relay.
+These relays are part of this relay's family but they don't consider this
+relay to be part of their family.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+<font color="blue">Added on August 25, 2015.</font>
+</p>
+</li>
+
+<li>
+<b><font color="blue">indirect_family</font></b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+Array of $-prefixed fingerprints of relays that are not in an effective,
+mutual family relationship with this relay but that can be reached by
+following effective, mutual family relationships starting at this relay.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+<font color="blue">Added on August 25, 2015.</font>
+</p>
+</li>
+
+<li>
<b>consensus_weight_fraction</b>
<code class="typeof">number</code>
<span class="required-false">optional</span>
