add javadoc to magnet filter

i2p · Nov 26, 2022 · 49a0d65 · 49a0d65
1 parent f97bfbf
commit 49a0d65
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 46 deletions.
diff --git a/apps/jetty/java/src/net/i2p/servlet/filters/XI2PHeaderFilter.java b/apps/jetty/java/src/net/i2p/servlet/filters/XI2PHeaderFilter.java
@@ -2,10 +2,6 @@
 
 import java.io.File;
 import java.io.IOException;
-import java.net.URI;
-import java.net.URISyntaxException;
-import java.net.URL;
-import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 import java.util.Properties;
 import javax.servlet.ServletException;

diff --git a/apps/jetty/java/src/net/i2p/servlet/filters/XI2PHostnameFilter.java b/apps/jetty/java/src/net/i2p/servlet/filters/XI2PHostnameFilter.java
@@ -1,23 +1,9 @@
 package net.i2p.servlet.filters;
 
-import java.io.IOException;
-import java.net.URI;
-import java.net.URISyntaxException;
-import java.net.URL;
-import java.net.URLEncoder;
-import java.nio.charset.StandardCharsets;
-import java.util.Properties;
-import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
-import net.i2p.I2PAppContext;
-import net.i2p.I2PException;
-import net.i2p.data.DataHelper;
 import net.i2p.data.Destination;
-import net.i2p.data.PrivateKeyFile;
-import net.i2p.util.Log;
 import org.eclipse.jetty.server.Request;
-import org.eclipse.jetty.server.handler.HandlerWrapper;
 
 /**
  * Adds a header, X-I2P-Hostname, to requests when they come from inside of

diff --git a/apps/jetty/java/src/net/i2p/servlet/filters/XI2PLocationFilter.java b/apps/jetty/java/src/net/i2p/servlet/filters/XI2PLocationFilter.java
@@ -1,29 +1,22 @@
 package net.i2p.servlet.filters;
 
-import java.io.IOException;
 import java.net.URI;
 import java.net.URISyntaxException;
-import java.net.URL;
-import java.net.URLEncoder;
-import java.nio.charset.StandardCharsets;
-import java.util.Properties;
-import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
-import net.i2p.I2PAppContext;
 import net.i2p.data.Destination;
-import net.i2p.util.Log;
 import org.eclipse.jetty.server.Request;
-import org.eclipse.jetty.server.handler.HandlerWrapper;
 
 /**
  * Adds a header, X-I2P-Location, to requests when they do **not** come in on an
  * I2P hostname. This header contains a URL that looks like:
- * [scheme://][i2phostname.i2p][/path][?query] and expresses the I2P-Equivalent
- * URL of the clearnet query. Clients can use this to prompt users to switch
- * from a non-I2P host to an I2P host or to redirect them automatically. It
- * automatically enabled on the default I2P site located on port 7658 by
- * default.
+ * 
+ * [scheme://][i2phostname.i2p][/path][?query]
+ *
+ * This expresses the I2P-Equivalent URL of the clearnet query. Clients can use
+ * this to prompt users to switch from a non-I2P host to an I2P host or to
+ * redirect them automatically. It automatically enabled on the default I2P site
+ * located on port 7658 by default.
  *
  *  @since 0.9.51
  */

diff --git a/apps/jetty/java/src/net/i2p/servlet/filters/XI2PMagnetFilter.java b/apps/jetty/java/src/net/i2p/servlet/filters/XI2PMagnetFilter.java
@@ -1,24 +1,41 @@
 package net.i2p.servlet.filters;
 
-import java.io.IOException;
-import java.net.URI;
-import java.net.URISyntaxException;
-import java.net.URL;
-import java.net.URLEncoder;
-import java.nio.charset.StandardCharsets;
-import java.util.Properties;
-import javax.servlet.ServletException;
+// import java.net.URI;
+// import java.net.URISyntaxException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
-import net.i2p.I2PAppContext;
-import net.i2p.I2PException;
-import net.i2p.data.DataHelper;
 import net.i2p.data.Destination;
-import net.i2p.data.PrivateKeyFile;
-import net.i2p.util.Log;
 import org.eclipse.jetty.server.Request;
-import org.eclipse.jetty.server.handler.HandlerWrapper;
 
+/**
+ * Adds a header, X-I2P-Magnet, to requests when they come in on an I2P
+ * hostname. This header contains a link that looks like:
+ *
+ *   [magnet:]?[xt=urn:btih:[BT_INFO_HASH]]&[tr=[BT_TRACKER_URL]]&[ws=[WEBSEED_PAYLOAD_URL]]
+ *
+ * This corresponds to a torrent where the content is exactly the file being
+ * served, and the webseed URL corresponds exactly to the I2P URL of the
+ * request. The torrent is structured thus:
+ *
+ *   [hostname || base32]/[path/to/url]
+ *
+ * This can be useful for 2 things in particular:
+ *
+ * 1. A user who wishes to mirror the I2P site can use the header to keep the
+ * mirror up-to-date infohash changes, file has changed, delete the old one and
+ * participate in the new swarm
+ * 2. A user who uses an HTTP client which has insight into the torrent
+ * client(Such as I2P in Private Browsing) can optionally replace in-I2P
+ * resources with locally-cached resources from the corresponding I2P torrent.
+ *
+ * This allows sites to be more "Permanent" by spreading their files across
+ * the users, making the files themselves resistant to takedown, and if widely
+ * adopted, would reduce the bandwidth used for serving files over I2P. It may
+ * also cause the downloads to appear differently than HTTP downloads, being
+ * more loosely clustered and out-of-order.
+ *
+ *  @since 0.9.57
+ */
 public class XI2PMagnetFilter extends XI2PHeaderFilter {
   private static final long failTimeout = 600000;