Merge branch 'tunnel' into master

Author: meethigher

README.md

@@ -1,5 +1,5 @@
 # tcp-reverse-proxy
-基于[Vert.x](https://vertx.io/)实现的TCP反向代理与HTTP反向代理。
+基于[Vert.x](https://vertx.io/)实现的HTTP反向代理与TCP反向代理、内网穿透
 
 开发环境
 
@@ -19,14 +19,27 @@
     <artifactId>vertx-core</artifactId>
     <version>4.5.10</version>
 </dependency>
+<!-- 若不使用http反向代理，可不加此依赖 -->
 <dependency>
     <groupId>io.vertx</groupId>
     <artifactId>vertx-web</artifactId>
     <version>4.5.10</version>
 </dependency>
+<!-- 若不想添加日志，可只添加slf4j-api -->
+<dependency>
+    <groupId>ch.qos.logback</groupId>
+    <artifactId>logback-classic</artifactId>
+    <version>1.2.12</version>
+</dependency>
+<!-- 若不使用TCP内网穿透，可不加此依赖 -->
+<dependency>
+    <groupId>com.google.protobuf</groupId>
+    <artifactId>protobuf-javalite</artifactId>
+    <version>4.30.2</version>
+</dependency>
 ```
 
-## TCP反向代理
+## 一、TCP反向代理
 
 实现TCP反向代理：`0.0.0.0:22`↔️`10.0.0.1:8080`
 
@@ -36,7 +49,83 @@ ReverseTcpProxy.create(Vertx.vertx(), "10.0.0.1", 8080)
         .start();
 ```
 
-## HTTP反向代理
+## 二、TCP内网穿透
+
+虚线表示进程内部通信。实线表示外部通信。
+
+一些代码上的设计思路，参考[socket.io-client-java](https://github.com/socketio/socket.io-client-java/blob/socket.io-client-2.1.0/src/main/java/io/socket/client/Socket.java)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant u as User
+    participant dps as DataProxyServer
+    participant ts as TunnelServer
+    participant tc as TunnelClient
+    participant bs as BackendServer
+    
+    ts-->ts: 监听44444端口
+    tc->>ts: 建立控制连接、发送鉴权密钥、申请启用22端口数据服务
+    ts-->ts: 鉴权校验通过
+    ts-->>dps: 你要开启22端口
+    dps-->dps: 监听22端口
+    dps-->>ts: 已开启
+    ts->>tc: 成功
+    tc-->tc: 开启与控制服务的周期心跳
+    loop 控制连接保活
+      tc->>ts: 发送心跳
+      ts->>tc: 响应心跳
+    end
+    u->>dps: 建立数据连接
+    dps-->>ts: 通知
+    ts->>tc: 你需要主动与22数据服务建立数据连接
+    tc->>dps: 建立数据连接
+    note left of dps: 用户连接和数据连接绑定双向生命周期、双向数据传输
+    tc->>bs: 建立后端连接
+    dps->>tc: 成功
+    bs->>tc: 成功
+    note right of tc: 数据连接和后端连接绑定双向生命周期、双向数据传输
+    
+    u->dps: 双向传输
+    dps->tc: 双向传输
+    tc->bs: 双向传输 
+    
+
+```
+
+假如我有一个内网`SSH`服务`10.0.0.10:22`，需要通过`192.168.0.200:22`穿透出去。并且网络条件受限如下
+
+1. `10.0.0.10`可以主动连接`192.168.0.200`
+2. `192.168.0.200`无法主动连接`10.0.0.10`
+3. 只要双方建立连接，即可实现双向数据传输
+
+这就需要TCP内网穿透了。假设你内网穿透使用的控制端口为`44444`。
+
+首先，在`192.168.0.200`这台机器，使用如下代码启动`TunnelServer`
+
+```java
+ReverseTcpProxyTunnelServer.create(Vertx.vertx())
+        .port(44444)
+        // 用于用户连接和数据连接的延迟判定，如果网络较差/DNS解析较慢的情况下，建议将该参数调大
+        .judgeDelay(2000)
+        .start();
+```
+
+在`10.0.0.10`这台机器，使用如下代码启动`TunnelClient`
+
+```java
+ReverseTcpProxyTunnelClient.create(Vertx.vertx())
+        .backendHost("10.0.0.10")
+        .backendPort(22)
+        .dataProxyName("ssh-proxy")
+        .dataProxyHost("192.168.0.200")
+        .dataProxyPort(22)
+        .connect("192.168.0.200", 44444);
+```
+
+
+
+## 三、HTTP反向代理
 
 实现HTTP反向代理，代理路由优先级如下
 

pom.xml

@@ -40,6 +40,12 @@
             <version>4.5.10</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-javalite</artifactId>
+            <version>4.30.2</version>
+            <scope>provided</scope>
+        </dependency>
     </dependencies>
 
 

src/main/java/top/meethigher/proxy/http/ReverseHttpProxy.java

@@ -254,6 +254,10 @@ protected static String generateName() {
     /**
      * 更新路由内数据。
      * 该内容以路由为单位。
+     *
+     * @param route 路由对象
+     * @param key   元数据键
+     * @param value 元数据值
      */
     protected void setRouteMetadata(Route route, String key, Object value) {
         route.putMetadata(key, value == null ? "" : value);
@@ -268,6 +272,10 @@ protected Object getRouteMetadata(Route route, String key) {
     /**
      * 更新请求上下文内数据。
      * 该内容以请求为单位。对于请求来说，是线程安全的。
+     *
+     * @param ctx   路由上下文
+     * @param key   数据键
+     * @param value 数据值
      */
     protected void setContextData(RoutingContext ctx, String key, Object value) {
         ctx.put(key, value == null ? "" : value);
@@ -348,7 +356,12 @@ public ReverseHttpProxy addRoute(ProxyRoute proxyRoute, Integer order) {
     }
 
     /**
-     * order越小，优先级越高
+     * 添加路由
+     *
+     * @param proxyRoute 路由信息
+     * @param order      order越小，优先级越高
+     * @param printLog   true表示打印日志
+     * @return 实例本身
      */
     public ReverseHttpProxy addRoute(
             ProxyRoute proxyRoute,
@@ -406,6 +419,9 @@ public List<Route> getRoutes() {
     /**
      * 将标头转为小写后，判断是否是逐跳标头
      * 时间复杂度为 O(1)
+     *
+     * @param headerName 标头名称
+     * @return 是否是逐跳标头
      */
     protected boolean isHopByHopHeader(String headerName) {
         return headerName != null && HOP_BY_HOP_HEADERS_SET.contains(headerName.toLowerCase());
@@ -414,6 +430,10 @@ protected boolean isHopByHopHeader(String headerName) {
 
     /**
      * 复制请求头。复制的过程中忽略逐跳标头
+     *
+     * @param ctx      路由上下文
+     * @param realReq  真实请求
+     * @param proxyReq 代理请求
      */
     protected void copyRequestHeaders(RoutingContext ctx, HttpServerRequest realReq, HttpClientRequest proxyReq) {
         proxyReq.headers().clear();
@@ -451,6 +471,11 @@ protected void copyRequestHeaders(RoutingContext ctx, HttpServerRequest realReq,
 
     /**
      * 复制响应头。复制的过程中忽略逐跳标头
+     *
+     * @param ctx       路由上下文
+     * @param realReq   真实请求
+     * @param realResp  真实响应
+     * @param proxyResp 代理响应
      */
     protected void copyResponseHeaders(RoutingContext ctx, HttpServerRequest realReq, HttpServerResponse realResp, HttpClientResponse proxyResp) {
         realResp.headers().clear();
@@ -510,6 +535,11 @@ else if ("Location".equalsIgnoreCase(headerName)) {
 
     /**
      * 重写Location
+     *
+     * @param ctx      路由上下文
+     * @param url      原始URL
+     * @param location 重定向位置
+     * @return 重写后的Location
      */
     protected String rewriteLocation(RoutingContext ctx, String url, String location) {
         // 若重定向的地址，在反向代理的范围内，则进行重写
@@ -525,6 +555,12 @@ protected String rewriteLocation(RoutingContext ctx, String url, String location
 
     /**
      * 发起请求Handler
+     *
+     * @param ctx        路由上下文
+     * @param serverReq  服务端请求
+     * @param serverResp 服务端响应
+     * @param proxyUrl   代理URL
+     * @return 异步处理Handler
      */
     protected Handler<AsyncResult<HttpClientResponse>> sendRequestHandler(RoutingContext ctx, HttpServerRequest serverReq, HttpServerResponse serverResp, String proxyUrl) {
         return ar -> {
@@ -560,6 +596,12 @@ protected Handler<AsyncResult<HttpClientResponse>> sendRequestHandler(RoutingCon
 
     /**
      * 建立连接Handler
+     *
+     * @param ctx        路由上下文
+     * @param serverReq  服务端请求
+     * @param serverResp 服务端响应
+     * @param proxyUrl   代理URL
+     * @return 异步处理Handler
      */
     protected Handler<AsyncResult<HttpClientRequest>> connectHandler(RoutingContext ctx, HttpServerRequest serverReq, HttpServerResponse serverResp, String proxyUrl) {
         return ar -> {
@@ -611,6 +653,9 @@ protected void badGateway(RoutingContext ctx, HttpServerResponse serverResp) {
 
     /**
      * 路由处理Handler
+     *
+     * @param httpClient HTTP客户端
+     * @return 路由处理Handler
      */
     protected Handler<RoutingContext> routingContextHandler(HttpClient httpClient) {
         return ctx -> {
@@ -685,6 +730,11 @@ protected Handler<RoutingContext> routingContextHandler(HttpClient httpClient) {
     /**
      * 获取代理后的完整proxyUrl，不区分代理目标路径是否以/结尾。
      * 处理逻辑为删除掉匹配的路径，并将剩下的内容追加到代理目标路径后面。
+     *
+     * @param ctx        路由上下文
+     * @param serverReq  服务端请求
+     * @param serverResp 服务端响应
+     * @return 代理后的完整URL
      */
     protected String getProxyUrl(RoutingContext ctx, HttpServerRequest serverReq, HttpServerResponse serverResp) {
         String targetUrl = getContextData(ctx, P_TARGET_URL).toString();

src/main/java/top/meethigher/proxy/http/UrlParser.java

@@ -7,6 +7,10 @@ public class UrlParser {
 
     /**
      * 在压测时，性能比String.replace略优
+     * @param text 需要替换的文本
+     * @param search 要搜索的字符串
+     * @param replacement 替换的字符串
+     * @return 替换后的文本
      */
     public static String fastReplace(String text, String search, String replacement) {
         if (text == null || search == null || replacement == null || search.isEmpty()) {
@@ -25,6 +29,9 @@ public static String fastReplace(String text, String search, String replacement)
 
     /**
      * 拼接两个uri。不要求uri以"/"结尾
+     * @param uri1 第一个URI字符串
+     * @param uri2 第二个URI字符串
+     * @return 拼接后的URI字符串
      */
     public static String joinURI(String uri1, String uri2) {
         if (uri1.endsWith("/") && uri2.startsWith("/")) {