Develop

.github/workflows/release.yml

@@ -0,0 +1,91 @@
+# Create a version tag and GitHub Release for the proxy Go module.
+# Run from Actions → Release → Run workflow (typically on develop or master).
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version (e.g. v0.1.0 or 0.1.0)"
+        required: true
+        type: string
+      prerelease:
+        description: "Mark GitHub Release as prerelease"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # Need write access to push the tag back to the repo.
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Normalize version
+        id: ver
+        run: |
+          set -euo pipefail
+          RAW="${{ inputs.version }}"
+          RAW="${RAW#v}"
+          if [[ ! "$RAW" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Invalid version: ${{ inputs.version }} (expected semver like v0.1.0)"
+            exit 1
+          fi
+          TAG="v${RAW}"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "Using tag ${TAG}"
+
+      - name: Ensure tag does not already exist
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.ver.outputs.tag }}"
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag ${TAG} already exists"
+            exit 1
+          fi
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+            echo "Tag ${TAG} already exists on origin"
+            exit 1
+          fi
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Test
+        run: go test ./... -count=1
+
+      - name: Create and push tag
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.ver.outputs.tag }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release ${TAG}"
+          git push origin "$TAG"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.ver.outputs.tag }}"
+          ARGS=(release create "$TAG"
+            --title "$TAG"
+            --generate-notes
+            --target "${{ github.sha }}"
+          )
+          if [[ "${{ inputs.prerelease }}" == "true" ]]; then
+            ARGS+=(--prerelease)
+          fi
+          gh "${ARGS[@]}"

README.md

@@ -27,3 +27,11 @@ Name-based egress via HTTP CONNECT over the mesh (underlay remains WireGuard). S
 ```bash
 go test ./... -race
 ```
+
+## Release
+
+From GitHub Actions → **Release** → **Run workflow**: enter a semver (`v0.1.0` or `0.1.0`). The workflow runs tests, pushes an annotated tag, and creates a GitHub Release (notes auto-generated). Consumers can then:
+
+```bash
+go get github.com/gravitl/proxy/l7@v0.1.0
+```

docs/PROXY_WSS_UPLINK.md

@@ -0,0 +1,68 @@
+# TCP Uplink WebSocket Transport
+
+Netmaker TCP uplink uses **WebSocket** (`/uplink/v1`) as the application transport in every deployment. TLS termination is configured independently via `tcp_proxy_tls_mode`.
+
+## TLS modes
+
+| Mode | Value | Behavior |
+|------|-------|----------|
+| Self-signed (default) | `selfsigned` | Uplink terminates TLS with a persisted self-signed certificate and serves `wss://` |
+| Reverse proxy | `proxy` | Upstream reverse proxy terminates TLS; uplink serves plain `ws://` on an internal bind |
+
+Invalid modes fail startup/API with: `unsupported uplink TLS mode: …`
+
+## Standalone gateway
+
+```json
+{
+  "enabled": true,
+  "listen_port": 443,
+  "tls_mode": "selfsigned"
+}
+```
+
+Client dials: `wss://<gateway-ip>:443/uplink/v1`
+
+## Behind a reverse proxy
+
+```json
+{
+  "enabled": true,
+  "listen_port": 51822,
+  "listen_addr": "127.0.0.1",
+  "tls_mode": "proxy",
+  "public_hostname": "gateway.example.com"
+}
+```
+
+- `listen_port` / `listen_addr` are the **backend** bind (what Caddy/nginx proxies to).
+- Set gateway `tcp_proxy_public_hostname` (e.g. `gateway.example.com`) so clients dial the reverse-proxy DNS name.
+- Clients are published `wss://<public-hostname-or-ip>:<public-port>/uplink/v1` in `proxy` mode.
+- Public port defaults to **443** (server env `TCP_PROXY_PUBLIC_PORT` can override).
+- The reverse proxy must expose that public port and forward `/uplink/v1` to the backend.
+
+Generic reverse-proxy route (works with Caddy, nginx, HAProxy, Ingress, etc.):
+
+```text
+:443 /uplink/v1  →  127.0.0.1:51822
+```
+
+Example Caddy (documentation only — not required by the implementation):
+
+```caddy
+gateway.example.com {
+    reverse_proxy /uplink/v1 127.0.0.1:51822
+}
+```
+
+Client dials: `wss://gateway.example.com:443/uplink/v1` (falls back to gateway IP if hostname unset)
+
+## Client trust
+
+- Public / reverse-proxy certificates: normal system TLS verification
+- Self-signed gateways: SHA-256 leaf fingerprint published as `tcp_proxy_cert_fingerprint`
+- Temporary legacy: IP dial without fingerprint may skip verify (deprecated)
+
+## Origin policy
+
+Netclient is a machine client and typically sends no browser `Origin` header. The uplink WebSocket upgrader accepts missing Origin; authentication remains the HELLO/WG-proof security boundary.

go.mod

@@ -1,3 +1,5 @@
 module github.com/gravitl/proxy
 
 go 1.22
+
+require github.com/gorilla/websocket v1.5.3

go.sum

@@ -0,0 +1,2 @@
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=