diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessCounter.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessCounter.java
index 22cceb883ef672a8f04a36e5d0a59cfe3f3fe0b9..4dddb1cf6108d9dd8cf00777980e956476547150 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessCounter.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessCounter.java
@@ -4,14 +4,32 @@ import java.util.List;
import java.util.ArrayList;
import java.util.Collections;
+/**
+ * Counts connection attempts and decides if specified thresholds have been
+ * breached.
+ *
+ * @since 0.9.40
+ */
class AccessCounter {
+ /**
+ * List of timestamps of each connection attempt
+ */
private final List<Long> accesses = new ArrayList<Long>();
+ /**
+ * records that a connection attempt was made
+ *
+ * @param now the current time
+ */
void recordAccess(long now) {
accesses.add(now);
}
+ /**
+ * @param threshold definition of a threshold
+ * @return true if the given threshold has been breached
+ */
boolean isBreached(Threshold threshold) {
if (threshold.getConnections() == 0)
return !accesses.isEmpty();
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessFilter.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessFilter.java
index 4b0c623c2ed06578fd4d6d5478c38184aad7dc62..eff55e38d5003742f891f2d4072c03dbf502a723 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessFilter.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/AccessFilter.java
@@ -22,6 +22,20 @@ import net.i2p.data.Hash;
import net.i2p.i2ptunnel.I2PTunnelTask;
import net.i2p.client.streaming.IncomingConnectionFilter;
+/**
+ * A filter for incoming connections which can be configured
+ * based on access list rules.
+ *
+ * It keeps a track of known destinations - those defined in existing access
+ * lists and unknown ones - those who are not defined in such lists but have
+ * recently attempted to connect to us.
+ *
+ * Every SYNC_INTERVAL seconds the access lists are reloaded from disk which
+ * allows the user to edit them. Also, if any recorders are defined in the
+ * access rules, they will write to disk at such interval.
+ *
+ * @since 0.9.40
+ */
class AccessFilter implements IncomingConnectionFilter {
private static final long PURGE_INTERVAL = 1000;
@@ -40,6 +54,11 @@ class AccessFilter implements IncomingConnectionFilter {
*/
private final Map<Hash, DestTracker> unknownDests = new HashMap<Hash, DestTracker>();
+ /**
+ * @param context the context, used for scheduling and timer purposes
+ * @param definition definition of this filter
+ * @param task the task to query for liveness of the tunnel
+ */
AccessFilter(I2PAppContext context, FilterDefinition definition, I2PTunnelTask task)
throws IOException {
this.context = context;
@@ -56,7 +75,7 @@ class AccessFilter implements IncomingConnectionFilter {
public boolean allowDestination(Destination d) {
Hash hash = d.getHash();
long now = context.clock().now();
- DestTracker tracker = null;
+ DestTracker tracker;
synchronized(knownDests) {
tracker = knownDests.get(hash);
}
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DefinitionParser.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DefinitionParser.java
index e83d0e828b34463091b02d0d96e4b90d0d44997e..c3164af7dc18b00e2e3c3c2774efcc61767c9054 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DefinitionParser.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DefinitionParser.java
@@ -7,8 +7,22 @@ import java.io.File;
import net.i2p.data.DataHelper;
+/**
+ * Utility class for parsing filter definitions
+ *
+ * @since 0.9.40
+ */
class DefinitionParser {
+ /**
+ * Processes an array of String objects containing the human-readable definition of
+ * the filter.
+ *
+ * TODO: format
+ *
+ * @return a FilterDefinition POJO representation for internal use
+ * @throws InvalidDefinitionException if the definition is malformed
+ */
static FilterDefinition parse(String []definition) throws InvalidDefinitionException {
DefinitionBuilder builder = new DefinitionBuilder();
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DestTracker.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DestTracker.java
index 4b034ca75b74d5e8c588eafb65409579a46e956a..79d0c1e6eba425f4c22bfbf55f1ff3e2d672d394 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DestTracker.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/DestTracker.java
@@ -2,12 +2,21 @@ package net.i2p.i2ptunnel.access;
import net.i2p.data.Hash;
+/**
+ * Tracks the connection attempts for a given remote Destination
+ *
+ * @since 0.9.40
+ */
class DestTracker {
private final Hash hash;
private final Threshold threshold;
private final AccessCounter counter;
+ /**
+ * @param hash hash of the remote destination
+ * @param threshold threshold defined in the access rule
+ */
DestTracker(Hash hash, Threshold threshold) {
this.hash = hash;
this.threshold = threshold;
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/ExplicitFilterDefinitionElement.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/ExplicitFilterDefinitionElement.java
index 1ce89c7462c63c534e8101812e97eb9eb8a33712..8c7665f083bb60baf2f3666d7dd2f16e4cdb617d 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/ExplicitFilterDefinitionElement.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/ExplicitFilterDefinitionElement.java
@@ -4,10 +4,21 @@ import java.util.Map;
import net.i2p.data.Hash;
+/**
+ * A filter definition element that includes a single, explicitly defined
+ * remote destination
+ *
+ * @since 0.9.40
+ */
class ExplicitFilterDefinitionElement extends FilterDefinitionElement {
private final Hash hash;
+ /**
+ * @param b32 A string with the .b32 representation of the remote destination
+ * @param threshold threshold to apply to that destination
+ * @throws InvalidDefinitionException if the b32 string is not valid b32
+ */
ExplicitFilterDefinitionElement(String b32, Threshold threshold) throws InvalidDefinitionException {
super(threshold);
this.hash = fromBase32(b32);
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FileFilterDefinitionElement.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FileFilterDefinitionElement.java
index 718bbf75ee76c8d4b7d47de413447985e38040a7..4e7afa97c951bc39ca7c0d17cc8212caf6193268 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FileFilterDefinitionElement.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FileFilterDefinitionElement.java
@@ -9,10 +9,20 @@ import java.io.IOException;
import net.i2p.data.Hash;
+/**
+ * An element of filter definition that reads hashes of remote destinations
+ * from a file.
+ *
+ * @since 0.9.40
+ */
class FileFilterDefinitionElement extends FilterDefinitionElement {
private final File file;
+ /**
+ * @param file file to read the remote destinations from
+ * @param threshold threshold to apply to all those destinations
+ */
FileFilterDefinitionElement(File file, Threshold threshold) {
super(threshold);
this.file = file;
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinition.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinition.java
index 4dcf95485d8bdf5503a136ddaf456f6f6a3a7add..7a389ecb0b5b314e2a7e43663bf2eb1782a60693 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinition.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinition.java
@@ -1,5 +1,12 @@
package net.i2p.i2ptunnel.access;
+/**
+ * Definition of an access filter.
+ *
+ * This POJO contains the parsed representation from the filter definition file.
+ *
+ * @since 0.9.40
+ */
class FilterDefinition {
private final Threshold defaultThreshold;
@@ -7,6 +14,11 @@ class FilterDefinition {
private final Recorder[] recorders;
private final int purgeMinutes;
+ /**
+ * @param defaultThreshold threshold to apply to unknown remote destinations
+ * @param elements the elements defined in the filter definition, if any
+ * @param recorders the recorders defined in the filter definition, if any
+ */
FilterDefinition(Threshold defaultThreshold,
FilterDefinitionElement[] elements,
Recorder[] recorders) {
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinitionElement.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinitionElement.java
index f6bc49c5a5de9ce4874b5a85222cf2c9936a5c07..c9bace8aa7487e162bbe98fdc2029eafc860f33b 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinitionElement.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterDefinitionElement.java
@@ -6,6 +6,11 @@ import java.io.IOException;
import net.i2p.data.Hash;
import net.i2p.data.Base32;
+/**
+ * Base class for elements found in filter definition files
+ *
+ * @since 0.9.40
+ */
abstract class FilterDefinitionElement {
protected final Threshold threshold;
@@ -14,12 +19,19 @@ abstract class FilterDefinitionElement {
this.threshold = threshold;
}
+ /**
+ * Updates the provided map with the hash(es) of remote destinations
+ * mentioned in this element
+ */
abstract void update(Map<Hash, DestTracker> map) throws IOException;
Threshold getThreshold() {
return threshold;
}
+ /**
+ * Utility method to create a Hash object from a .b32 string
+ */
protected static Hash fromBase32(String b32) throws InvalidDefinitionException {
if (!b32.endsWith(".b32.i2p"))
throw new InvalidDefinitionException("Invalid b32 " + b32);
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterFactory.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterFactory.java
index 4333a529a9e0f52ef2cb1bf7b07256437f7013da..54267d6e09a06bd66f46d21759b2fd606f3968c1 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterFactory.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/FilterFactory.java
@@ -12,7 +12,21 @@ import net.i2p.I2PAppContext;
import net.i2p.i2ptunnel.I2PTunnelTask;
import net.i2p.client.streaming.IncomingConnectionFilter;
+/**
+ * Factory for incoming connection filters. Only public class in this package.
+ *
+ * @since 0.9.40
+ */
public class FilterFactory {
+
+ /**
+ * Creates an instance of IncomingConnectionFilter based on the definition
+ * contained in the given file.
+ *
+ * @param context the context this is running in
+ * @param definition file containing the filter definition
+ * @param task the I2PTunnelTask instance to query for liveness
+ */
public static IncomingConnectionFilter createFilter(I2PAppContext context,
File definition,
I2PTunnelTask task)
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/InvalidDefinitionException.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/InvalidDefinitionException.java
index 098aa04cd3abf8a113883761e439843c481d235b..804820c8031cc2eb5f7f36f3423efa3c64c5c2d5 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/InvalidDefinitionException.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/InvalidDefinitionException.java
@@ -1,5 +1,9 @@
package net.i2p.i2ptunnel.access;
+/**
+ * Exception thrown if the filter definition file cannot be
+ * parsed for some reason.
+ */
public class InvalidDefinitionException extends Exception {
public InvalidDefinitionException(String reason) {
super(reason);
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Recorder.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Recorder.java
index cf38607ef4b79d30b8c4a97330a8eb4c0faf8d51..c22cba1092990d40d26d21c91a97c437bf90b24d 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Recorder.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Recorder.java
@@ -2,11 +2,22 @@ package net.i2p.i2ptunnel.access;
import java.io.File;
+/**
+ * Definition of a recorder. If any remote destinations attempt
+ * enough connections to cause a breach of the specified threshold,
+ * their hash will be recorded in the specified file.
+ *
+ * @since 0.9.40
+ */
class Recorder {
private final File file;
private final Threshold threshold;
+ /**
+ * @param file to record hashes of destinations that breach the threshold
+ * @param threshold the threshold that needs to be breached to trigger recording
+ */
Recorder(File file, Threshold threshold) {
this.file = file;
this.threshold = threshold;
diff --git a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Threshold.java b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Threshold.java
index 405694024cb5c0d3edf61803b78122099a7e2279..f55a5f609148b4ad821a4261d485aa5c3606acc2 100644
--- a/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Threshold.java
+++ b/apps/i2ptunnel/java/src/net/i2p/i2ptunnel/access/Threshold.java
@@ -1,8 +1,17 @@
package net.i2p.i2ptunnel.access;
+/**
+ * Definition of a Threshold.
+ *
+ * A Threshold is defined by a number of connections over a period of minutes
+ *
+ * @since 0.9.40
+ */
class Threshold {
+ /** A Threshold that is never breached */
static final Threshold ALLOW = new Threshold(Integer.MAX_VALUE, 1);
+ /** A Threshold that is always breached */
static final Threshold DENY = new Threshold(0, 1);
private final int connections;