Merge branch 'main' into feature/landing-page

Author: gosunuts

.env.example

@@ -5,6 +5,10 @@ PORTAL_URL=https://localhost:4017
 API_PORT=4017
 SNI_PORT=443
 
+# UDP transport (0 = disabled). Set count > 0 to enable QUIC tunnel + allocate UDP ports starting from 50000.
+# e.g., UDP_PORT_COUNT=10 → ports 50000-50009. Also requires enabling UDP in the admin panel.
+UDP_PORT_COUNT=0
+
 # TLS/ACME and keyless materials
 KEYLESS_DIR=./.portal-certs
 # Supported values: cloudflare, route53
@@ -18,6 +22,7 @@ AWS_ACCESS_KEY_ID=
 AWS_SECRET_ACCESS_KEY=
 AWS_SESSION_TOKEN=
 AWS_REGION=
+AWS_DEFAULT_REGION=
 AWS_HOSTED_ZONE_ID=
 
 # Admin/auth configuration

AGENTS.md

@@ -13,16 +13,17 @@ Architecture, product behavior, and design rationale belong in `docs/architectur
 
 ## Project Principles
 
-- No wrapper functions or helpers without demonstrated value.
-- Prefer fewer concepts and direct code over extra layers, facades, and indirection.
-- Prefer flattening and merging nearby responsibilities over splitting files or packages by default.
-- Remove dead fields, dead methods, dead config, and stale state while touching nearby code.
-- Avoid duplicate normalization, copying, and caching unless aliasing or trust boundaries require it.
-- Keep stable shared contracts, shared constants, and public paths in `types/`, not runtime state, package-local logic, or generic helpers.
+- When caller and callee are both local and no real boundary exists, change both directly; do not preserve local call shapes.
+- If a field, method, wrapper, or abstraction has no clear, current use and does not protect a real boundary, remove it immediately.
+- No wrapper functions or helpers unless they remove real coupling or protect a real boundary.
+- Prefer direct code over layers, facades, and indirection.
+- Prefer flattening and merging nearby responsibilities over splitting by default.
+- Remove dead fields, methods, config, and stale state while touching nearby code.
+- Do not duplicate normalization, validation, or defaulting logic; keep it in a single real owner.
 - Keep shared stateless transforms in `utils/`; keep stateful and domain-shaped logic with the real owner.
-- Resolve complexity in the lowest coherent owner and expose only the minimum necessary surface upward.
-- Shared runtime logic should live in one real owner and be reused, not mirrored by parallel helpers.
-- Prefer not preserving backward compatibility by default, but ask when breaking it may cause real downstream problems.
+- Keep stable shared contracts, constants, and public paths in `types/`, not in runtime or helpers.
+- Resolve complexity in the lowest coherent owner and expose only the minimum surface upward.
+- Shared runtime logic must live in one real owner and be reused, not mirrored.
 
 ## Verification
 

Makefile

@@ -8,6 +8,8 @@ GOIMPORTS_VERSION := v0.41.0
 GOLANGCI_LINT_VERSION := v2.11.1
 GOVULNCHECK_VERSION := v1.1.4
 
+export GOTOOLCHAIN := $(GO_TOOLCHAIN_VERSION)
+
 help:
 	@echo "Available targets:"
 	@echo "  make install           - Install Go developer tools used by this repo"
@@ -21,9 +23,9 @@ help:
 	@echo "  make clean             - Remove build artifacts"
 
 install:
-	GOTOOLCHAIN=$(GO_TOOLCHAIN_VERSION) go install golang.org/x/tools/cmd/goimports@$(GOIMPORTS_VERSION)
-	GOTOOLCHAIN=$(GO_TOOLCHAIN_VERSION) go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
-	GOTOOLCHAIN=$(GO_TOOLCHAIN_VERSION) go install golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)
+	go install golang.org/x/tools/cmd/goimports@$(GOIMPORTS_VERSION)
+	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
+	go install golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)
 
 fmt:
 	gofmt -w .

README.md

@@ -25,6 +25,7 @@ Unlike other tunneling services, Portal is self-hosted and permissionless. You c
 - **End-to-end encryption**: Supports TLS passthrough with relay keyless certificates
 - **Permissionless Hosting**: Anyone can run their own Portal — no approval needed
 - **One-Command Setup**: Expose any local app with a single command
+- **UDP Relay (Experimental)**: Supports raw UDP relay use cases, but the transport model and operational behavior may still change
 
 ## Components
 

cmd/demo-app/handler.go

@@ -8,6 +8,8 @@ import (
 	"time"
 
 	"golang.org/x/net/websocket"
+
+	"github.com/gosuda/portal/v2/sdk"
 )
 
 //go:embed static
@@ -61,3 +63,16 @@ func handleCookies(w http.ResponseWriter, r *http.Request) {
 		"message": "4 cookies set: session_id, auth_token, csrf_token, user_pref",
 	})
 }
+
+func newUDPInfoHandler(exposure *sdk.Exposure) http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		udpAddrs, _ := exposure.WaitDatagramReady(r.Context())
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"message":   "demo-udp is running",
+			"udp_addrs": udpAddrs,
+		})
+	})
+	return mux
+}