From d90fc421fd17526151dec91859ddbc4afb330d1d Mon Sep 17 00:00:00 2001
From: zab2 <zab2@mail.i2p>
Date: Thu, 28 Mar 2019 18:57:42 +0000
Subject: [PATCH] javadoc
---
.../i2p/i2ptunnel/access/AccessCounter.java | 18 ++++++++++++++++
.../i2p/i2ptunnel/access/AccessFilter.java | 21 ++++++++++++++++++-
.../i2ptunnel/access/DefinitionParser.java | 14 +++++++++++++
.../net/i2p/i2ptunnel/access/DestTracker.java | 9 ++++++++
.../ExplicitFilterDefinitionElement.java | 11 ++++++++++
.../access/FileFilterDefinitionElement.java | 10 +++++++++
.../i2ptunnel/access/FilterDefinition.java | 12 +++++++++++
.../access/FilterDefinitionElement.java | 12 +++++++++++
.../i2p/i2ptunnel/access/FilterFactory.java | 14 +++++++++++++
.../access/InvalidDefinitionException.java | 4 ++++
.../net/i2p/i2ptunnel/access/Recorder.java | 11 ++++++++++
.../net/i2p/i2ptunnel/access/Threshold.java | 9 ++++++++
12 files changed, 144 insertions(+), 1 deletion(-)
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 22cceb883e..4dddb1cf61 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 4b0c623c2e..eff55e38d5 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 e83d0e828b..c3164af7dc 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 4b034ca75b..79d0c1e6eb 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 1ce89c7462..8c7665f083 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 718bbf75ee..4e7afa97c9 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 4dcf95485d..7a389ecb0b 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 f6bc49c5a5..c9bace8aa7 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 4333a529a9..54267d6e09 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 098aa04cd3..804820c803 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 cf38607ef4..c22cba1092 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 405694024c..f55a5f6091 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;
--
GitLab