______________________________________________________________________

## 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