Initial implementation (#1)

Initial implementation (alpha version)

.gitignore

@@ -0,0 +1,3 @@
+gokv
+bin
+build

Earthfile

@@ -0,0 +1,12 @@
+VERSION 0.6
+
+FROM golang:1.18-bullseye
+
+build:
+  WORKDIR /app
+  COPY go.mod go.sum ./
+  RUN go mod download
+  COPY . .
+  RUN CGO_ENABLED=0 GOOS=linux go build -o ./build/frp-port-keeper ./main.go
+
+  SAVE ARTIFACT build /build AS LOCAL ./build

Justfile

@@ -0,0 +1,8 @@
+@start:
+  watchexec -r -e go -- go run .
+
+@test:
+  go test -v ./...
+
+@build:
+  go build -o bin/frp-port-keeper ./main.go

README.md

@@ -0,0 +1,123 @@
+# frp-port-keeper
+This is a plugin for the awesome [frp reverse proxy](https://github.com/fatedier/frp). 
+
+| :exclamation:  This is an early alpha version which needs further refactoring and improvements (see the [TODO](https://github.com/librepod/frp-port-keeper/tree/develop#todo) section) |
+|------------------------------------------------------------------------------------------------------------------|
+
+
+## What is it for?
+The purpose of this plugin is to keep track of `remote_ports` that are being assigned
+to frp clients upon initial connection to frp server. With this plugin, you can be
+sure that whenever a client connects to an frp server, it would get the same `remote_port`
+number that it was allocated initially.
+
+## Implementation
+frp-port-keeper is a simple server that exposes a `POST /port-registrations` endpoint
+that processes the *NewProxy* payload from the frp server. It is utilizing a simple
+key/value store to track ports and correspinding users. Port allocation data
+persists in json files under the `gokv` folder (The `gokv` folder is created in the
+same directory where the frp-port-keeper executable is located).
+
+### Endpoint details
+This handler is used to allocate ports for the proxy requests storing the mapping of
+`user` param specified in frpc.ini and a free port available.
+
+#### Request
+The hendler expects a JSON payload with the following structure:
+```json
+{
+	"version": "0.1.0",
+	"op": "NewProxy",
+	"content": {
+		"user": {
+			"user": "myiphone",
+		},
+	"proxy_name": "myiphone.my_wireguard_proxy",
+	"proxy_type": "udp"
+	}
+}
+```
+The corresponding frpc.ini config that generates this kind of payload should have 
+the following mandatory parameters specified:
+```ini
+[common]
+server_addr = <your_server_address>
+server_port = 7000
+user = myiphone
+
+[my_wireguard_proxy]
+type = udp
+local_ip = 127.0.0.1
+local_port = 51820
+# remote_port may be omitted since the actual remote_port value will be assigned by the plugin
+# remote_port = 1000
+```
+
+#### Response
+The response body will be a JSON with the following structure:
+
+```json
+{
+	"unchange": false,
+	"content": {
+		"user": {
+			"user": "myiphone",
+		},
+		"proxy_name": "myiphone.my_wireguard_proxy",
+		"proxy_type": "udp",
+		"remote_port": 12345
+	}
+}
+```
+
+If the request is not valid due to missing mandatory fields in frpc.ini config, the
+response will be of status 400 with the following content:
+```json
+{
+	"error":   "VALIDATEERR",
+	"message": "Invalid inputs. Please check your frpc.ini config",
+}
+```
+
+In case if there is an internal error or no more free ports left to allocate,
+the status would be 200 with the following content:
+
+```json
+{
+	"reject": true,
+	"reject_reason": "<reject reason>"
+}
+```
+
+## Requirements
+
+frp version >= v0.48.0
+
+It is possible that the plugin works for older version even though it has not been tested.
+
+## Usage
+ 1. Download the latest frp-port-keeper binary from the [releases page](https://github.com/librepod/frp-port-keeper/releases).
+ 2. Plugin needs to read the `allow_ports` value from the frps.ini file,
+    therefore you need to move the binary to the same folder where you have the 
+    frps.ini file located and have the `allow_ports` value specified under
+    the `common` section.
+ 3. Register plugin in frps.ini like this:
+    ```ini
+    [plugin.frp-port-keeper]
+    addr = 127.0.0.1:8080
+    path = /port-registrations
+    ops = NewProxy
+    ```
+ 4. Run the frp-port-keeper plugin (preferably via a systemd service) and make
+    sure that it works fine (hit the `GET /ping` endpoint).
+ 5. Run the frp server.
+ 6. Profit.
+
+## TODO
+[ ] Pass `allow_ports` param via cli  
+[ ] Add unit tests  
+[ ] Add proper error handling in case if payload is not as expected  
+[ ] Cross compile for other platforms (currently supports only amd64)  
+[ ] Refactor by improving modules/folder structure following golang best practices  
+[ ] Add systemd files and instructions to run the plugin as systemd service
+

docker-compose.yaml

@@ -0,0 +1,71 @@
+volumes:
+  minio_data:
+  redis_data:
+
+services:
+
+  # minio:
+  #   image: quay.io/minio/minio:RELEASE.2023-03-24T21-41-23Z
+  #   restart: always
+  #   ports:
+  #     - 9000:9000
+  #     - 9001:9001
+  #   environment:
+  #     - MINIO_ROOT_USER=minio
+  #     - MINIO_ROOT_PASSWORD=minio123
+  #     - minio_data:/data
+  #   volumes:
+  #   command: 
+  #     - server
+  #     - /data
+  #     - --console-address
+  #     - ":9001"
+
+  redis:
+    image: redis:7-alpine
+    restart: always
+    ports:
+      - 6379:6379
+    command: redis-server --save 60 1 --loglevel warning
+    profiles:
+      - redis
+    volumes: 
+      - redis_data:/data
+
+  redis-commander:
+    container_name: redis-commander
+    image: ghcr.io/joeferner/redis-commander:latest
+    restart: always
+    environment:
+      REDIS_HOSTS: redis
+    ports:
+      - 8081:8081
+    profiles:
+      - redis
+
+  frps:
+    image: snowdreamtech/frps:0.48.0
+    container_name: frps
+    ports:
+      - 7400:7400
+      - 7500:7500
+    volumes:
+      - ./frps.ini:/etc/frp/frps.ini
+    network_mode: host
+    restart: always
+
+  frpc:
+    image: snowdreamtech/frpc:0.48.0
+    container_name: frpc
+    environment:
+      USER: testuser
+    ports:
+      - 7400:7400
+      - 7500:7500
+    depends_on:
+      - frps
+    volumes:
+      - ./frpc.ini:/etc/frp/frpc.ini
+    network_mode: host
+    restart: always
+    command: frpc -c /etc/frp/frpc.ini

frpc.ini

@@ -0,0 +1,23 @@
+[common]
+server_addr = 127.0.0.1
+server_port = 7000
+authentication_method = token
+token = hello
+# your proxy name will be changed to {user}.{proxy}
+user = {{ .Envs.USER }}
+
+# communication protocol used to connect to server
+# supports tcp, kcp, quic and websocket now, default is tcp
+protocol = quic
+# set admin address for control frpc's action by http api such as reload
+admin_addr = 127.0.0.1
+admin_port = 7400
+admin_user = admin
+admin_pwd = admin
+
+[my_wireguard_proxy]
+type = udp
+local_ip = 127.0.0.1
+local_port = 51820
+# The actual remote_port will be assigned by frp-port-keeper
+# remote_port = 1000

frps.ini

@@ -0,0 +1,25 @@
+[common]
+bind_addr = 0.0.0.0
+bind_port = 7000
+authentication_method = token
+token = hello
+
+# only allow frpc to bind ports you list, if you don't specifyecify this, the
+# frp-port-keeper will fall back to 1000-65535 port range
+allow_ports = 6000-7000
+
+# UDP port used for QUIC protocol. if not set, quic is disabled in frps.
+quic_bind_port = 7000
+quic_keepalive_period = 10
+quic_max_idle_timeout = 30
+quic_max_incoming_streams = 100000
+
+# admin UI
+dashboard_port = 7500
+dashboard_user = librepod
+dashboard_pwd = librepod-librepod
+
+[plugin.frp-port-keeper]
+addr = 127.0.0.1:8080
+path = /port-registrations
+ops = NewProxy

go.mod

@@ -0,0 +1,38 @@
+module main
+
+go 1.18
+
+require (
+	github.com/gin-gonic/gin v1.9.0
+	github.com/philippgille/gokv v0.6.0
+	github.com/philippgille/gokv/file v0.6.0
+	gopkg.in/ini.v1 v1.67.0
+)
+
+require (
+	github.com/bytedance/sonic v1.8.0 // indirect
+	github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
+	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.11.2 // indirect
+	github.com/goccy/go-json v0.10.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.0.9 // indirect
+	github.com/leodido/go-urn v1.2.1 // indirect
+	github.com/mattn/go-isatty v0.0.17 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.0.6 // indirect
+	github.com/philippgille/gokv/encoding v0.0.0-20191011213304-eb77f15b9c61 // indirect
+	github.com/philippgille/gokv/util v0.0.0-20191011213304-eb77f15b9c61 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.2.9 // indirect
+	golang.org/x/arch v0.0.0-20210923205945-b76863e36670 // indirect
+	golang.org/x/crypto v0.5.0 // indirect
+	golang.org/x/net v0.7.0 // indirect
+	golang.org/x/sys v0.5.0 // indirect
+	golang.org/x/text v0.7.0 // indirect
+	google.golang.org/protobuf v1.28.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)