feat: initial commit

.github/workflows/docker-image.yaml

@@ -0,0 +1,31 @@
+name: Docker Image
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  build_push:
+    name: Build and Push
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Login to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build Container Image
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64,linux/386,linux/arm64,linux/arm/v7,linux/riscv64
+          push: true
+          tags: ghcr.io/menci/tsukasa:latest

.gitignore

@@ -0,0 +1,28 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+
+# built binary
+/tsukasa

Dockerfile

@@ -0,0 +1,10 @@
+ARG ALPINE_VERSION=3.20
+ARG GOLANG_VERSION=1.22.5
+
+FROM golang:${GOLANG_VERSION}-alpine AS builder
+COPY . /build
+RUN cd /build && go build -o tsukasa
+
+FROM alpine:$ALPINE_VERSION
+COPY --from=builder /build/tsukasa /usr/local/bin/tsukasa
+ENTRYPOINT ["/usr/local/bin/tsukasa"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Menci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,109 @@
+# Tsusaka
+
+Tsusaka is a flexible port forwarder among:
+
+* TCP Ports
+* UNIX Sockets
+* Tailscale TCP Ports (without Tailscale daemon or TUN/TAP permission! This is made possible with [tsnet](https://tailscale.com/kb/1244/tsnet))
+  * If you don't use Tailscale features, it won't initialize Tailscale components and just behaves like a local port forwarder.
+
+It also supports passing the client IP with PROXY protocol (for listening on TCP or Tailscale TCP).
+
+> The name Tsusaka comes from the character **Tenma Tsukasa** from the music visual novel game Project SEKAI. He is a member of the musical show unit "Wonderlands x Showtime". Tsukasa has bucketloads of confidence and loves to be the center of attention. A theater show he saw as a kid impressed him so much that he made it his ultimate goal to become the greatest star in the world.
+
+# Development
+
+Simply build the program with `go build` or build the Docker image with `docker build`.
+
+# Usage
+
+Use with command-line configuration:
+
+```bash
+./tsusaka --ts-hostname Tsusaka \
+          --ts-authkey "$TS_AUTHKEY" \
+          --ts-ephemeral false \
+          --ts-state-dir /var/lib/tailscale \
+          --ts-verbose true \
+          nginx,listen=tailscale://0.0.0.0:80,connect=tcp://127.0.0.1:8080,log-level=info,proxy-protocol \
+          myapp,listen=unix:/var/run/myapp.sock,connect=tailscale://app-hosted-in-tailnet:8080
+```
+
+Or use with configuration file:
+
+```yaml
+# Tailscale configuration is not required and Tailsccale will not be loaded if no services with Tailscale defined.
+tailscale:
+  hostname: Tsusaka
+  # `null` to Use `TS_AUTHKEY` from environment or interactive login.
+  authKey: null
+  ephemeral: false
+  stateDir: /var/lib/tailscale
+  verbose: true
+services:
+  nginx:
+    listen: tailscale://0.0.0.0:80 # Only "0.0.0.0" and "::" allowed in Tailscale listener.
+    connect: tcp://127.0.0.1:8080
+    logLevel: info # "error" / "info" / "verbose". By default "info".
+    proxyProtocol: true # Listening on UNIX socket doesn't support PROXY protocol.
+  myapp:
+    listen: unix:/var/run/myapp.sock
+    connect: tailscale://app-hosted-in-tailnet:8080
+```
+
+Configuration file could be specified with command-line configuration options at the same time.
+
+```bash
+./tsusaka --conf tsusaka.yaml
+```
+
+You can also completely omit Tailscale-related configuration and use Tsukasa as a simple port forward between TCP port and UNIX socket.
+
+# Docker
+
+To use Tsukasa with Docker, it's recommended to start Tsusaka in the host network mode to ensure Tailscale's UDP hole punching to work (Docker's MASQUERADE routing is nearly blocking NAT traversal).
+
+```bash
+docker run \
+  --network=host \
+  -e TS_AUTHKEY="$TS_AUTHKEY" \
+  -v ./tailscale-state:/var/lib/tailscale \
+  ghcr.io/menci/tsusaka \
+  --ts-hostname Tsusaka \
+  --ts-state-dir /var/lib/tailscale \
+  myapp,listen=tcp://0.0.0.0:80,connect=tailscale://app-hosted-in-tailnet:8080
+```
+
+If you want to expose something in a container to your Tailnet, use UNIX socket and a shared volume. Here is an example with [Docker Compose](https://docs.docker.com/compose/). Note that if your application doesn't support listening on a UNIX socket, you can also start another instance of Tsukasa to work as a simple port forwarder from/to UNIX socket and TCP port in the virtual network.
+
+```yaml
+services:
+  initialize:
+    image: busybox
+    command: |
+      # The initialize container empties the shared-sockets directory each time.
+      rm -rf /socket/*
+    volumes:
+      - shared-sockets:/socket
+  tsukasa:
+    image: ghcr.io/menci/tsukasa
+    network_mode: host
+    depends_on:
+      initialize:
+        condition: service_completed_successfully
+    volumes:
+      - tailscale-state:/var/lib/tailscale
+      - shared-sockets:/socket
+    environment:
+      TS_AUTHKEY: ${TAILSCALE_AUTHKEY}
+    command:
+      - app,listen=tailscale://0.0.0.0:80,connect=unix:/socket/app.sock
+  app:
+    image: # Here comes your app, which listens on /socket/app.sock
+    depends_on:
+      initialize:
+        condition: service_completed_successfully
+    volumes:
+      - shared-sockets:/socket
+    command: my_app --listen /socket/app.sock
+```