From 2f2828ec48af6e6f7c51758c20374f9ebedd52bb Mon Sep 17 00:00:00 2001 From: yusing Date: Thu, 8 Jan 2026 20:31:44 +0800 Subject: [PATCH] docs(idlewatcher): update README to include loading page and SSE endpoint details - Added information about the loading page (HTML + JS + CSS) and the SSE endpoint for wake events. - Clarified the health monitor implementation and readiness tracking in the architecture overview. - Correct state machine syntax. --- .kilocode/rules/godoxy.md | 92 +++++++++++++++++++++++++++++++++++++ CLAUDE.md | 97 +++++++++++++++++++++++++++++++++++++++ RELEASE_NOTES.md | 36 +++++++++++++++ goutils | 2 +- internal/gopsutil | 2 +- 5 files changed, 227 insertions(+), 2 deletions(-) create mode 100644 .kilocode/rules/godoxy.md create mode 100644 CLAUDE.md create mode 100644 RELEASE_NOTES.md diff --git a/.kilocode/rules/godoxy.md b/.kilocode/rules/godoxy.md new file mode 100644 index 00000000..42901b34 --- /dev/null +++ b/.kilocode/rules/godoxy.md @@ -0,0 +1,92 @@ +# godoxy.md + +## Project Overview + +GoDoxy is a lightweight reverse proxy with WebUI written in Go. It automatically configures routes for Docker containers using labels and provides SSL certificate management, access control, and monitoring capabilities. + +## Development Commands + +You should not run any commands to build or run the project. + +## Documentation + +If `README.md` exists in the package: + +- Read it to understand what the package does and how it works. +- Update it with the changes you made (if any). + +Update the roort `README.md` if relevant. + +## Architecture + +### Core Components + +1. **Main Entry Point** (`cmd/main.go`) + + - Initializes configuration and logging + - Starts the proxy server and WebUI + +2. **Internal Packages** (`internal/`) + + - `config/` - Configuration management with YAML files + - `route/` - HTTP routing and middleware management + - `docker/` - Docker container integration and auto-discovery + - `autocert/` - SSL certificate management with Let's Encrypt + - `acl/` - Access control lists (IP/CIDR, country, timezone) + - `api/` - REST API server with Swagger documentation + - `homepage/` - WebUI dashboard and configuration interface + - `metrics/` - System metrics and uptime monitoring + - `idlewatcher/` - Container idle detection and power management + - `watcher/` - File and container state watchers + +3. **Sub-projects** + - `agent/` - System agent for monitoring containers + - `socket-proxy/` - Docker socket proxy + +### Key Patterns + +- **Task Management**: Use `internal/task/task.go` for managing object lifetimes and background operations +- **Concurrent Maps**: Use `github.com/puzpuzpuz/xsync/v4` instead of maps with mutexes +- **Error Handling**: Use `pkg/gperr` for nested errors with subjects +- **Configuration**: YAML-based configuration in `config/` directory + +## Go Guidelines (from .cursor/rules/go.mdc) + +1. Use builtin `min` and `max` functions instead of custom helpers +2. Prefer range-over-integer syntax (`for i := range 10`) over traditional loops +3. Use `xsync/v4` for concurrent maps instead of map+mutex +4. Beware of variable shadowing when making edits +5. Use `internal/task/task.go` for lifetime management: + - `task.RootTask()` for background operations + - `parent.Subtask()` for nested tasks + - `OnFinished()` and `OnCancel()` callbacks for cleanup +6. Use `pkg/gperr` for complex error scenarios: + - `gperr.Multiline()` for multiple operation attempts + - `gperr.NewBuilder()` for collecting multiple errors + - `gperr.NewGroup() + group.Go()` for collecting errors of multiple concurrent operations + - `gperr.New().Subject()` for errors with subjects + +## Configuration Structure + +- `config/config.yml` - Main configuration +- `config/middlewares/` - HTTP middleware configurations +- `config/*.yml` - Provider and service configurations +- `.env` - Environment variables for ports and settings + +## Testing + +Tests are located in `internal/` packages and can be run with: + +- `make test` - Run all internal package tests +- Individual package tests: `go test ./internal/config/...` +- You MUST use `-ldflags="-checklinkname=0"` otherwise compiler will complain +- prefer `testify/require` over `expect` + +## Docker Integration + +GoDoxy integrates with Docker by: + +1. Listing all containers and reading their labels +2. Creating routes based on `proxy.aliases` label or container name +3. Watching for container/config changes and updating automatically +4. Supporting both Docker and Podman runtimes diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..c30383a3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,97 @@ +______________________________________________________________________ + +## alwaysApply: true + +# Cursor Rules + +## Project Overview + +GoDoxy is a lightweight reverse proxy with WebUI written in Go. It automatically configures routes for Docker containers using labels and provides SSL certificate management, access control, and monitoring capabilities. + +## Development Commands + +You should not run any commands to build or run the project. + +## Documentation + +If `README.md` exists in the package: + +- Read it to understand what the package does and how it works. +- Update it with the changes you made (if any). + +Update the roort `README.md` if relevant. + +## Architecture + +### Core Components + +1. **Main Entry Point** (`cmd/main.go`) + + - Initializes configuration and logging + - Starts the proxy server and WebUI + +1. **Internal Packages** (`internal/`) + + - `config/` - Configuration management with YAML files + - `route/` - HTTP routing and middleware management + - `docker/` - Docker container integration and auto-discovery + - `autocert/` - SSL certificate management with Let's Encrypt + - `acl/` - Access control lists (IP/CIDR, country, timezone) + - `api/` - REST API server with Swagger documentation + - `homepage/` - WebUI dashboard and configuration interface + - `metrics/` - System metrics and uptime monitoring + - `idlewatcher/` - Container idle detection and power management + - `watcher/` - File and container state watchers + +1. **Sub-projects** + + - `agent/` - System agent for monitoring containers + - `socket-proxy/` - Docker socket proxy + +### Key Patterns + +- **Task Management**: Use `internal/task/task.go` for managing object lifetimes and background operations +- **Concurrent Maps**: Use `github.com/puzpuzpuz/xsync/v4` instead of maps with mutexes +- **Error Handling**: Use `pkg/gperr` for nested errors with subjects +- **Configuration**: YAML-based configuration in `config/` directory + +## Go Guidelines (from .cursor/rules/go.mdc) + +1. Use builtin `min` and `max` functions instead of custom helpers +1. Prefer range-over-integer syntax (`for i := range 10`) over traditional loops +1. Use `xsync/v4` for concurrent maps instead of map+mutex +1. Beware of variable shadowing when making edits +1. Use `internal/task/task.go` for lifetime management: + - `task.RootTask()` for background operations + - `parent.Subtask()` for nested tasks + - `OnFinished()` and `OnCancel()` callbacks for cleanup +1. Use `pkg/gperr` for complex error scenarios: + - `gperr.Multiline()` for multiple operation attempts + - `gperr.NewBuilder()` for collecting multiple errors + - `gperr.NewGroup() + group.Go()` for collecting errors of multiple concurrent operations + - `gperr.New().Subject()` for errors with subjects + +## Configuration Structure + +- `config/config.yml` - Main configuration +- `config/middlewares/` - HTTP middleware configurations +- `config/*.yml` - Provider and service configurations +- `.env` - Environment variables for ports and settings + +## Testing + +Tests are located in `internal/` packages and can be run with: + +- `make test` - Run all internal package tests +- Individual package tests: `go test ./internal/config/...` +- You MUST use `-ldflags="-checklinkname=0"` otherwise compiler will complain +- prefer `testify/require` over `expect` + +## Docker Integration + +GoDoxy integrates with Docker by: + +1. Listing all containers and reading their labels +1. Creating routes based on `proxy.aliases` label or container name +1. Watching for container/config changes and updating automatically +1. Supporting both Docker and Podman runtimes diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md new file mode 100644 index 00000000..f554a90d --- /dev/null +++ b/RELEASE_NOTES.md @@ -0,0 +1,36 @@ +# GoDoxy v0.24.0 Release Notes + +## New + +- **Core/Agent**: stream tunneling (TLS/dTLS) with multiplexed TLS port supporting HTTP API and custom stream protocol via ALPN #188 +- **Core/Agent**: TCP and DTLS/UDP stream tunneling with health-check support and runtime capability detection +- **Core/Router**: TCP/UDP route configurable bind address support +- **WebUI/Autocert**: multiple certificates display with Carousel component +- **WebUI/Agent**: stream support status display (TCP/UDP capabilities) + +## Changes + +- **Core/Agent**: refactored HTTP server to use direct setup instead of goutils/server helper +- **Core/HealthCheck**: restructured into dedicated `internal/health/check/` package +- **Core/Dockerfile**: updated to use bun runtime with distroless base images +- **Core/Compose**: updated agent compose template to expose TCP and UDP ports for stream tunneling + +## Fixes + +- **Core/Stream**: fixed stream headers with read deadlines to prevent hangs +- **Core/Icon**: fixed icons provider initialization on first load +- **Core/Docker**: fixed TLS verification and dial handling for custom Docker providers +- **Core/Stream**: fixed hostname handling for stream routes +- **Core/HTTP**: fixed HTTPS redirect for IPv6 with `net.JoinHostPort` +- **Core/Stream**: fixed remote stream scheme for IPv4 and IPv6 addresses +- **Core/HealthCheck**: fixed panic on TLS errors during HTTP health checks +- **Core/Stream**: fixed nil panic for excluded routes +- **Core/Store**: fixed empty segment handling in nested paths + +## Refactoring + +- **Core/Agent**: extracted agent pool and HTTP utilities to dedicated package +- **Core/Route**: improved References method for FQDN alias handling +- **Core/Icon**: reorganized with health checking and retry logic +- **Core/Error**: replaced `gperr.Builder` with `gperr.Group` for concurrent error handling +- **Core/Utils**: removed `internal/utils` entirely, moved `RefCounter` to goutils diff --git a/goutils b/goutils index 4b046d27..326c1f1e 160000 --- a/goutils +++ b/goutils @@ -1 +1 @@ -Subproject commit 4b046d275fbfc49de3c02038983b775a95a3a8f6 +Subproject commit 326c1f1eb3620d36b482c453ca25971d4f251194 diff --git a/internal/gopsutil b/internal/gopsutil index 2dec3012..9532b08a 160000 --- a/internal/gopsutil +++ b/internal/gopsutil @@ -1 +1 @@ -Subproject commit 2dec30129b0ebfd2101e147aa621fed6598f080e +Subproject commit 9532b08adde452459baa610ce7768a6bc811f199