refactor(api): restructured API for type safety, maintainability and docs generation

- These changes makes the API incombatible with previous versions
- Added new types for error handling, success responses, and health checks.
- Updated health check logic to utilize the new types for better clarity and structure.
- Refactored existing handlers to improve response consistency and error handling.
- Updated Makefile to include a new target for generating API types from Swagger.
- Updated "new agent" API to respond an encrypted cert pair

Makefile

@@ -134,4 +134,13 @@ cloc:
 	cloc --include-lang=Go --not-match-f '_test.go$$' .
 
 push-github:
-	git push origin $(shell git rev-parse --abbrev-ref HEAD)
+	git push origin $(shell git rev-parse --abbrev-ref HEAD)
+
+gen-swagger:
+	swag init --parseDependency --parseInternal -g handler.go -d internal/api -o internal/api/v1/docs
+	python3 scripts/fix-swagger-json.py
+
+gen-api-types: gen-swagger
+	# --disable-throw-on-error
+	pnpx swagger-typescript-api generate --sort-types --generate-union-enums --axios --add-readonly --route-types \
+		 --responses -o ../godoxy-frontend/src/lib -n api.ts -p internal/api/v1/docs/swagger.json

agent/pkg/agent/new_agent.go

@@ -1,6 +1,8 @@
 package agent
 
 import (
+	"crypto/aes"
+	"crypto/cipher"
 	"crypto/rand"
 	"crypto/tls"
 	"crypto/x509"
@@ -8,6 +10,7 @@ import (
 	"encoding/base64"
 	"encoding/pem"
 	"errors"
+	"io"
 	"math/big"
 	"strings"
 	"time"
@@ -74,6 +77,62 @@ func (p *PEMPair) Load(data string) (err error) {
 	return nil
 }
 
+func (p *PEMPair) Encrypt(encKey []byte) (PEMPair, error) {
+	cert, err := encrypt(p.Cert, encKey)
+	if err != nil {
+		return PEMPair{}, err
+	}
+	key, err := encrypt(p.Key, encKey)
+	if err != nil {
+		return PEMPair{}, err
+	}
+	return PEMPair{Cert: cert, Key: key}, nil
+}
+
+func (p *PEMPair) Decrypt(encKey []byte) (PEMPair, error) {
+	cert, err := decrypt(p.Cert, encKey)
+	if err != nil {
+		return PEMPair{}, err
+	}
+	key, err := decrypt(p.Key, encKey)
+	if err != nil {
+		return PEMPair{}, err
+	}
+	return PEMPair{Cert: cert, Key: key}, nil
+}
+
+func encrypt(data []byte, key []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return nil, err
+	}
+	return gcm.Seal(nonce, nonce, data, nil), nil
+}
+
+func decrypt(data []byte, key []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+
+	nonce := data[:gcm.NonceSize()]
+	ciphertext := data[gcm.NonceSize():]
+	return gcm.Open(nil, nonce, ciphertext, nil)
+}
+
 func (p *PEMPair) ToTLSCert() (*tls.Certificate, error) {
 	cert, err := tls.X509KeyPair(p.Cert, p.Key)
 	return &cert, err

agent/pkg/agent/new_agent_test.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"crypto/rand"
 	"crypto/tls"
 	"crypto/x509"
 	"fmt"
@@ -89,3 +90,23 @@ func TestServerClient(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, resp.StatusCode, http.StatusOK)
 }
+
+func TestPEMPairEncryptDecrypt(t *testing.T) {
+	encKey := make([]byte, 32)
+	_, err := rand.Read(encKey)
+	require.NoError(t, err)
+
+	ca, _, _, err := NewAgent()
+	require.NoError(t, err)
+
+	encCA, err := ca.Encrypt(encKey)
+	require.NoError(t, err)
+	require.NotNil(t, encCA)
+
+	decCA, err := encCA.Decrypt(encKey)
+	require.NoError(t, err)
+	require.NotNil(t, decCA)
+
+	require.Equal(t, string(ca.Cert), string(decCA.Cert))
+	require.Equal(t, string(ca.Key), string(decCA.Key))
+}

agent/pkg/handler/check_health.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"strings"
 
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/watcher/health"
 	"github.com/yusing/go-proxy/internal/watcher/health/monitor"
 )
@@ -22,7 +23,7 @@ func CheckHealth(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	var result *health.HealthCheckResult
+	var result *types.HealthCheckResult
 	var err error
 	switch scheme {
 	case "fileserver":
@@ -32,7 +33,7 @@ func CheckHealth(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 		_, err := os.Stat(path)
-		result = &health.HealthCheckResult{Healthy: err == nil}
+		result = &types.HealthCheckResult{Healthy: err == nil}
 		if err != nil {
 			result.Detail = err.Error()
 		}

agent/pkg/handler/check_health_test.go

@@ -12,7 +12,7 @@ import (
 	"github.com/stretchr/testify/require"
 	"github.com/yusing/go-proxy/agent/pkg/agent"
 	"github.com/yusing/go-proxy/agent/pkg/handler"
-	"github.com/yusing/go-proxy/internal/watcher/health"
+	"github.com/yusing/go-proxy/internal/types"
 )
 
 func TestCheckHealthHTTP(t *testing.T) {
@@ -81,7 +81,7 @@ func TestCheckHealthHTTP(t *testing.T) {
 			require.Equal(t, recorder.Code, tt.expectedStatus)
 
 			if tt.expectedStatus == http.StatusOK {
-				var result health.HealthCheckResult
+				var result types.HealthCheckResult
 				require.NoError(t, json.Unmarshal(recorder.Body.Bytes(), &result))
 				require.Equal(t, result.Healthy, tt.expectedHealthy)
 			}
@@ -125,7 +125,7 @@ func TestCheckHealthFileServer(t *testing.T) {
 
 			require.Equal(t, recorder.Code, tt.expectedStatus)
 
-			var result health.HealthCheckResult
+			var result types.HealthCheckResult
 			require.NoError(t, json.Unmarshal(recorder.Body.Bytes(), &result))
 			require.Equal(t, result.Healthy, tt.expectedHealthy)
 			require.Equal(t, result.Detail, tt.expectedDetail)
@@ -217,7 +217,7 @@ func TestCheckHealthTCPUDP(t *testing.T) {
 			require.Equal(t, recorder.Code, tt.expectedStatus)
 
 			if tt.expectedStatus == http.StatusOK {
-				var result health.HealthCheckResult
+				var result types.HealthCheckResult
 				require.NoError(t, json.Unmarshal(recorder.Body.Bytes(), &result))
 				require.Equal(t, result.Healthy, tt.expectedHealthy)
 			}

agent/pkg/handler/handler.go

@@ -25,7 +25,9 @@ func NewAgentHandler() http.Handler {
 	mux := ServeMux{http.NewServeMux()}
 
 	mux.HandleFunc(agent.EndpointProxyHTTP+"/{path...}", ProxyHTTP)
-	mux.HandleEndpoint("GET", agent.EndpointVersion, pkg.GetVersionHTTPHandler())
+	mux.HandleEndpoint("GET", agent.EndpointVersion, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, pkg.GetVersion())
+	})
 	mux.HandleEndpoint("GET", agent.EndpointName, func(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, env.AgentName)
 	})

internal/api/handler.go

@@ -1,111 +1,155 @@
 package api
 
 import (
-	"fmt"
 	"net/http"
 
-	v1 "github.com/yusing/go-proxy/internal/api/v1"
-	"github.com/yusing/go-proxy/internal/api/v1/certapi"
-	"github.com/yusing/go-proxy/internal/api/v1/dockerapi"
-	"github.com/yusing/go-proxy/internal/api/v1/favicon"
+	"github.com/gin-gonic/gin"
+	"github.com/rs/zerolog/log"
+	swaggerFiles "github.com/swaggo/files"
+	ginSwagger "github.com/swaggo/gin-swagger"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	apiV1 "github.com/yusing/go-proxy/internal/api/v1"
+	agentApi "github.com/yusing/go-proxy/internal/api/v1/agent"
+	authApi "github.com/yusing/go-proxy/internal/api/v1/auth"
+	certApi "github.com/yusing/go-proxy/internal/api/v1/cert"
+	dockerApi "github.com/yusing/go-proxy/internal/api/v1/docker"
+	"github.com/yusing/go-proxy/internal/api/v1/docs"
+	fileApi "github.com/yusing/go-proxy/internal/api/v1/file"
+	homepageApi "github.com/yusing/go-proxy/internal/api/v1/homepage"
+	metricsApi "github.com/yusing/go-proxy/internal/api/v1/metrics"
+	routeApi "github.com/yusing/go-proxy/internal/api/v1/route"
 	"github.com/yusing/go-proxy/internal/auth"
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/logging/memlogger"
-	"github.com/yusing/go-proxy/internal/metrics/uptime"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
-	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
-	"github.com/yusing/go-proxy/internal/utils/strutils"
-	"github.com/yusing/go-proxy/pkg"
 )
 
-type (
-	ServeMux struct {
-		*http.ServeMux
-		cfg config.ConfigInstance
+func NewHandler() *gin.Engine {
+	gin.SetMode("release")
+	r := gin.New()
+	r.Use(ErrorHandler())
+	r.Use(ErrorLoggingMiddleware())
+
+	docs.SwaggerInfo.Title = "GoDoxy API"
+	docs.SwaggerInfo.BasePath = "/api/v1"
+
+	v1Auth := r.Group("/api/v1/auth")
+	{
+		v1Auth.HEAD("/check", authApi.Check)
+		v1Auth.POST("/login", authApi.Login)
+		v1Auth.POST("/callback", authApi.Callback)
+		v1Auth.POST("/logout", authApi.Logout)
 	}
-	WithCfgHandler = func(config.ConfigInstance, http.ResponseWriter, *http.Request)
-)
 
-func (mux ServeMux) HandleFunc(methods, endpoint string, h any, requireAuth ...bool) {
-	var handler http.HandlerFunc
-	switch h := h.(type) {
-	case func(http.ResponseWriter, *http.Request):
-		handler = h
-	case http.Handler:
-		handler = h.ServeHTTP
-	case WithCfgHandler:
-		handler = func(w http.ResponseWriter, r *http.Request) {
-			h(mux.cfg, w, r)
+	v1Swagger := r.Group("/api/v1/swagger")
+	{
+		v1Swagger.GET("/:any", func(c *gin.Context) {
+			c.Redirect(http.StatusTemporaryRedirect, "/api/v1/swagger/index.html")
+		})
+		v1Swagger.GET("/:any/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	}
+
+	v1 := r.Group("/api/v1")
+	v1.Use(AuthMiddleware())
+	{
+		v1.GET("/favicon", apiV1.FavIcon)
+		v1.GET("/health", apiV1.Health)
+		v1.GET("/icons", apiV1.Icons)
+		v1.POST("/reload", apiV1.Reload)
+		v1.GET("/stats", apiV1.Stats)
+		v1.GET("/version", apiV1.Version)
+
+		route := v1.Group("/route")
+		{
+			route.GET("/list", routeApi.Routes)
+			route.GET("/:which", routeApi.Route)
+			route.GET("/providers", routeApi.Providers)
+			route.GET("/by_provider", routeApi.ByProvider)
+		}
+
+		file := v1.Group("/file")
+		{
+			file.GET("/list", fileApi.List)
+			file.GET("/content", fileApi.Get)
+			file.PUT("/content", fileApi.Set)
+			file.POST("/content", fileApi.Set)
+			file.POST("/validate", fileApi.Validate)
+		}
+
+		homepage := v1.Group("/homepage")
+		{
+			homepage.GET("/categories", homepageApi.Categories)
+			homepage.GET("/items", homepageApi.Items)
+			homepage.POST("/set", homepageApi.Set)
+		}
+
+		cert := v1.Group("/cert")
+		{
+			cert.GET("/info", certApi.Info)
+			cert.POST("/renew", certApi.Renew)
+		}
+
+		agent := v1.Group("/agent")
+		{
+			agent.GET("/list", agentApi.List)
+			agent.POST("/create", agentApi.Create)
+			agent.POST("/verify", agentApi.Verify)
+		}
+
+		metrics := v1.Group("/metrics")
+		{
+			metrics.GET("/system_info", metricsApi.SystemInfo)
+			metrics.GET("/uptime", metricsApi.Uptime)
+		}
+
+		docker := v1.Group("/docker")
+		{
+			docker.GET("/containers", dockerApi.Containers)
+			docker.GET("/info", dockerApi.Info)
+			docker.GET("/logs/:server/:container", dockerApi.Logs)
 		}
-	default:
-		panic(fmt.Errorf("unsupported handler type: %T", h))
 	}
 
-	matchDomains := mux.cfg.Value().MatchDomains
-	if len(matchDomains) > 0 {
-		origHandler := handler
-		handler = func(w http.ResponseWriter, r *http.Request) {
-			if httpheaders.IsWebsocket(r.Header) {
-				gpwebsocket.SetWebsocketAllowedDomains(r.Header, matchDomains)
+	return r
+}
+
+func AuthMiddleware() gin.HandlerFunc {
+	if !auth.IsEnabled() {
+		return func(c *gin.Context) {
+			c.Next()
+		}
+	}
+	return func(c *gin.Context) {
+		err := auth.GetDefaultAuth().CheckToken(c.Request)
+		if err != nil {
+			c.JSON(http.StatusUnauthorized, apitypes.Error("Unauthorized", err))
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}
+
+func ErrorHandler() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Next()
+		if len(c.Errors) > 0 {
+			for _, err := range c.Errors {
+				log.Err(err.Err).Str("uri", c.Request.RequestURI).Msg("Internal error")
+			}
+			if !isWebSocketRequest(c) {
+				c.JSON(http.StatusInternalServerError, apitypes.Error("Internal server error"))
 			}
-			origHandler(w, r)
-		}
-	}
-
-	if len(requireAuth) > 0 && requireAuth[0] {
-		handler = auth.RequireAuth(handler)
-	}
-	if methods == "" {
-		mux.ServeMux.HandleFunc(endpoint, handler)
-	} else {
-		for _, m := range strutils.CommaSeperatedList(methods) {
-			mux.ServeMux.HandleFunc(m+" "+endpoint, handler)
 		}
 	}
 }
 
-func NewHandler(cfg config.ConfigInstance) http.Handler {
-	mux := ServeMux{http.NewServeMux(), cfg}
-	mux.HandleFunc("GET", "/v1", v1.Index)
-	mux.HandleFunc("GET", "/v1/version", pkg.GetVersionHTTPHandler())
-
-	mux.HandleFunc("GET", "/v1/stats", v1.Stats, true)
-	mux.HandleFunc("POST", "/v1/reload", v1.Reload, true)
-	mux.HandleFunc("GET", "/v1/list", v1.ListRoutesHandler, true)
-	mux.HandleFunc("GET", "/v1/list/routes", v1.ListRoutesHandler, true)
-	mux.HandleFunc("GET", "/v1/list/route/{which}", v1.ListRouteHandler, true)
-	mux.HandleFunc("GET", "/v1/list/routes_by_provider", v1.ListRoutesByProviderHandler, true)
-	mux.HandleFunc("GET", "/v1/list/files", v1.ListFilesHandler, true)
-	mux.HandleFunc("GET", "/v1/list/homepage_config", v1.ListHomepageConfigHandler, true)
-	mux.HandleFunc("GET", "/v1/list/route_providers", v1.ListRouteProvidersHandler, true)
-	mux.HandleFunc("GET", "/v1/list/homepage_categories", v1.ListHomepageCategoriesHandler, true)
-	mux.HandleFunc("GET", "/v1/list/icons", v1.ListIconsHandler, true)
-	mux.HandleFunc("GET", "/v1/file/{type}/{filename}", v1.GetFileContent, true)
-	mux.HandleFunc("POST,PUT", "/v1/file/{type}/{filename}", v1.SetFileContent, true)
-	mux.HandleFunc("POST", "/v1/file/validate/{type}", v1.ValidateFile, true)
-	mux.HandleFunc("GET", "/v1/health", v1.Health, true)
-	mux.HandleFunc("GET", "/v1/logs", memlogger.Handler(), true)
-	mux.HandleFunc("GET", "/v1/favicon", favicon.GetFavIcon, true)
-	mux.HandleFunc("POST", "/v1/homepage/set", v1.SetHomePageOverrides, true)
-	mux.HandleFunc("GET", "/v1/agents", v1.ListAgents, true)
-	mux.HandleFunc("GET", "/v1/agents/new", v1.NewAgent, true)
-	mux.HandleFunc("POST", "/v1/agents/verify", v1.VerifyNewAgent, true)
-	mux.HandleFunc("GET", "/v1/metrics/system_info", v1.SystemInfo, true)
-	mux.HandleFunc("GET", "/v1/metrics/uptime", uptime.Poller.ServeHTTP, true)
-	mux.HandleFunc("GET", "/v1/cert/info", certapi.GetCertInfo, true)
-	mux.HandleFunc("", "/v1/cert/renew", certapi.RenewCert, true)
-	mux.HandleFunc("GET", "/v1/docker/info", dockerapi.DockerInfo, true)
-	mux.HandleFunc("GET", "/v1/docker/logs/{server}/{container}", dockerapi.Logs, true)
-	mux.HandleFunc("GET", "/v1/docker/containers", dockerapi.Containers, true)
-
-	defaultAuth := auth.GetDefaultAuth()
-	if defaultAuth == nil {
-		return mux
-	}
-
-	mux.HandleFunc("GET", "/v1/auth/check", auth.AuthCheckHandler)
-	mux.HandleFunc("GET,POST", "/v1/auth/redirect", defaultAuth.LoginHandler)
-	mux.HandleFunc("GET,POST", "/v1/auth/callback", defaultAuth.PostAuthCallbackHandler)
-	mux.HandleFunc("GET,POST", "/v1/auth/logout", defaultAuth.LogoutHandler)
-	return mux
+func ErrorLoggingMiddleware() gin.HandlerFunc {
+	return gin.CustomRecoveryWithWriter(nil, func(c *gin.Context, err any) {
+		log.Error().Any("error", err).Str("uri", c.Request.RequestURI).Msg("Internal error")
+		if !isWebSocketRequest(c) {
+			c.JSON(http.StatusInternalServerError, apitypes.Error("Internal server error"))
+		}
+	})
+}
+
+func isWebSocketRequest(c *gin.Context) bool {
+	return c.GetHeader("Upgrade") == "websocket"
 }

internal/api/types/error.go

@@ -0,0 +1,42 @@
+package apitypes
+
+type ErrorResponse struct {
+	Message string `json:"message"`
+	Error   string `json:"error,omitempty" extensions:"x-nullable"`
+} // @name ErrorResponse
+
+type serverError struct {
+	Message string
+	Err     error
+}
+
+// Error returns a generic error response
+func Error(message string, err ...error) ErrorResponse {
+	if len(err) > 0 {
+		return ErrorResponse{
+			Message: message,
+			Error:   err[0].Error(),
+		}
+	}
+	return ErrorResponse{
+		Message: message,
+	}
+}
+
+func InternalServerError(err error, message string) error {
+	return serverError{
+		Message: message,
+		Err:     err,
+	}
+}
+
+func (e serverError) Error() string {
+	if e.Err != nil {
+		return e.Message + ": " + e.Err.Error()
+	}
+	return e.Message
+}
+
+func (e serverError) Unwrap() error {
+	return e.Err
+}

internal/api/types/error_code.go

@@ -0,0 +1,17 @@
+package apitypes
+
+type ErrorCode int
+
+const (
+	ErrorCodeUnauthorized ErrorCode = iota + 1
+	ErrorCodeNotFound
+	ErrorCodeInternalServerError
+)
+
+func (e ErrorCode) String() string {
+	return []string{
+		"Unauthorized",
+		"Not Found",
+		"Internal Server Error",
+	}[e]
+}

internal/api/types/query.go

@@ -0,0 +1,29 @@
+package apitypes
+
+type QueryOptions struct {
+	Limit   int                 `binding:"required,min=1,max=20" form:"limit"`
+	Offset  int                 `binding:"omitempty,min=0" form:"offset"`
+	OrderBy QueryOrder          `binding:"omitempty,oneof=created_at updated_at" form:"order_by"`
+	Order   QueryOrderDirection `binding:"omitempty,oneof=asc desc" form:"order"`
+}
+
+type QueryOrder string
+
+const (
+	QueryOrderCreatedAt QueryOrder = "created_at"
+	QueryOrderUpdatedAt QueryOrder = "updated_at"
+)
+
+type QueryOrderDirection string
+
+const (
+	QueryOrderDirectionAsc  QueryOrderDirection = "asc"
+	QueryOrderDirectionDesc QueryOrderDirection = "desc"
+)
+
+type QueryResponse struct {
+	Total   int64 `json:"total"`
+	Limit   int   `json:"limit"`
+	Offset  int   `json:"offset"`
+	HasMore bool  `json:"has_more"`
+}

internal/api/types/success.go

@@ -0,0 +1,18 @@
+package apitypes
+
+type SuccessResponse struct {
+	Message string         `json:"message"`
+	Details map[string]any `json:"details,omitempty" extensions:"x-nullable"`
+} // @name SuccessResponse
+
+func Success(message string, extra ...map[string]any) SuccessResponse {
+	if len(extra) > 0 {
+		return SuccessResponse{
+			Message: message,
+			Details: extra[0],
+		}
+	}
+	return SuccessResponse{
+		Message: message,
+	}
+}

internal/api/v1/agent/common.go

@@ -0,0 +1,67 @@
+package agentapi
+
+import (
+	"crypto/rand"
+	"encoding/base64"
+	"sync/atomic"
+	"time"
+
+	"github.com/rs/zerolog/log"
+	"github.com/yusing/go-proxy/agent/pkg/agent"
+)
+
+type PEMPairResponse struct {
+	Cert string `json:"cert" format:"base64"`
+	Key  string `json:"key" format:"base64"`
+} // @name PEMPairResponse
+
+var encryptionKey atomic.Value
+
+const rotateKeyInterval = 15 * time.Minute
+
+func init() {
+	if err := rotateKey(); err != nil {
+		log.Panic().Err(err).Msg("failed to generate encryption key")
+	}
+	go func() {
+		for range time.Tick(rotateKeyInterval) {
+			if err := rotateKey(); err != nil {
+				log.Error().Err(err).Msg("failed to rotate encryption key")
+			}
+		}
+	}()
+}
+
+func getEncryptionKey() []byte {
+	return encryptionKey.Load().([]byte)
+}
+
+func rotateKey() error {
+	// generate a random 32 bytes key
+	key := make([]byte, 32)
+	if _, err := rand.Read(key); err != nil {
+		return err
+	}
+	encryptionKey.Store(key)
+	return nil
+}
+
+func toPEMPairResponse(encPEMPair agent.PEMPair) PEMPairResponse {
+	return PEMPairResponse{
+		Cert: base64.StdEncoding.EncodeToString(encPEMPair.Cert),
+		Key:  base64.StdEncoding.EncodeToString(encPEMPair.Key),
+	}
+}
+
+func fromEncryptedPEMPairResponse(pemPair PEMPairResponse) (agent.PEMPair, error) {
+	encCert, err := base64.StdEncoding.DecodeString(pemPair.Cert)
+	if err != nil {
+		return agent.PEMPair{}, err
+	}
+	encKey, err := base64.StdEncoding.DecodeString(pemPair.Key)
+	if err != nil {
+		return agent.PEMPair{}, err
+	}
+	pair := agent.PEMPair{Cert: encCert, Key: encKey}
+	return pair.Decrypt(getEncryptionKey())
+}

internal/api/v1/agent/create.go

@@ -0,0 +1,103 @@
+package agentapi
+
+import (
+	"fmt"
+	"net/http"
+
+	_ "embed"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/agent/pkg/agent"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+)
+
+type NewAgentRequest struct {
+	Name    string `form:"name" validate:"required"`
+	Host    string `form:"host" validate:"required"`
+	Port    int    `form:"port" validate:"required,min=1,max=65535"`
+	Type    string `form:"type" validate:"required,oneof=docker system"`
+	Nightly bool   `form:"nightly" validate:"omitempty"`
+} // @name NewAgentRequest
+
+type NewAgentResponse struct {
+	Compose string          `json:"compose"`
+	CA      PEMPairResponse `json:"ca"`
+	Client  PEMPairResponse `json:"client"`
+} // @name NewAgentResponse
+
+// @x-id				"create"
+// @BasePath		/api/v1
+// @Summary		Create a new agent
+// @Description	Create a new agent and return the docker compose file, encrypted CA and client PEMs
+// @Description	The returned PEMs are encrypted with a random key and will be used for verification when adding a new agent
+// @Tags			agent
+// @Accept			json
+// @Produce		json
+// @Param			request	body		NewAgentRequest	true	"Request"
+// @Success		200		{object}	NewAgentResponse
+// @Failure		400		{object}	apitypes.ErrorResponse
+// @Failure		403		{object}	apitypes.ErrorResponse
+// @Failure		409		{object}	apitypes.ErrorResponse
+// @Failure		500		{object}	apitypes.ErrorResponse
+// @Router			/agent/create [post]
+func Create(c *gin.Context) {
+	var request NewAgentRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+	hostport := fmt.Sprintf("%s:%d", request.Host, request.Port)
+	if _, ok := agent.GetAgent(hostport); ok {
+		c.JSON(http.StatusConflict, apitypes.Error("agent already exists"))
+		return
+	}
+
+	var image string
+	if request.Nightly {
+		image = agent.DockerImageNightly
+	} else {
+		image = agent.DockerImageProduction
+	}
+
+	ca, srv, client, err := agent.NewAgent()
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to create agent"))
+		return
+	}
+
+	var cfg agent.Generator = &agent.AgentEnvConfig{
+		Name:    request.Name,
+		Port:    request.Port,
+		CACert:  ca.String(),
+		SSLCert: srv.String(),
+	}
+	if request.Type == "docker" {
+		cfg = &agent.AgentComposeConfig{
+			Image:          image,
+			AgentEnvConfig: cfg.(*agent.AgentEnvConfig),
+		}
+	}
+	template, err := cfg.Generate()
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to generate agent config"))
+		return
+	}
+
+	key := getEncryptionKey()
+	encCA, err := ca.Encrypt(key)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to encrypt CA PEMs"))
+		return
+	}
+	encClient, err := client.Encrypt(key)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to encrypt client PEMs"))
+		return
+	}
+
+	c.JSON(http.StatusOK, NewAgentResponse{
+		Compose: template,
+		CA:      toPEMPairResponse(encCA),
+		Client:  toPEMPairResponse(encClient),
+	})
+}

internal/api/v1/agent/list.go

@@ -0,0 +1,32 @@
+package agentapi
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/agent/pkg/agent"
+	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
+)
+
+// @x-id				"list"
+// @BasePath		/api/v1
+// @Summary		List agents
+// @Description	List agents
+// @Tags			agent,websocket
+// @Accept			json
+// @Produce		json
+// @Success		200	{array}		Agent
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/agent/list [get]
+func List(c *gin.Context) {
+	if httpheaders.IsWebsocket(c.Request.Header) {
+		websocket.PeriodicWrite(c, 10*time.Second, func() (any, error) {
+			return agent.ListAgents(), nil
+		})
+	} else {
+		c.JSON(http.StatusOK, agent.ListAgents())
+	}
+}

internal/api/v1/agent/verify.go

@@ -0,0 +1,76 @@
+package agentapi
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/agent/pkg/certs"
+	. "github.com/yusing/go-proxy/internal/api/types"
+	config "github.com/yusing/go-proxy/internal/config/types"
+)
+
+type VerifyNewAgentRequest struct {
+	Host   string          `json:"host"`
+	CA     PEMPairResponse `json:"ca"`
+	Client PEMPairResponse `json:"client"`
+} // @name VerifyNewAgentRequest
+
+// @x-id          "verify"
+// @BasePath		/api/v1
+// @Summary		Verify a new agent
+// @Description	Verify a new agent and return the number of routes added
+// @Tags			agent
+// @Accept			json
+// @Produce		json
+// @Param			request	body		VerifyNewAgentRequest	true	"Request"
+// @Success		200		{object}	SuccessResponse
+// @Failure		400		{object}	ErrorResponse
+// @Failure		403		{object}	ErrorResponse
+// @Failure		500		{object}	ErrorResponse
+// @Router			/agent/verify [post]
+func Verify(c *gin.Context) {
+	var request VerifyNewAgentRequest
+	if err := c.ShouldBindJSON(&request); err != nil {
+		c.JSON(http.StatusBadRequest, Error("invalid request", err))
+		return
+	}
+
+	filename, ok := certs.AgentCertsFilepath(request.Host)
+	if !ok {
+		c.JSON(http.StatusBadRequest, Error("invalid host", nil))
+		return
+	}
+
+	ca, err := fromEncryptedPEMPairResponse(request.CA)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, Error("invalid CA", err))
+		return
+	}
+
+	client, err := fromEncryptedPEMPairResponse(request.Client)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, Error("invalid client", err))
+		return
+	}
+
+	nRoutesAdded, err := config.GetInstance().VerifyNewAgent(request.Host, ca, client)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, Error("invalid request", err))
+		return
+	}
+
+	zip, err := certs.ZipCert(ca.Cert, client.Cert, client.Key)
+	if err != nil {
+		c.Error(InternalServerError(err, "failed to zip certs"))
+		return
+	}
+
+	if err := os.WriteFile(filename, zip, 0o600); err != nil {
+		c.Error(InternalServerError(err, "failed to write certs"))
+		return
+	}
+
+	c.JSON(http.StatusOK, Success(fmt.Sprintf("Added %d routes", nRoutesAdded)))
+}

internal/api/v1/auth/callback.go

@@ -0,0 +1,24 @@
+//nolint:dupword
+package auth
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/auth"
+)
+
+// @x-id				"callback"
+// @Base			/api/v1
+// @Summary		Post Auth Callback
+// @Description	Handles the callback from the provider after successful authentication
+// @Tags			auth
+// @Produce		plain
+// @Param		  body	body	auth.UserPassAuthCallbackRequest	true	"Userpass only"
+// @Success		200	{string}	string	"Userpass: OK"
+// @Success		302	{string}	string	"OIDC: Redirects to home page"
+// @Failure		400	{string}	string	"OIDC: invalid request (missing state cookie or oauth state)"
+// @Failure		400	{string}	string	"Userpass: invalid request / credentials"
+// @Failure		500	{string}	string	"Internal server error"
+// @Router			/auth/callback [post]
+func Callback(c *gin.Context) {
+	auth.GetDefaultAuth().PostAuthCallbackHandler(c.Writer, c.Request)
+}

internal/api/v1/auth/check.go

@@ -0,0 +1,19 @@
+package auth
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/auth"
+)
+
+// @x-id				"check"
+// @Base			/api/v1
+// @Summary		Check authentication status
+// @Description	Checks if the user is authenticated by validating their token
+// @Tags			auth
+// @Produce		plain
+// @Success		200	{string}	string	"OK"
+// @Failure		403	{string}	string	"Forbidden: use X-Redirect-To header to redirect to login page"
+// @Router			/auth/check [head]
+func Check(c *gin.Context) {
+	auth.AuthCheckHandler(c.Writer, c.Request)
+}

internal/api/v1/auth/login.go

@@ -0,0 +1,20 @@
+package auth
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/auth"
+)
+
+// @x-id       "login"
+// @Base       /api/v1
+// @Summary    Login
+// @Description Initiates the login process by redirecting the user to the provider's login page
+// @Tags       auth
+// @Produce    plain
+// @Success    302 {string} string "Redirects to login page or IdP"
+// @Failure    403 {string} string "Forbidden(webui): follow X-Redirect-To header"
+// @Failure    429 {string} string "Too Many Requests"
+// @Router     /auth/login [post]
+func Login(c *gin.Context) {
+	auth.GetDefaultAuth().LoginHandler(c.Writer, c.Request)
+}

internal/api/v1/auth/logout.go

@@ -0,0 +1,18 @@
+package auth
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/auth"
+)
+
+// @x-id				"logout"
+// @Base			/api/v1
+// @Summary		Logout
+// @Description	Logs out the user by invalidating the token
+// @Tags			auth
+// @Produce		plain
+// @Success		302	{string} string	"Redirects to home page"
+// @Router			/auth/logout [post]
+func Logout(c *gin.Context) {
+	auth.GetDefaultAuth().LogoutHandler(c.Writer, c.Request)
+}

internal/api/v1/cert/info.go

@@ -1,9 +1,10 @@
 package certapi
 
 import (
-	"encoding/json"
 	"net/http"
 
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
 	config "github.com/yusing/go-proxy/internal/config/types"
 )
 
@@ -14,18 +15,29 @@ type CertInfo struct {
 	NotAfter       int64    `json:"not_after"`
 	DNSNames       []string `json:"dns_names"`
 	EmailAddresses []string `json:"email_addresses"`
-}
+} // @name CertInfo
 
-func GetCertInfo(w http.ResponseWriter, r *http.Request) {
+// @BasePath		/api/v1
+// @Summary		Get cert info
+// @Description	Get cert info
+// @Tags			cert
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	CertInfo
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		404	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/cert/info [get]
+func Info(c *gin.Context) {
 	autocert := config.GetInstance().AutoCertProvider()
 	if autocert == nil {
-		http.Error(w, "autocert is not enabled", http.StatusNotFound)
+		c.JSON(http.StatusNotFound, apitypes.Error("autocert is not enabled"))
 		return
 	}
 
 	cert, err := autocert.GetCert(nil)
 	if err != nil {
-		http.Error(w, err.Error(), http.StatusInternalServerError)
+		c.Error(apitypes.InternalServerError(err, "failed to get cert info"))
 		return
 	}
 
@@ -37,5 +49,5 @@ func GetCertInfo(w http.ResponseWriter, r *http.Request) {
 		DNSNames:       cert.Leaf.DNSNames,
 		EmailAddresses: cert.Leaf.EmailAddresses,
 	}
-	json.NewEncoder(w).Encode(&certInfo)
+	c.JSON(http.StatusOK, certInfo)
 }

internal/api/v1/cert/renew.go

@@ -0,0 +1,72 @@
+package certapi
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/rs/zerolog/log"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	config "github.com/yusing/go-proxy/internal/config/types"
+	"github.com/yusing/go-proxy/internal/gperr"
+	"github.com/yusing/go-proxy/internal/logging/memlogger"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
+)
+
+// @BasePath		/api/v1
+// @Summary		Renew cert
+// @Description	Renew cert
+// @Tags			cert
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	apitypes.SuccessResponse
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/cert/renew [post]
+func Renew(c *gin.Context) {
+	autocert := config.GetInstance().AutoCertProvider()
+	if autocert == nil {
+		c.JSON(http.StatusNotFound, apitypes.Error("autocert is not enabled"))
+		return
+	}
+
+	manager, err := websocket.NewManagerWithUpgrade(c)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to create websocket manager"))
+		return
+	}
+	defer manager.Close()
+
+	logs, cancel := memlogger.Events()
+	defer cancel()
+
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		err = autocert.ObtainCert()
+		if err != nil {
+			gperr.LogError("failed to obtain cert", err)
+			_ = manager.WriteData(websocket.TextMessage, []byte(err.Error()), 10*time.Second)
+		} else {
+			log.Info().Msg("cert obtained successfully")
+		}
+	}()
+
+	for {
+		select {
+		case l := <-logs:
+			if err != nil {
+				return
+			}
+
+			err = manager.WriteData(websocket.TextMessage, l, 10*time.Second)
+			if err != nil {
+				return
+			}
+		case <-done:
+			return
+		}
+	}
+}

internal/api/v1/certapi/renew.go

@@ -1,54 +0,0 @@
-package certapi
-
-import (
-	"net/http"
-
-	"github.com/rs/zerolog/log"
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/gperr"
-	"github.com/yusing/go-proxy/internal/logging/memlogger"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
-)
-
-func RenewCert(w http.ResponseWriter, r *http.Request) {
-	autocert := config.GetInstance().AutoCertProvider()
-	if autocert == nil {
-		http.Error(w, "autocert is not enabled", http.StatusNotFound)
-		return
-	}
-
-	conn, err := gpwebsocket.Initiate(w, r)
-	if err != nil {
-		return
-	}
-	defer conn.Close()
-
-	logs, cancel := memlogger.Events()
-	defer cancel()
-
-	done := make(chan struct{})
-
-	go func() {
-		defer close(done)
-		err = autocert.ObtainCert()
-		if err != nil {
-			gperr.LogError("failed to obtain cert", err)
-			_ = gpwebsocket.WriteText(conn, err.Error())
-		} else {
-			log.Info().Msg("cert obtained successfully")
-		}
-	}()
-	for {
-		select {
-		case l := <-logs:
-			if err != nil {
-				return
-			}
-			if err := gpwebsocket.WriteText(conn, string(l)); err != nil {
-				return
-			}
-		case <-done:
-			return
-		}
-	}
-}

internal/api/v1/config_file.go

@@ -1,133 +0,0 @@
-package v1
-
-import (
-	"fmt"
-	"io"
-	"net/http"
-	"os"
-	"path"
-	"strings"
-
-	"github.com/yusing/go-proxy/internal/common"
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/gperr"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/middleware"
-	"github.com/yusing/go-proxy/internal/route/provider"
-)
-
-type FileType string
-
-const (
-	FileTypeConfig     FileType = "config"
-	FileTypeProvider   FileType = "provider"
-	FileTypeMiddleware FileType = "middleware"
-)
-
-func fileType(file string) FileType {
-	switch {
-	case strings.HasPrefix(path.Base(file), "config."):
-		return FileTypeConfig
-	case strings.HasPrefix(file, common.MiddlewareComposeBasePath):
-		return FileTypeMiddleware
-	}
-	return FileTypeProvider
-}
-
-func (t FileType) IsValid() bool {
-	switch t {
-	case FileTypeConfig, FileTypeProvider, FileTypeMiddleware:
-		return true
-	}
-	return false
-}
-
-func (t FileType) GetPath(filename string) string {
-	if t == FileTypeMiddleware {
-		return path.Join(common.MiddlewareComposeBasePath, filename)
-	}
-	return path.Join(common.ConfigBasePath, filename)
-}
-
-func getArgs(r *http.Request) (fileType FileType, filename string, err error) {
-	fileType = FileType(r.PathValue("type"))
-	if !fileType.IsValid() {
-		err = fmt.Errorf("invalid file type: %s", fileType)
-		return
-	}
-	filename = r.PathValue("filename")
-	if filename == "" {
-		err = fmt.Errorf("missing filename")
-	}
-	return
-}
-
-func GetFileContent(w http.ResponseWriter, r *http.Request) {
-	fileType, filename, err := getArgs(r)
-	if err != nil {
-		gphttp.BadRequest(w, err.Error())
-		return
-	}
-	content, err := os.ReadFile(fileType.GetPath(filename))
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-	gphttp.WriteBody(w, content)
-}
-
-func validateFile(fileType FileType, content []byte) gperr.Error {
-	switch fileType {
-	case FileTypeConfig:
-		return config.Validate(content)
-	case FileTypeMiddleware:
-		errs := gperr.NewBuilder("middleware errors")
-		middleware.BuildMiddlewaresFromYAML("", content, errs)
-		return errs.Error()
-	}
-	return provider.Validate(content)
-}
-
-func ValidateFile(w http.ResponseWriter, r *http.Request) {
-	fileType := FileType(r.PathValue("type"))
-	if !fileType.IsValid() {
-		gphttp.BadRequest(w, "invalid file type")
-		return
-	}
-	content, err := io.ReadAll(r.Body)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-	r.Body.Close()
-	if valErr := validateFile(fileType, content); valErr != nil {
-		gphttp.JSONError(w, valErr, http.StatusBadRequest)
-		return
-	}
-	w.WriteHeader(http.StatusOK)
-}
-
-func SetFileContent(w http.ResponseWriter, r *http.Request) {
-	fileType, filename, err := getArgs(r)
-	if err != nil {
-		gphttp.BadRequest(w, err.Error())
-		return
-	}
-	content, err := io.ReadAll(r.Body)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-
-	if valErr := validateFile(fileType, content); valErr != nil {
-		gphttp.JSONError(w, valErr, http.StatusBadRequest)
-		return
-	}
-
-	err = os.WriteFile(fileType.GetPath(filename), content, 0o644)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-	w.WriteHeader(http.StatusOK)
-}

internal/api/v1/docker/containers.go

@@ -2,10 +2,10 @@ package dockerapi
 
 import (
 	"context"
-	"net/http"
 	"sort"
 
 	"github.com/docker/docker/api/types/container"
+	"github.com/gin-gonic/gin"
 	"github.com/yusing/go-proxy/internal/gperr"
 )
 
@@ -15,10 +15,20 @@ type Container struct {
 	ID     string `json:"id"`
 	Image  string `json:"image"`
 	State  string `json:"state"`
-}
+} // @name ContainerResponse
 
-func Containers(w http.ResponseWriter, r *http.Request) {
-	serveHTTP[Container](w, r, GetContainers)
+// @BasePath		/api/v1
+// @Summary		Get containers
+// @Description	Get containers
+// @Tags			docker
+// @Accept			json
+// @Produce		json
+// @Success		200	{array}		Container
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/docker/containers [get]
+func Containers(c *gin.Context) {
+	serveHTTP[Container](c, GetContainers)
 }
 
 func GetContainers(ctx context.Context, dockerClients DockerClients) ([]Container, gperr.Error) {

internal/api/v1/docker/info.go

@@ -0,0 +1,79 @@
+package dockerapi
+
+import (
+	"context"
+	"sort"
+
+	dockerSystem "github.com/docker/docker/api/types/system"
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/gperr"
+	"github.com/yusing/go-proxy/internal/utils/strutils"
+)
+
+type containerStats struct {
+	Total   int `json:"total"`
+	Running int `json:"running"`
+	Paused  int `json:"paused"`
+	Stopped int `json:"stopped"`
+} // @name ContainerStats
+
+type dockerInfo struct {
+	Name          string         `json:"name"`
+	ServerVersion string         `json:"version"`
+	Containers    containerStats `json:"containers"`
+	Images        int            `json:"images"`
+	NCPU          int            `json:"n_cpu"`
+	MemTotal      string         `json:"memory"`
+} // @name ServerInfo
+
+func toDockerInfo(info dockerSystem.Info) dockerInfo {
+	return dockerInfo{
+		Name:          info.Name,
+		ServerVersion: info.ServerVersion,
+		Containers: containerStats{
+			Total:   info.ContainersRunning,
+			Running: info.ContainersRunning,
+			Paused:  info.ContainersPaused,
+			Stopped: info.ContainersStopped,
+		},
+		Images:   info.Images,
+		NCPU:     info.NCPU,
+		MemTotal: strutils.FormatByteSize(info.MemTotal),
+	}
+}
+
+// @BasePath		/api/v1
+// @Summary		Get docker info
+// @Description	Get docker info
+// @Tags			docker
+// @Accept			json
+// @Produce		json
+// @Success		200	{array}		dockerInfo
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/docker/info [get]
+func Info(c *gin.Context) {
+	serveHTTP[dockerInfo](c, GetDockerInfo)
+}
+
+func GetDockerInfo(ctx context.Context, dockerClients DockerClients) ([]dockerInfo, gperr.Error) {
+	errs := gperr.NewBuilder("failed to get docker info")
+	dockerInfos := make([]dockerInfo, len(dockerClients))
+
+	i := 0
+	for name, dockerClient := range dockerClients {
+		info, err := dockerClient.Info(ctx)
+		if err != nil {
+			errs.Add(err)
+			continue
+		}
+		info.Name = name
+		dockerInfos[i] = toDockerInfo(info)
+		i++
+	}
+
+	sort.Slice(dockerInfos, func(i, j int) bool {
+		return dockerInfos[i].Name < dockerInfos[j].Name
+	})
+	return dockerInfos, errs.Error()
+}

internal/api/v1/docker/logs.go

@@ -0,0 +1,112 @@
+package dockerapi
+
+import (
+	"context"
+	"errors"
+	"net/http"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/pkg/stdcopy"
+	"github.com/gin-gonic/gin"
+	"github.com/rs/zerolog/log"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
+	"github.com/yusing/go-proxy/internal/task"
+)
+
+type LogsPathParams struct {
+	Server      string `uri:"server" binding:"required"`
+	ContainerID string `uri:"container" binding:"required"`
+} //	@name	LogsPathParams
+
+type LogsQueryParams struct {
+	Stdout bool   `form:"stdout,default=true"`
+	Stderr bool   `form:"stderr,default=true"`
+	Since  string `form:"from"`
+	Until  string `form:"to"`
+	Levels string `form:"levels"`
+} //	@name	LogsQueryParams
+
+// @BasePath		/api/v1
+// @Summary		Get docker container logs
+// @Description	Get docker container logs
+// @Tags			docker,websocket
+// @Accept			json
+// @Produce		json
+// @Param			server		path	string	true	"server name"
+// @Param			container	path	string	true	"container id"
+// @Param			stdout		query	bool	false	"show stdout"
+// @Param			stderr		query	bool	false	"show stderr"
+// @Param			from		query	string	false	"from timestamp"
+// @Param			to			query	string	false	"to timestamp"
+// @Param			levels		query	string	false	"levels"
+// @Success		200
+// @Failure		400	{object}	apitypes.ErrorResponse
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		404	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/docker/logs/{server}/{container} [get]
+func Logs(c *gin.Context) {
+	var pathParams LogsPathParams
+	var queryParams LogsQueryParams
+	if err := c.ShouldBindQuery(&queryParams); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid query params"))
+		return
+	}
+	if err := c.ShouldBindUri(&pathParams); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid path params"))
+		return
+	}
+	// TODO: implement levels
+
+	dockerClient, found, err := getDockerClient(pathParams.Server)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to get docker client"))
+		return
+	}
+	if !found {
+		c.JSON(http.StatusNotFound, apitypes.Error("server not found"))
+		return
+	}
+	defer dockerClient.Close()
+
+	opts := container.LogsOptions{
+		ShowStdout: queryParams.Stdout,
+		ShowStderr: queryParams.Stderr,
+		Since:      queryParams.Since,
+		Until:      queryParams.Until,
+		Timestamps: true,
+		Follow:     true,
+		Tail:       "100",
+	}
+	if queryParams.Levels != "" {
+		opts.Details = true
+	}
+
+	logs, err := dockerClient.ContainerLogs(c.Request.Context(), pathParams.ContainerID, opts)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to get container logs"))
+		return
+	}
+	defer logs.Close()
+
+	manager, err := websocket.NewManagerWithUpgrade(c)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to create websocket manager"))
+		return
+	}
+	defer manager.Close()
+
+	writer := manager.NewWriter(websocket.TextMessage)
+
+	_, err = stdcopy.StdCopy(writer, writer, logs) // de-multiplex logs
+	if err != nil {
+		if errors.Is(err, context.Canceled) || errors.Is(err, task.ErrProgramExiting) {
+			return
+		}
+		log.Err(err).
+			Str("server", pathParams.Server).
+			Str("container", pathParams.ContainerID).
+			Msg("failed to de-multiplex logs")
+	}
+}

internal/api/v1/docker/utils.go

@@ -2,17 +2,17 @@ package dockerapi
 
 import (
 	"context"
-	"encoding/json"
 	"net/http"
 	"time"
 
-	"github.com/gorilla/websocket"
+	"github.com/gin-gonic/gin"
 	"github.com/yusing/go-proxy/agent/pkg/agent"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
 	config "github.com/yusing/go-proxy/internal/config/types"
 	"github.com/yusing/go-proxy/internal/docker"
 	"github.com/yusing/go-proxy/internal/gperr"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
 	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
 )
 
 type (
@@ -50,7 +50,7 @@ func getDockerClients() (DockerClients, gperr.Error) {
 			connErrs.Add(err)
 			continue
 		}
-		dockerClients[agent.Name()] = dockerClient
+		dockerClients[agent.Name] = dockerClient
 	}
 
 	return dockerClients, connErrs.Error()
@@ -67,7 +67,7 @@ func getDockerClient(server string) (*docker.SharedClient, bool, error) {
 	}
 	if host == "" {
 		for _, agent := range agent.ListAgents() {
-			if agent.Name() == server {
+			if agent.Name == server {
 				host = agent.FakeDockerHost()
 				break
 			}
@@ -92,35 +92,30 @@ func closeAllClients(dockerClients DockerClients) {
 	}
 }
 
-func handleResult[V any, T ResultType[V]](w http.ResponseWriter, errs error, result T) {
+func handleResult[V any, T ResultType[V]](c *gin.Context, errs error, result T) {
 	if errs != nil {
-		gperr.LogError("docker errors", errs)
 		if len(result) == 0 {
-			http.Error(w, "docker errors", http.StatusInternalServerError)
+			c.Error(apitypes.InternalServerError(errs, "docker errors"))
 			return
 		}
 	}
-	json.NewEncoder(w).Encode(result) //nolint
+	c.JSON(http.StatusOK, result)
 }
 
-func serveHTTP[V any, T ResultType[V]](w http.ResponseWriter, r *http.Request, getResult func(ctx context.Context, dockerClients DockerClients) (T, gperr.Error)) {
+func serveHTTP[V any, T ResultType[V]](c *gin.Context, getResult func(ctx context.Context, dockerClients DockerClients) (T, gperr.Error)) {
 	dockerClients, err := getDockerClients()
 	if err != nil {
-		handleResult[V, T](w, err, nil)
+		handleResult[V, T](c, err, nil)
 		return
 	}
 	defer closeAllClients(dockerClients)
 
-	if httpheaders.IsWebsocket(r.Header) {
-		gpwebsocket.Periodic(w, r, 5*time.Second, func(conn *websocket.Conn) error {
-			result, err := getResult(r.Context(), dockerClients)
-			if err != nil {
-				return err
-			}
-			return conn.WriteJSON(result)
+	if httpheaders.IsWebsocket(c.Request.Header) {
+		websocket.PeriodicWrite(c, 5*time.Second, func() (any, error) {
+			return getResult(c.Request.Context(), dockerClients)
 		})
 	} else {
-		result, err := getResult(r.Context(), dockerClients)
-		handleResult[V](w, err, result)
+		result, err := getResult(c.Request.Context(), dockerClients)
+		handleResult[V](c, err, result)
 	}
 }

internal/api/v1/dockerapi/info.go

@@ -1,56 +0,0 @@
-package dockerapi
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"sort"
-
-	dockerSystem "github.com/docker/docker/api/types/system"
-	"github.com/yusing/go-proxy/internal/gperr"
-	"github.com/yusing/go-proxy/internal/utils/strutils"
-)
-
-type dockerInfo dockerSystem.Info
-
-func (d *dockerInfo) MarshalJSON() ([]byte, error) {
-	return json.Marshal(map[string]any{
-		"name":    d.Name,
-		"version": d.ServerVersion,
-		"containers": map[string]int{
-			"total":   d.Containers,
-			"running": d.ContainersRunning,
-			"paused":  d.ContainersPaused,
-			"stopped": d.ContainersStopped,
-		},
-		"images": d.Images,
-		"n_cpu":  d.NCPU,
-		"memory": strutils.FormatByteSize(d.MemTotal),
-	})
-}
-
-func DockerInfo(w http.ResponseWriter, r *http.Request) {
-	serveHTTP[dockerInfo](w, r, GetDockerInfo)
-}
-
-func GetDockerInfo(ctx context.Context, dockerClients DockerClients) ([]dockerInfo, gperr.Error) {
-	errs := gperr.NewBuilder("failed to get docker info")
-	dockerInfos := make([]dockerInfo, len(dockerClients))
-
-	i := 0
-	for name, dockerClient := range dockerClients {
-		info, err := dockerClient.Info(ctx)
-		if err != nil {
-			errs.Add(err)
-			continue
-		}
-		info.Name = name
-		dockerInfos[i] = dockerInfo(info)
-		i++
-	}
-
-	sort.Slice(dockerInfos, func(i, j int) bool {
-		return dockerInfos[i].Name < dockerInfos[j].Name
-	})
-	return dockerInfos, errs.Error()
-}

internal/api/v1/dockerapi/logs.go

@@ -1,77 +0,0 @@
-package dockerapi
-
-import (
-	"context"
-	"errors"
-	"net/http"
-	"strconv"
-
-	"github.com/docker/docker/api/types/container"
-	"github.com/docker/docker/pkg/stdcopy"
-	"github.com/gorilla/websocket"
-	"github.com/rs/zerolog/log"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
-	"github.com/yusing/go-proxy/internal/task"
-)
-
-// FIXME: agent logs not updating.
-func Logs(w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
-	server := r.PathValue("server")
-	containerID := r.PathValue("container")
-	stdout, _ := strconv.ParseBool(query.Get("stdout"))
-	stderr, _ := strconv.ParseBool(query.Get("stderr"))
-	since := query.Get("from")
-	until := query.Get("to")
-	levels := query.Get("levels") // TODO: implement levels
-
-	dockerClient, found, err := getDockerClient(server)
-	if err != nil {
-		gphttp.BadRequest(w, err.Error())
-		return
-	}
-	if !found {
-		gphttp.NotFound(w, "server not found")
-		return
-	}
-	defer dockerClient.Close()
-
-	opts := container.LogsOptions{
-		ShowStdout: stdout,
-		ShowStderr: stderr,
-		Since:      since,
-		Until:      until,
-		Timestamps: true,
-		Follow:     true,
-		Tail:       "100",
-	}
-	if levels != "" {
-		opts.Details = true
-	}
-
-	logs, err := dockerClient.ContainerLogs(r.Context(), containerID, opts)
-	if err != nil {
-		gphttp.BadRequest(w, err.Error())
-		return
-	}
-	defer logs.Close()
-
-	conn, err := gpwebsocket.Initiate(w, r)
-	if err != nil {
-		return
-	}
-	defer conn.Close()
-
-	writer := gpwebsocket.NewWriter(r.Context(), conn, websocket.TextMessage)
-	_, err = stdcopy.StdCopy(writer, writer, logs) // de-multiplex logs
-	if err != nil {
-		if errors.Is(err, context.Canceled) || errors.Is(err, task.ErrProgramExiting) {
-			return
-		}
-		log.Err(err).
-			Str("server", server).
-			Str("container", containerID).
-			Msg("failed to de-multiplex logs")
-	}
-}

internal/api/v1/favicon.go

@@ -0,0 +1,100 @@
+package v1
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/homepage"
+	"github.com/yusing/go-proxy/internal/route/routes"
+)
+
+type GetFavIconRequest struct {
+	URL   string `form:"url" binding:"required_without=Alias"`
+	Alias string `form:"alias" binding:"required_without=URL"`
+} //	@name	GetFavIconRequest
+
+// GetFavIcon returns the favicon of the route
+//
+// Returns:
+//   - 200 OK: if icon found
+//   - 400 Bad Request: if alias is empty or route is not HTTPRoute
+//   - 404 Not Found: if route or icon not found
+//   - 500 Internal Server Error: if internal error
+//   - others: depends on route handler response
+
+// @x-id				"favicon"
+// @BasePath		/api/v1
+// @Summary		Get favicon
+// @Description	Get favicon
+// @Tags			v1
+// @Accept			json
+// @Produce		image/svg+xml,image/x-icon,image/png,image/webp
+// @Param			url		query		string	false	"URL of the route"
+// @Param			alias	query		string	false	"Alias of the route"
+// @Success		200		{array}		homepage.FetchResult
+// @Failure		400		{object}	apitypes.ErrorResponse
+// @Failure		403		{object}	apitypes.ErrorResponse
+// @Failure		404		{object}	apitypes.ErrorResponse
+// @Failure		500		{object}	apitypes.ErrorResponse
+// @Router			/favicon [get]
+func FavIcon(c *gin.Context) {
+	var request GetFavIconRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	// try with url
+	if request.URL != "" {
+		var iconURL homepage.IconURL
+		if err := iconURL.Parse(request.URL); err != nil {
+			c.JSON(http.StatusBadRequest, apitypes.Error("invalid url", err))
+			return
+		}
+		fetchResult := homepage.FetchFavIconFromURL(c.Request.Context(), &iconURL)
+		if !fetchResult.OK() {
+			c.JSON(fetchResult.StatusCode, apitypes.Error(fetchResult.ErrMsg))
+			return
+		}
+		c.Data(fetchResult.StatusCode, fetchResult.ContentType(), fetchResult.Icon)
+		return
+	}
+
+	// try with alias
+	result := GetFavIconFromAlias(c.Request.Context(), request.Alias)
+	if !result.OK() {
+		c.JSON(result.StatusCode, apitypes.Error(result.ErrMsg))
+		return
+	}
+	c.Data(result.StatusCode, result.ContentType(), result.Icon)
+}
+
+func GetFavIconFromAlias(ctx context.Context, alias string) *homepage.FetchResult {
+	// try with route.Icon
+	r, ok := routes.HTTP.Get(alias)
+	if !ok {
+		return &homepage.FetchResult{
+			StatusCode: http.StatusNotFound,
+			ErrMsg:     "route not found",
+		}
+	}
+
+	var result *homepage.FetchResult
+	hp := r.HomepageItem()
+	if hp.Icon != nil {
+		if hp.Icon.IconSource == homepage.IconSourceRelative {
+			result = homepage.FindIcon(ctx, r, *hp.Icon.FullURL)
+		} else {
+			result = homepage.FetchFavIconFromURL(ctx, hp.Icon)
+		}
+	} else {
+		// try extract from "link[rel=icon]"
+		result = homepage.FindIcon(ctx, r, "/")
+	}
+	if result.StatusCode == 0 {
+		result.StatusCode = http.StatusOK
+	}
+	return result
+}

internal/api/v1/favicon/favicon.go

@@ -1,81 +0,0 @@
-package favicon
-
-import (
-	"net/http"
-
-	"github.com/yusing/go-proxy/internal/homepage"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/route/routes"
-)
-
-// GetFavIcon returns the favicon of the route
-//
-// Returns:
-//   - 200 OK: if icon found
-//   - 400 Bad Request: if alias is empty or route is not HTTPRoute
-//   - 404 Not Found: if route or icon not found
-//   - 500 Internal Server Error: if internal error
-//   - others: depends on route handler response
-func GetFavIcon(w http.ResponseWriter, req *http.Request) {
-	url, alias := req.FormValue("url"), req.FormValue("alias")
-	if url == "" && alias == "" {
-		gphttp.MissingKey(w, "url or alias")
-		return
-	}
-	if url != "" && alias != "" {
-		gphttp.BadRequest(w, "url and alias are mutually exclusive")
-		return
-	}
-
-	// try with url
-	if url != "" {
-		var iconURL homepage.IconURL
-		if err := iconURL.Parse(url); err != nil {
-			gphttp.ClientError(w, req, err, http.StatusBadRequest)
-			return
-		}
-		fetchResult := homepage.FetchFavIconFromURL(req.Context(), &iconURL)
-		if !fetchResult.OK() {
-			http.Error(w, fetchResult.ErrMsg, fetchResult.StatusCode)
-			return
-		}
-		w.Header().Set("Content-Type", fetchResult.ContentType())
-		gphttp.WriteBody(w, fetchResult.Icon)
-		return
-	}
-
-	// try with alias
-	GetFavIconFromAlias(w, req, alias)
-	return
-}
-
-func GetFavIconFromAlias(w http.ResponseWriter, req *http.Request, alias string) {
-	// try with route.Icon
-	r, ok := routes.HTTP.Get(alias)
-	if !ok {
-		gphttp.ValueNotFound(w, "route", alias)
-		return
-	}
-
-	var result *homepage.FetchResult
-	hp := r.HomepageItem()
-	if hp.Icon != nil {
-		if hp.Icon.IconSource == homepage.IconSourceRelative {
-			result = homepage.FindIcon(req.Context(), r, *hp.Icon.FullURL)
-		} else {
-			result = homepage.FetchFavIconFromURL(req.Context(), hp.Icon)
-		}
-	} else {
-		// try extract from "link[rel=icon]"
-		result = homepage.FindIcon(req.Context(), r, "/")
-	}
-	if result.StatusCode == 0 {
-		result.StatusCode = http.StatusOK
-	}
-	if !result.OK() {
-		http.Error(w, result.ErrMsg, result.StatusCode)
-		return
-	}
-	w.Header().Set("Content-Type", result.ContentType())
-	gphttp.WriteBody(w, result.Icon)
-}

internal/api/v1/file/get.go

@@ -0,0 +1,73 @@
+package fileapi
+
+import (
+	"net/http"
+	"os"
+	"path"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/common"
+)
+
+type FileType string // @name FileType
+
+const (
+	FileTypeConfig     FileType = "config"     // @name FileTypeConfig
+	FileTypeProvider   FileType = "provider"   // @name FileTypeProvider
+	FileTypeMiddleware FileType = "middleware" // @name FileTypeMiddleware
+)
+
+type GetFileContentRequest struct {
+	FileType FileType `form:"type" binding:"required,oneof=config provider middleware"`
+	Filename string   `form:"filename" binding:"required" format:"filename"`
+} //	@name	GetFileContentRequest
+
+// @x-id				"get"
+// @BasePath		/api/v1
+// @Summary		Get file content
+// @Description	Get file content
+// @Tags			file
+// @Accept			json
+// @Produce		json,application/godoxy+yaml
+// @Param			query	query		GetFileContentRequest	true	"Request"
+// @Success		200			{string}	application/godoxy+yaml	"File content"
+// @Failure		400			{object}	apitypes.ErrorResponse
+// @Failure		403			{object}	apitypes.ErrorResponse
+// @Failure		500			{object}	apitypes.ErrorResponse
+// @Router			/file/content [get]
+func Get(c *gin.Context) {
+	var request GetFileContentRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	content, err := os.ReadFile(request.FileType.GetPath(request.Filename))
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to read file"))
+		return
+	}
+
+	// RFC 9512: https://www.rfc-editor.org/rfc/rfc9512.html
+	// xxx/yyy+yaml
+	c.Data(http.StatusOK, "application/godoxy+yaml", content)
+}
+
+func GetFileType(file string) FileType {
+	switch {
+	case strings.HasPrefix(path.Base(file), "config."):
+		return FileTypeConfig
+	case strings.HasPrefix(file, common.MiddlewareComposeBasePath):
+		return FileTypeMiddleware
+	}
+	return FileTypeProvider
+}
+
+func (t FileType) GetPath(filename string) string {
+	if t == FileTypeMiddleware {
+		return path.Join(common.MiddlewareComposeBasePath, filename)
+	}
+	return path.Join(common.ConfigBasePath, filename)
+}

internal/api/v1/file/list.go

@@ -0,0 +1,62 @@
+package fileapi
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/common"
+	"github.com/yusing/go-proxy/internal/utils"
+)
+
+type ListFilesResponse struct {
+	Config     []string `json:"config"`
+	Provider   []string `json:"provider"`
+	Middleware []string `json:"middleware"`
+} // @name ListFilesResponse
+
+// @x-id				"list"
+// @BasePath		/api/v1
+// @Summary		List files
+// @Description	List files
+// @Tags			file
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	ListFilesResponse
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/file/list [get]
+func List(c *gin.Context) {
+	resp := map[FileType][]string{
+		FileTypeConfig:     make([]string, 0),
+		FileTypeProvider:   make([]string, 0),
+		FileTypeMiddleware: make([]string, 0),
+	}
+
+	// config/
+	files, err := utils.ListFiles(common.ConfigBasePath, 0, true)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to list files"))
+		return
+	}
+
+	for _, file := range files {
+		t := GetFileType(file)
+		file = strings.TrimPrefix(file, common.ConfigBasePath+"/")
+		resp[t] = append(resp[t], file)
+	}
+
+	// config/middlewares/
+	mids, err := utils.ListFiles(common.MiddlewareComposeBasePath, 0, true)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to list files"))
+		return
+	}
+	for _, mid := range mids {
+		mid = strings.TrimPrefix(mid, common.MiddlewareComposeBasePath+"/")
+		resp[FileTypeMiddleware] = append(resp[FileTypeMiddleware], mid)
+	}
+
+	c.JSON(http.StatusOK, resp)
+}

internal/api/v1/file/set.go

@@ -0,0 +1,52 @@
+package fileapi
+
+import (
+	"net/http"
+	"os"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+)
+
+type SetFileContentRequest GetFileContentRequest
+
+// @x-id				"set"
+// @BasePath		/api/v1
+// @Summary		Set file content
+// @Description	Set file content
+// @Tags			file
+// @Accept			json
+// @Produce		json
+// @Param			type		query		FileType	true	"Type"
+// @Param			filename	query		string		true	"Filename"
+// @Param			file		body		string		true	"File"
+// @Success		200			{object}	apitypes.SuccessResponse
+// @Failure		400			{object}	apitypes.ErrorResponse
+// @Failure		403			{object}	apitypes.ErrorResponse
+// @Failure		500			{object}	apitypes.ErrorResponse
+// @Router			/file/content [put]
+func Set(c *gin.Context) {
+	var request SetFileContentRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	content, err := c.GetRawData()
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to read file"))
+		return
+	}
+
+	if valErr := validateFile(request.FileType, content); valErr != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid file", valErr))
+		return
+	}
+
+	err = os.WriteFile(request.FileType.GetPath(request.Filename), content, 0o644)
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to write file"))
+		return
+	}
+	c.JSON(http.StatusOK, apitypes.Success("file set"))
+}

internal/api/v1/file/validate.go

@@ -0,0 +1,64 @@
+package fileapi
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	config "github.com/yusing/go-proxy/internal/config/types"
+	"github.com/yusing/go-proxy/internal/gperr"
+	"github.com/yusing/go-proxy/internal/net/gphttp/middleware"
+	"github.com/yusing/go-proxy/internal/route/provider"
+)
+
+type ValidateFileRequest struct {
+	FileType FileType `form:"type" validate:"required,oneof=config provider middleware"`
+} //	@name	ValidateFileRequest
+
+// @x-id				"validate"
+// @BasePath		/api/v1
+// @Summary		Validate file
+// @Description	Validate file
+// @Tags			file
+// @Accept			json
+// @Produce		json
+// @Param			type	query		FileType	true	"Type"
+// @Param			file	body		string		true	"File content"
+// @Success		200		{object}	apitypes.SuccessResponse "File validated"
+// @Failure		400		{object}	apitypes.ErrorResponse "Bad request"
+// @Failure		403		{object}	apitypes.ErrorResponse "Forbidden"
+// @Failure		417		{object}	apitypes.ErrorResponse "Validation failed"
+// @Failure		500		{object}	apitypes.ErrorResponse "Internal server error"
+// @Router			/file/validate [post]
+func Validate(c *gin.Context) {
+	var request ValidateFileRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	content, err := c.GetRawData()
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to read file"))
+		return
+	}
+	c.Request.Body.Close()
+
+	if valErr := validateFile(request.FileType, content); valErr != nil {
+		c.JSON(http.StatusExpectationFailed, apitypes.Error("invalid file", valErr))
+		return
+	}
+	c.JSON(http.StatusOK, apitypes.Success("file validated"))
+}
+
+func validateFile(fileType FileType, content []byte) gperr.Error {
+	switch fileType {
+	case FileTypeConfig:
+		return config.Validate(content)
+	case FileTypeMiddleware:
+		errs := gperr.NewBuilder("middleware errors")
+		middleware.BuildMiddlewaresFromYAML("", content, errs)
+		return errs.Error()
+	}
+	return provider.Validate(content)
+}

internal/api/v1/health.go

@@ -4,19 +4,31 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/gorilla/websocket"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
+	"github.com/gin-gonic/gin"
 	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
 	"github.com/yusing/go-proxy/internal/route/routes"
 )
 
-func Health(w http.ResponseWriter, r *http.Request) {
-	if httpheaders.IsWebsocket(r.Header) {
-		gpwebsocket.Periodic(w, r, 1*time.Second, func(conn *websocket.Conn) error {
-			return conn.WriteJSON(routes.HealthMap())
+type HealthMap = map[string]routes.HealthInfo //	@name	HealthMap
+
+// @x-id				"health"
+// @BasePath		/api/v1
+// @Summary		Get routes health info
+// @Description	Get health info by route name
+// @Tags			v1,websocket
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	HealthMap "Health info by route name"
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/health [get]
+func Health(c *gin.Context) {
+	if httpheaders.IsWebsocket(c.Request.Header) {
+		websocket.PeriodicWrite(c, 1*time.Second, func() (any, error) {
+			return routes.GetHealthInfo(), nil
 		})
 	} else {
-		gphttp.RespondJSON(w, r, routes.HealthMap())
+		c.JSON(http.StatusOK, routes.GetHealthInfo())
 	}
 }

internal/api/v1/homepage/categories.go

@@ -0,0 +1,22 @@
+package homepageapi
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/route/routes"
+)
+
+// @x-id				"categories"
+// @BasePath		/api/v1
+// @Summary		List homepage categories
+// @Description	List homepage categories
+// @Tags			homepage
+// @Accept			json
+// @Produce		json
+// @Success		200	{array}		string
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Router			/homepage/categories [get]
+func Categories(c *gin.Context) {
+	c.JSON(http.StatusOK, routes.HomepageCategories())
+}

internal/api/v1/homepage/items.go

@@ -0,0 +1,46 @@
+package homepageapi
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/route/routes"
+)
+
+type HomepageItemsRequest struct {
+	Category string `form:"category" validate:"omitempty"`
+	Provider string `form:"provider" validate:"omitempty"`
+} //	@name	HomepageItemsRequest
+
+// @x-id				"items"
+// @BasePath		/api/v1
+// @Summary		Homepage items
+// @Description	Homepage items
+// @Tags			homepage
+// @Accept			json
+// @Produce		json
+// @Param			category	query		string	false	"Category filter"
+// @Param			provider	query		string	false	"Provider filter"
+// @Success		200			{object}	homepage.Homepage
+// @Failure		400			{object}	apitypes.ErrorResponse
+// @Failure		403			{object}	apitypes.ErrorResponse
+// @Router			/homepage/items [get]
+func Items(c *gin.Context) {
+	var request HomepageItemsRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	proto := "http"
+	if c.Request.TLS != nil || c.GetHeader("X-Forwarded-Proto") == "https" {
+		proto = "https"
+	}
+	hostname := c.Request.Host
+	if host := c.GetHeader("X-Forwarded-Host"); host != "" {
+		hostname = host
+	}
+
+	c.JSON(http.StatusOK, routes.HomepageItems(proto, hostname, request.Category, request.Provider))
+}

internal/api/v1/homepage/overrides.go

@@ -0,0 +1,110 @@
+package homepageapi
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/homepage"
+)
+
+const (
+	HomepageOverrideItem          = "item"
+	HomepageOverrideItemsBatch    = "items_batch"
+	HomepageOverrideCategoryOrder = "category_order"
+	HomepageOverrideItemVisible   = "item_visible"
+)
+
+type (
+	HomepageOverrideItemParams struct {
+		Which string              `json:"which"`
+		Value homepage.ItemConfig `json:"value"`
+	} //	@name	HomepageOverrideItemParams
+	HomepageOverrideItemsBatchParams struct {
+		Value map[string]*homepage.ItemConfig `json:"value"`
+	} //	@name	HomepageOverrideItemsBatchParams
+	HomepageOverrideCategoryOrderParams struct {
+		Which string `json:"which"`
+		Value int    `json:"value"`
+	} //	@name	HomepageOverrideCategoryOrderParams
+	HomepageOverrideItemVisibleParams struct {
+		Which []string `json:"which"`
+		Value bool     `json:"value"`
+	} //	@name	HomepageOverrideItemVisibleParams
+)
+
+type SetHomePageOverridesRequest struct {
+	What  string `json:"what" validate:"required,oneof=item items_batch category_order item_visible"`
+	Value any    `json:"value" validate:"required" swaggerType:"object"`
+}
+
+// @x-id				"set"
+// @BasePath		/api/v1
+// @Summary		Set homepage overrides
+// @Description	Set homepage overrides
+// @Tags			homepage
+// @Accept			json
+// @Produce		json
+// @Param			request	body		SetHomePageOverridesRequest{value=HomepageOverrideItemParams}			true	"Override single item"
+// @Param			request	body		SetHomePageOverridesRequest{value=HomepageOverrideItemsBatchParams}		true	"Override multiple items"
+// @Param			request	body		SetHomePageOverridesRequest{value=HomepageOverrideCategoryOrderParams}	true	"Override category order"
+// @Param			request	body		SetHomePageOverridesRequest{value=HomepageOverrideItemVisibleParams}	true	"Override item visibility"
+// @Success		200		{object}	apitypes.SuccessResponse
+// @Failure		400		{object}	apitypes.ErrorResponse
+// @Failure		500		{object}	apitypes.ErrorResponse
+// @Router			/homepage/set [post]
+func Set(c *gin.Context) {
+	var request SetHomePageOverridesRequest
+	if err := c.ShouldBindJSON(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	data, err := c.GetRawData()
+	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to get raw data"))
+		return
+	}
+
+	overrides := homepage.GetOverrideConfig()
+	switch request.What {
+	case HomepageOverrideItem:
+		var params HomepageOverrideItemParams
+		if err := json.Unmarshal(data, &params); err != nil {
+			c.Error(apitypes.InternalServerError(err, "failed to unmarshal data"))
+			return
+		}
+		overrides.OverrideItem(params.Which, &params.Value)
+	case HomepageOverrideItemsBatch:
+		var params HomepageOverrideItemsBatchParams
+		if err := json.Unmarshal(data, &params); err != nil {
+			c.Error(apitypes.InternalServerError(err, "failed to unmarshal data"))
+			return
+		}
+		overrides.OverrideItems(params.Value)
+	case HomepageOverrideItemVisible: // POST /v1/item_visible [a,b,c], false => hide a, b, c
+		var params HomepageOverrideItemVisibleParams
+		if err := json.Unmarshal(data, &params); err != nil {
+			c.Error(apitypes.InternalServerError(err, "failed to unmarshal data"))
+			return
+		}
+		if params.Value {
+			overrides.UnhideItems(params.Which)
+		} else {
+			overrides.HideItems(params.Which)
+		}
+	case HomepageOverrideCategoryOrder:
+		var params HomepageOverrideCategoryOrderParams
+		if err := json.Unmarshal(data, &params); err != nil {
+			c.Error(apitypes.InternalServerError(err, "failed to unmarshal data"))
+			return
+		}
+		overrides.SetCategoryOrder(params.Which, params.Value)
+	default: // won't happen
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid what", errors.New("invalid what")))
+		return
+	}
+	c.JSON(http.StatusOK, apitypes.Success("success"))
+}

internal/api/v1/homepage_overrides.go

@@ -1,90 +0,0 @@
-package v1
-
-import (
-	"encoding/json"
-	"io"
-	"net/http"
-
-	"github.com/yusing/go-proxy/internal/homepage"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-)
-
-const (
-	HomepageOverrideItem          = "item"
-	HomepageOverrideItemsBatch    = "items_batch"
-	HomepageOverrideCategoryOrder = "category_order"
-	HomepageOverrideItemVisible   = "item_visible"
-)
-
-type (
-	HomepageOverrideItemParams struct {
-		Which string              `json:"which"`
-		Value homepage.ItemConfig `json:"value"`
-	}
-	HomepageOverrideItemsBatchParams struct {
-		Value map[string]*homepage.ItemConfig `json:"value"`
-	}
-	HomepageOverrideCategoryOrderParams struct {
-		Which string `json:"which"`
-		Value int    `json:"value"`
-	}
-	HomepageOverrideItemVisibleParams struct {
-		Which []string `json:"which"`
-		Value bool     `json:"value"`
-	}
-)
-
-func SetHomePageOverrides(w http.ResponseWriter, r *http.Request) {
-	what := r.FormValue("what")
-	if what == "" {
-		gphttp.BadRequest(w, "missing what or which")
-		return
-	}
-
-	data, err := io.ReadAll(r.Body)
-	if err != nil {
-		gphttp.ClientError(w, r, err, http.StatusBadRequest)
-		return
-	}
-	r.Body.Close()
-
-	overrides := homepage.GetOverrideConfig()
-	switch what {
-	case HomepageOverrideItem:
-		var params HomepageOverrideItemParams
-		if err := json.Unmarshal(data, &params); err != nil {
-			gphttp.ClientError(w, r, err, http.StatusBadRequest)
-			return
-		}
-		overrides.OverrideItem(params.Which, &params.Value)
-	case HomepageOverrideItemsBatch:
-		var params HomepageOverrideItemsBatchParams
-		if err := json.Unmarshal(data, &params); err != nil {
-			gphttp.ClientError(w, r, err, http.StatusBadRequest)
-			return
-		}
-		overrides.OverrideItems(params.Value)
-	case HomepageOverrideItemVisible: // POST /v1/item_visible [a,b,c], false => hide a, b, c
-		var params HomepageOverrideItemVisibleParams
-		if err := json.Unmarshal(data, &params); err != nil {
-			gphttp.ClientError(w, r, err, http.StatusBadRequest)
-			return
-		}
-		if params.Value {
-			overrides.UnhideItems(params.Which)
-		} else {
-			overrides.HideItems(params.Which)
-		}
-	case HomepageOverrideCategoryOrder:
-		var params HomepageOverrideCategoryOrderParams
-		if err := json.Unmarshal(data, &params); err != nil {
-			gphttp.ClientError(w, r, err, http.StatusBadRequest)
-			return
-		}
-		overrides.SetCategoryOrder(params.Which, params.Value)
-	default:
-		http.Error(w, "invalid what", http.StatusBadRequest)
-		return
-	}
-	w.WriteHeader(http.StatusOK)
-}

internal/api/v1/icons.go

@@ -0,0 +1,37 @@
+package v1
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/homepage"
+)
+
+type ListIconsRequest struct {
+	Limit   int    `form:"limit" validate:"omitempty,min=0"`
+	Keyword string `form:"keyword" validate:"required"`
+} //	@name	ListIconsRequest
+
+// @x-id				"icons"
+// @BasePath		/api/v1
+// @Summary		List icons
+// @Description	List icons
+// @Tags			v1
+// @Accept			json
+// @Produce		json
+// @Param			limit	query		int		false	"Limit"
+// @Param			keyword	query		string	false	"Keyword"
+// @Success		200		{array}		homepage.IconMetaSearch
+// @Failure		400		{object}	apitypes.ErrorResponse
+// @Failure		403		{object}	apitypes.ErrorResponse
+// @Router			/icons [get]
+func Icons(c *gin.Context) {
+	var request ListIconsRequest
+	if err := c.ShouldBindQuery(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+	icons := homepage.SearchIcons(request.Keyword, request.Limit)
+	c.JSON(http.StatusOK, icons)
+}

internal/api/v1/index.go

@@ -1,11 +0,0 @@
-package v1
-
-import (
-	"net/http"
-
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-)
-
-func Index(w http.ResponseWriter, r *http.Request) {
-	gphttp.WriteBody(w, []byte("API ready"))
-}

internal/api/v1/list_agents.go

@@ -1,22 +0,0 @@
-package v1
-
-import (
-	"net/http"
-	"time"
-
-	"github.com/gorilla/websocket"
-	"github.com/yusing/go-proxy/agent/pkg/agent"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
-	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
-)
-
-func ListAgents(w http.ResponseWriter, r *http.Request) {
-	if httpheaders.IsWebsocket(r.Header) {
-		gpwebsocket.Periodic(w, r, 10*time.Second, func(conn *websocket.Conn) error {
-			return conn.WriteJSON(agent.ListAgents())
-		})
-	} else {
-		gphttp.RespondJSON(w, r, agent.ListAgents())
-	}
-}

internal/api/v1/list_files.go

@@ -1,41 +0,0 @@
-package v1
-
-import (
-	"net/http"
-	"strings"
-
-	"github.com/yusing/go-proxy/internal/common"
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/utils"
-)
-
-func ListFilesHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	files, err := utils.ListFiles(common.ConfigBasePath, 0, true)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-	resp := map[FileType][]string{
-		FileTypeConfig:     make([]string, 0),
-		FileTypeProvider:   make([]string, 0),
-		FileTypeMiddleware: make([]string, 0),
-	}
-
-	for _, file := range files {
-		t := fileType(file)
-		file = strings.TrimPrefix(file, common.ConfigBasePath+"/")
-		resp[t] = append(resp[t], file)
-	}
-
-	mids, err := utils.ListFiles(common.MiddlewareComposeBasePath, 0, true)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-	for _, mid := range mids {
-		mid = strings.TrimPrefix(mid, common.MiddlewareComposeBasePath+"/")
-		resp[FileTypeMiddleware] = append(resp[FileTypeMiddleware], mid)
-	}
-	gphttp.RespondJSON(w, r, resp)
-}

internal/api/v1/list_homepage_categories.go

@@ -1,13 +0,0 @@
-package v1
-
-import (
-	"net/http"
-
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/route/routes"
-)
-
-func ListHomepageCategoriesHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	gphttp.RespondJSON(w, r, routes.HomepageCategories())
-}

internal/api/v1/list_homepage_config.go

@@ -1,13 +0,0 @@
-package v1
-
-import (
-	"net/http"
-
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/route/routes"
-)
-
-func ListHomepageConfigHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	gphttp.RespondJSON(w, r, routes.HomepageConfig(r.FormValue("category"), r.FormValue("provider")))
-}

internal/api/v1/list_icons.go

@@ -1,23 +0,0 @@
-package v1
-
-import (
-	"net/http"
-	"strconv"
-
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/homepage"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-)
-
-func ListIconsHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	limit, err := strconv.Atoi(r.FormValue("limit"))
-	if err != nil {
-		limit = 0
-	}
-	icons, err := homepage.SearchIcons(r.FormValue("keyword"), limit)
-	if err != nil {
-		gphttp.ClientError(w, r, err)
-		return
-	}
-	gphttp.RespondJSON(w, r, icons)
-}

internal/api/v1/list_route.go

@@ -1,19 +0,0 @@
-package v1
-
-import (
-	"net/http"
-
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/route/routes"
-)
-
-func ListRouteHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	which := r.PathValue("which")
-	route, ok := routes.Get(which)
-	if ok {
-		gphttp.RespondJSON(w, r, route)
-	} else {
-		gphttp.RespondJSON(w, r, nil)
-	}
-}

internal/api/v1/list_route_providers.go

@@ -1,22 +0,0 @@
-package v1
-
-import (
-	"net/http"
-	"time"
-
-	"github.com/gorilla/websocket"
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
-	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
-)
-
-func ListRouteProvidersHandler(cfgInstance config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	if httpheaders.IsWebsocket(r.Header) {
-		gpwebsocket.Periodic(w, r, 5*time.Second, func(conn *websocket.Conn) error {
-			return conn.WriteJSON(cfgInstance.RouteProviderList())
-		})
-	} else {
-		gphttp.RespondJSON(w, r, cfgInstance.RouteProviderList())
-	}
-}

internal/api/v1/list_routes.go

@@ -1,25 +0,0 @@
-package v1
-
-import (
-	"net/http"
-	"slices"
-
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/route/routes"
-)
-
-func ListRoutesHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	rts := make([]routes.Route, 0)
-	provider := r.FormValue("provider")
-	if provider == "" {
-		gphttp.RespondJSON(w, r, slices.Collect(routes.Iter))
-		return
-	}
-	for r := range routes.Iter {
-		if r.ProviderName() == provider {
-			rts = append(rts, r)
-		}
-	}
-	gphttp.RespondJSON(w, r, rts)
-}

internal/api/v1/list_routes_by_provider.go

@@ -1,13 +0,0 @@
-package v1
-
-import (
-	"net/http"
-
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/route/routes"
-)
-
-func ListRoutesByProviderHandler(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	gphttp.RespondJSON(w, r, routes.ByProvider())
-}

internal/api/v1/metrics/system_info.go

@@ -0,0 +1,71 @@
+package metrics
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	agentPkg "github.com/yusing/go-proxy/agent/pkg/agent"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/metrics/period"
+	"github.com/yusing/go-proxy/internal/metrics/systeminfo"
+	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/reverseproxy"
+	nettypes "github.com/yusing/go-proxy/internal/net/types"
+)
+
+type SystemInfoAggregate period.ResponseType[systeminfo.Aggregated] // @name SystemInfoAggregate
+
+// @x-id				"system_info"
+// @BasePath		/api/v1
+// @Summary		Get system info
+// @Description	Get system info
+// @Tags			metrics,websocket
+// @Produce		json
+// @Param			agent_addr	query		string	false	"Agent address"
+// @Param			period		query		string	false	"Period"
+// @Success		200			{object}	systeminfo.SystemInfo "no period specified"
+// @Success		200			{object}	SystemInfoAggregate "period specified"
+// @Failure		400			{object}	apitypes.ErrorResponse
+// @Failure		403			{object}	apitypes.ErrorResponse
+// @Failure		404			{object}	apitypes.ErrorResponse
+// @Failure		500			{object}	apitypes.ErrorResponse
+// @Router	 /metrics/system_info [get]
+func SystemInfo(c *gin.Context) {
+	query := c.Request.URL.Query()
+	agentAddr := query.Get("agent_addr")
+	query.Del("agent_addr")
+	if agentAddr == "" {
+		systeminfo.Poller.ServeHTTP(c)
+		return
+	}
+
+	agent, ok := agentPkg.GetAgent(agentAddr)
+	if !ok {
+		c.JSON(http.StatusNotFound, apitypes.Error("agent_addr not found"))
+		return
+	}
+
+	isWS := httpheaders.IsWebsocket(c.Request.Header)
+	if !isWS {
+		respData, status, err := agent.Forward(c.Request, agentPkg.EndpointSystemInfo)
+		if err != nil {
+			c.Error(apitypes.InternalServerError(err, "failed to forward request to agent"))
+			return
+		}
+		if status != http.StatusOK {
+			c.JSON(status, apitypes.Error(string(respData)))
+			return
+		}
+		c.JSON(status, respData)
+	} else {
+		rp := reverseproxy.NewReverseProxy("agent", nettypes.NewURL(agentPkg.AgentURL), agent.Transport())
+		header := c.Request.Header.Clone()
+		r, err := http.NewRequestWithContext(c.Request.Context(), c.Request.Method, agentPkg.EndpointSystemInfo+"?"+query.Encode(), nil)
+		if err != nil {
+			c.Error(apitypes.InternalServerError(err, "failed to create request"))
+			return
+		}
+		r.Header = header
+		rp.ServeHTTP(c.Writer, r)
+	}
+}

internal/api/v1/metrics/upime.go

@@ -0,0 +1,34 @@
+package metrics
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/metrics/period"
+	"github.com/yusing/go-proxy/internal/metrics/uptime"
+)
+
+type UptimeRequest struct {
+	Limit    int           `query:"limit" example:"10"`
+	Offset   string        `query:"offset" example:"10"`
+	Interval period.Filter `query:"interval" example:"1m"`
+	Keyword  string        `query:"keyword" example:""`
+} // @name UptimeRequest
+
+type UptimeAggregate period.ResponseType[uptime.Aggregated] // @name UptimeAggregate
+
+// @x-id				"uptime"
+// @BasePath		/api/v1
+// @Summary		Get uptime
+// @Description	Get uptime
+// @Tags			metrics,websocket
+// @Produce   json
+// @Param			request	query		UptimeRequest	false	"Request"
+// @Success		200		{object}	uptime.StatusByAlias "no period specified"
+// @Success		200		{object}	UptimeAggregate "period specified"
+// @Success   204   {object}	apitypes.ErrorResponse
+// @Failure		400		{object}	apitypes.ErrorResponse
+// @Failure		403		{object}	apitypes.ErrorResponse
+// @Failure		500		{object}	apitypes.ErrorResponse
+// @Router			/metrics/uptime [get]
+func Uptime(c *gin.Context) {
+	uptime.Poller.ServeHTTP(c)
+}

internal/api/v1/new_agent.go

@@ -1,141 +0,0 @@
-package v1
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"os"
-	"strconv"
-
-	_ "embed"
-
-	"github.com/yusing/go-proxy/agent/pkg/agent"
-	"github.com/yusing/go-proxy/agent/pkg/certs"
-	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-)
-
-func NewAgent(w http.ResponseWriter, r *http.Request) {
-	q := r.URL.Query()
-	name := q.Get("name")
-	if name == "" {
-		gphttp.MissingKey(w, "name")
-		return
-	}
-	host := q.Get("host")
-	if host == "" {
-		gphttp.MissingKey(w, "host")
-		return
-	}
-	portStr := q.Get("port")
-	if portStr == "" {
-		gphttp.MissingKey(w, "port")
-		return
-	}
-	port, err := strconv.Atoi(portStr)
-	if err != nil || port < 1 || port > 65535 {
-		gphttp.InvalidKey(w, "port")
-		return
-	}
-	hostport := fmt.Sprintf("%s:%d", host, port)
-	if _, ok := agent.GetAgent(hostport); ok {
-		gphttp.KeyAlreadyExists(w, "agent", hostport)
-		return
-	}
-	t := q.Get("type")
-	switch t {
-	case "docker", "system":
-		break
-	case "":
-		gphttp.MissingKey(w, "type")
-		return
-	default:
-		gphttp.InvalidKey(w, "type")
-		return
-	}
-
-	nightly, _ := strconv.ParseBool(q.Get("nightly"))
-	var image string
-	if nightly {
-		image = agent.DockerImageNightly
-	} else {
-		image = agent.DockerImageProduction
-	}
-
-	ca, srv, client, err := agent.NewAgent()
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-
-	var cfg agent.Generator = &agent.AgentEnvConfig{
-		Name:    name,
-		Port:    port,
-		CACert:  ca.String(),
-		SSLCert: srv.String(),
-	}
-	if t == "docker" {
-		cfg = &agent.AgentComposeConfig{
-			Image:          image,
-			AgentEnvConfig: cfg.(*agent.AgentEnvConfig),
-		}
-	}
-	template, err := cfg.Generate()
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-
-	gphttp.RespondJSON(w, r, map[string]any{
-		"compose": template,
-		"ca":      ca,
-		"client":  client,
-	})
-}
-
-func VerifyNewAgent(w http.ResponseWriter, r *http.Request) {
-	defer r.Body.Close()
-	clientPEMData, err := io.ReadAll(r.Body)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-
-	var data struct {
-		Host   string        `json:"host"`
-		CA     agent.PEMPair `json:"ca"`
-		Client agent.PEMPair `json:"client"`
-	}
-
-	if err := json.Unmarshal(clientPEMData, &data); err != nil {
-		gphttp.ClientError(w, r, err)
-		return
-	}
-
-	nRoutesAdded, err := config.GetInstance().VerifyNewAgent(data.Host, data.CA, data.Client)
-	if err != nil {
-		gphttp.ClientError(w, r, err)
-		return
-	}
-
-	zip, err := certs.ZipCert(data.CA.Cert, data.Client.Cert, data.Client.Key)
-	if err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-
-	filename, ok := certs.AgentCertsFilepath(data.Host)
-	if !ok {
-		gphttp.InvalidKey(w, "host")
-		return
-	}
-
-	if err := os.WriteFile(filename, zip, 0600); err != nil {
-		gphttp.ServerError(w, r, err)
-		return
-	}
-
-	w.WriteHeader(http.StatusOK)
-	w.Write(fmt.Appendf(nil, "Added %d routes", nRoutesAdded))
-}

internal/api/v1/reload.go

@@ -3,14 +3,26 @@ package v1
 import (
 	"net/http"
 
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
 	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
 )
 
-func Reload(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	if err := cfg.Reload(); err != nil {
-		gphttp.ServerError(w, r, err)
+// @x-id				"reload"
+// @BasePath		/api/v1
+// @Summary		Reload config
+// @Description	Reload config
+// @Tags			v1
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	apitypes.SuccessResponse
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/reload [post]
+func Reload(c *gin.Context) {
+	if err := config.GetInstance().Reload(); err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to reload config"))
 		return
 	}
-	gphttp.WriteBody(w, []byte("OK"))
+	c.JSON(http.StatusOK, apitypes.Success("config reloaded"))
 }

internal/api/v1/route/by_provider.go

@@ -0,0 +1,26 @@
+package routeApi
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/route"
+	"github.com/yusing/go-proxy/internal/route/routes"
+)
+
+type RoutesByProvider map[string][]route.Route
+
+// @x-id				"byProvider"
+// @BasePath		/api/v1
+// @Summary		List routes by provider
+// @Description	List routes by provider
+// @Tags			route
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	RoutesByProvider
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/route/by_provider [get]
+func ByProvider(c *gin.Context) {
+	c.JSON(http.StatusOK, routes.ByProvider())
+}

internal/api/v1/route/providers.go

@@ -0,0 +1,33 @@
+package routeApi
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	config "github.com/yusing/go-proxy/internal/config/types"
+	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
+)
+
+// @x-id				"providers"
+// @BasePath		/api/v1
+// @Summary		List route providers
+// @Description	List route providers
+// @Tags			route,websocket
+// @Accept			json
+// @Produce		json
+// @Success		200	{array}		config.RouteProviderListResponse
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/route/providers [get]
+func Providers(c *gin.Context) {
+	cfg := config.GetInstance()
+	if httpheaders.IsWebsocket(c.Request.Header) {
+		websocket.PeriodicWrite(c, 5*time.Second, func() (any, error) {
+			return config.GetInstance().RouteProviderList(), nil
+		})
+	} else {
+		c.JSON(http.StatusOK, cfg.RouteProviderList())
+	}
+}

internal/api/v1/route/route.go

@@ -0,0 +1,41 @@
+package routeApi
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/route/routes"
+)
+
+type ListRouteRequest struct {
+	Which string `uri:"which" validate:"required"`
+} //	@name	ListRouteRequest
+
+// @x-id				"route"
+// @BasePath		/api/v1
+// @Summary		List route
+// @Description	List route
+// @Tags			route
+// @Accept			json
+// @Produce		json
+// @Param			which	path		string	true	"Route name"
+// @Success		200		{object}	RouteType
+// @Failure		400		{object}	apitypes.ErrorResponse
+// @Failure		403		{object}	apitypes.ErrorResponse
+// @Failure		404		{object}	apitypes.ErrorResponse
+// @Router			/route/{which} [get]
+func Route(c *gin.Context) {
+	var request ListRouteRequest
+	if err := c.ShouldBindUri(&request); err != nil {
+		c.JSON(http.StatusBadRequest, apitypes.Error("invalid request", err))
+		return
+	}
+
+	route, ok := routes.Get(request.Which)
+	if ok {
+		c.JSON(http.StatusOK, route)
+	} else {
+		c.JSON(http.StatusNotFound, nil)
+	}
+}

internal/api/v1/route/routes.go

@@ -0,0 +1,68 @@
+package routeApi
+
+import (
+	"net/http"
+	"slices"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
+	"github.com/yusing/go-proxy/internal/route"
+	"github.com/yusing/go-proxy/internal/route/routes"
+	"github.com/yusing/go-proxy/internal/types"
+)
+
+type RouteType route.Route // @name Route
+
+// @x-id				"routes"
+// @BasePath		/api/v1
+// @Summary		List routes
+// @Description	List routes
+// @Tags			route,websocket
+// @Accept			json
+// @Produce		json
+// @Param			provider	query		string	false	"Provider"
+// @Success		200			{array}		RouteType
+// @Failure		403			{object}	apitypes.ErrorResponse
+// @Router			/route/list [get]
+func Routes(c *gin.Context) {
+	if httpheaders.IsWebsocket(c.Request.Header) {
+		RoutesWS(c)
+		return
+	}
+
+	provider := c.Query("provider")
+	if provider == "" {
+		c.JSON(http.StatusOK, slices.Collect(routes.Iter))
+		return
+	}
+
+	rts := make([]types.Route, 0, routes.NumRoutes())
+	for r := range routes.Iter {
+		if r.ProviderName() == provider {
+			rts = append(rts, r)
+		}
+	}
+	c.JSON(http.StatusOK, rts)
+}
+
+func RoutesWS(c *gin.Context) {
+	provider := c.Query("provider")
+	if provider == "" {
+		websocket.PeriodicWrite(c, 3*time.Second, func() (any, error) {
+			return slices.Collect(routes.Iter), nil
+		})
+		return
+	}
+
+	websocket.PeriodicWrite(c, 3*time.Second, func() (any, error) {
+		rts := make([]types.Route, 0, routes.NumRoutes())
+		for r := range routes.Iter {
+			if r.ProviderName() == provider {
+				rts = append(rts, r)
+			}
+		}
+		return rts, nil
+	})
+}

internal/api/v1/stats.go

@@ -4,29 +4,52 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/gorilla/websocket"
+	"github.com/gin-gonic/gin"
 	config "github.com/yusing/go-proxy/internal/config/types"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
 	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/utils/strutils"
 )
 
-func Stats(cfg config.ConfigInstance, w http.ResponseWriter, r *http.Request) {
-	if httpheaders.IsWebsocket(r.Header) {
-		gpwebsocket.Periodic(w, r, 1*time.Second, func(conn *websocket.Conn) error {
-			return conn.WriteJSON(getStats(cfg))
-		})
+type StatsResponse struct {
+	Proxies ProxyStats `json:"proxies"`
+	Uptime  string     `json:"uptime"`
+} //	@name	StatsResponse
+
+type ProxyStats struct {
+	Total          uint16                         `json:"total"`
+	ReverseProxies types.RouteStats               `json:"reverse_proxies"`
+	Streams        types.RouteStats               `json:"streams"`
+	Providers      map[string]types.ProviderStats `json:"providers"`
+} //	@name	ProxyStats
+
+// @x-id				"stats"
+// @BasePath		/api/v1
+// @Summary		Get GoDoxy stats
+// @Description	Get stats
+// @Tags			v1,websocket
+// @Accept			json
+// @Produce		json
+// @Success		200	{object}	StatsResponse
+// @Failure		403	{object}	apitypes.ErrorResponse
+// @Failure		500	{object}	apitypes.ErrorResponse
+// @Router			/stats [get]
+func Stats(c *gin.Context) {
+	cfg := config.GetInstance()
+	getStats := func() (any, error) {
+		return map[string]any{
+			"proxies": cfg.Statistics(),
+			"uptime":  strutils.FormatDuration(time.Since(startTime)),
+		}, nil
+	}
+
+	if httpheaders.IsWebsocket(c.Request.Header) {
+		websocket.PeriodicWrite(c, time.Second, getStats)
 	} else {
-		gphttp.RespondJSON(w, r, getStats(cfg))
+		stats, _ := getStats()
+		c.JSON(http.StatusOK, stats)
 	}
 }
 
 var startTime = time.Now()
-
-func getStats(cfg config.ConfigInstance) map[string]any {
-	return map[string]any{
-		"proxies": cfg.Statistics(),
-		"uptime":  strutils.FormatDuration(time.Since(startTime)),
-	}
-}

internal/api/v1/system_info.go

@@ -1,53 +0,0 @@
-package v1
-
-import (
-	"net/http"
-
-	agentPkg "github.com/yusing/go-proxy/agent/pkg/agent"
-	"github.com/yusing/go-proxy/internal/gperr"
-	"github.com/yusing/go-proxy/internal/metrics/systeminfo"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
-	"github.com/yusing/go-proxy/internal/net/gphttp/reverseproxy"
-	nettypes "github.com/yusing/go-proxy/internal/net/types"
-)
-
-func SystemInfo(w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
-	agentAddr := query.Get("agent_addr")
-	query.Del("agent_addr")
-	if agentAddr == "" {
-		systeminfo.Poller.ServeHTTP(w, r)
-		return
-	}
-
-	agent, ok := agentPkg.GetAgent(agentAddr)
-	if !ok {
-		gphttp.NotFound(w, "agent_addr")
-		return
-	}
-
-	isWS := httpheaders.IsWebsocket(r.Header)
-	if !isWS {
-		respData, status, err := agent.Forward(r, agentPkg.EndpointSystemInfo)
-		if err != nil {
-			gphttp.ServerError(w, r, gperr.Wrap(err, "failed to forward request to agent"))
-			return
-		}
-		if status != http.StatusOK {
-			http.Error(w, string(respData), status)
-			return
-		}
-		gphttp.WriteBody(w, respData)
-	} else {
-		rp := reverseproxy.NewReverseProxy("agent", nettypes.NewURL(agentPkg.AgentURL), agent.Transport())
-		header := r.Header.Clone()
-		r, err := http.NewRequestWithContext(r.Context(), r.Method, agentPkg.EndpointSystemInfo+"?"+query.Encode(), nil)
-		if err != nil {
-			gphttp.ServerError(w, r, gperr.Wrap(err, "failed to create request"))
-			return
-		}
-		r.Header = header
-		rp.ServeHTTP(w, r)
-	}
-}

internal/api/v1/version.go

@@ -0,0 +1,21 @@
+package v1
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yusing/go-proxy/pkg"
+)
+
+// @x-id				"version"
+// @BasePath		/api/v1
+// @Summary		Get version
+// @Description	Get the version of the GoDoxy
+// @Tags			v1
+// @Accept			json
+// @Produce		plain
+// @Success		200	{string}	string	"version"
+// @Router			/version [get]
+func Version(c *gin.Context) {
+	c.JSON(http.StatusOK, pkg.GetVersion().String())
+}

internal/auth/auth.go

@@ -4,7 +4,6 @@ import (
 	"net/http"
 
 	"github.com/yusing/go-proxy/internal/common"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
 )
 
 var defaultAuth Provider
@@ -42,19 +41,6 @@ type nextHandler struct{}
 
 var nextHandlerContextKey = nextHandler{}
 
-func RequireAuth(next http.HandlerFunc) http.HandlerFunc {
-	if !IsEnabled() {
-		return next
-	}
-	return func(w http.ResponseWriter, r *http.Request) {
-		if err := defaultAuth.CheckToken(r); err != nil {
-			gphttp.Unauthorized(w, err.Error())
-			return
-		}
-		next(w, r)
-	}
-}
-
 func ProceedNext(w http.ResponseWriter, r *http.Request) {
 	next, ok := r.Context().Value(nextHandlerContextKey).(http.HandlerFunc)
 	if ok {
@@ -65,7 +51,8 @@ func ProceedNext(w http.ResponseWriter, r *http.Request) {
 }
 
 func AuthCheckHandler(w http.ResponseWriter, r *http.Request) {
-	if err := defaultAuth.CheckToken(r); err != nil {
+	err := defaultAuth.CheckToken(r)
+	if err != nil {
 		defaultAuth.LoginHandler(w, r)
 	} else {
 		w.WriteHeader(http.StatusOK)

internal/auth/oidc.go

@@ -37,6 +37,8 @@ type (
 	}
 )
 
+var _ Provider = (*OIDCProvider)(nil)
+
 const (
 	CookieOauthState        = "godoxy_oidc_state"
 	CookieOauthToken        = "godoxy_oauth_token"   //nolint:gosec
@@ -257,11 +259,11 @@ func (auth *OIDCProvider) PostAuthCallbackHandler(w http.ResponseWriter, r *http
 	// verify state
 	state, err := r.Cookie(CookieOauthState)
 	if err != nil {
-		gphttp.BadRequest(w, "missing state cookie")
+		http.Error(w, "missing state cookie", http.StatusBadRequest)
 		return
 	}
 	if r.URL.Query().Get("state") != state.Value {
-		gphttp.BadRequest(w, "invalid oauth state")
+		http.Error(w, "invalid oauth state", http.StatusBadRequest)
 		return
 	}
 
@@ -335,12 +337,12 @@ func (auth *OIDCProvider) clearCookie(w http.ResponseWriter, r *http.Request) {
 func (auth *OIDCProvider) handleTestCallback(w http.ResponseWriter, r *http.Request) {
 	state, err := r.Cookie(CookieOauthState)
 	if err != nil {
-		gphttp.BadRequest(w, "missing state cookie")
+		http.Error(w, "missing state cookie", http.StatusBadRequest)
 		return
 	}
 
 	if r.URL.Query().Get("state") != state.Value {
-		gphttp.BadRequest(w, "invalid oauth state")
+		http.Error(w, "invalid oauth state", http.StatusBadRequest)
 		return
 	}
 

internal/auth/userpass.go

@@ -32,6 +32,8 @@ type (
 	}
 )
 
+var _ Provider = (*UserPassAuth)(nil)
+
 func NewUserPassAuth(username, password string, secret []byte, tokenTTL time.Duration) (*UserPassAuth, error) {
 	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
 	if err != nil {
@@ -100,18 +102,21 @@ func (auth *UserPassAuth) CheckToken(r *http.Request) error {
 	return nil
 }
 
+type UserPassAuthCallbackRequest struct {
+	User string `json:"username"`
+	Pass string `json:"password"`
+}
+
 func (auth *UserPassAuth) PostAuthCallbackHandler(w http.ResponseWriter, r *http.Request) {
-	var creds struct {
-		User string `json:"username"`
-		Pass string `json:"password"`
-	}
+	var creds UserPassAuthCallbackRequest
 	err := json.NewDecoder(r.Body).Decode(&creds)
 	if err != nil {
-		gphttp.Unauthorized(w, "invalid credentials")
+		http.Error(w, "invalid request", http.StatusBadRequest)
 		return
 	}
 	if err := auth.validatePassword(creds.User, creds.Pass); err != nil {
-		gphttp.Unauthorized(w, "invalid credentials")
+		// NOTE: do not include the actual error here
+		http.Error(w, "invalid credentials", http.StatusBadRequest)
 		return
 	}
 	token, err := auth.NewToken()

internal/config/config.go

@@ -210,7 +210,7 @@ func (cfg *Config) StartServers(opts ...*StartServersOptions) {
 			Name:         "api",
 			CertProvider: cfg.AutoCertProvider(),
 			HTTPAddr:     common.APIHTTPAddr,
-			Handler:      api.NewHandler(cfg),
+			Handler:      api.NewHandler(),
 		})
 	}
 }

internal/config/query.go

@@ -3,6 +3,7 @@ package config
 import (
 	config "github.com/yusing/go-proxy/internal/config/types"
 	"github.com/yusing/go-proxy/internal/route/provider"
+	"github.com/yusing/go-proxy/internal/types"
 )
 
 func (cfg *Config) DumpRouteProviders() map[string]*provider.Provider {
@@ -25,9 +26,9 @@ func (cfg *Config) RouteProviderList() []config.RouteProviderListResponse {
 }
 
 func (cfg *Config) Statistics() map[string]any {
-	var rps, streams provider.RouteStats
+	var rps, streams types.RouteStats
 	var total uint16
-	providerStats := make(map[string]provider.ProviderStats)
+	providerStats := make(map[string]types.ProviderStats)
 
 	for _, p := range cfg.providers.Range {
 		stats := p.Statistics()

internal/config/types/config.go

@@ -45,7 +45,7 @@ type (
 	RouteProviderListResponse struct {
 		ShortName string `json:"short_name"`
 		FullName  string `json:"full_name"`
-	}
+	} // @name RouteProvider
 	ConfigInstance interface {
 		Value() *Config
 		Reload() gperr.Error

internal/docker/container.go

@@ -13,57 +13,19 @@ import (
 	"github.com/docker/go-connections/nat"
 	"github.com/yusing/go-proxy/agent/pkg/agent"
 	"github.com/yusing/go-proxy/internal/gperr"
-	idlewatcher "github.com/yusing/go-proxy/internal/idlewatcher/types"
 	"github.com/yusing/go-proxy/internal/serialization"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/utils"
 )
 
-type (
-	PortMapping = map[int]container.Port
-	Container   struct {
-		_ utils.NoCopy
-
-		DockerHost    string          `json:"docker_host"`
-		Image         *ContainerImage `json:"image"`
-		ContainerName string          `json:"container_name"`
-		ContainerID   string          `json:"container_id"`
-
-		Agent *agent.AgentConfig `json:"agent"`
-
-		Labels            map[string]string   `json:"-"`
-		IdlewatcherConfig *idlewatcher.Config `json:"idlewatcher_config"`
-
-		Mounts []string `json:"mounts"`
-
-		Network            string      `json:"network,omitempty"`
-		PublicPortMapping  PortMapping `json:"public_ports"`  // non-zero publicPort:types.Port
-		PrivatePortMapping PortMapping `json:"private_ports"` // privatePort:types.Port
-		PublicHostname     string      `json:"public_hostname"`
-		PrivateHostname    string      `json:"private_hostname"`
-
-		Aliases           []string `json:"aliases"`
-		IsExcluded        bool     `json:"is_excluded"`
-		IsExplicit        bool     `json:"is_explicit"`
-		IsHostNetworkMode bool     `json:"is_host_network_mode"`
-		Running           bool     `json:"running"`
-
-		Errors *containerError `json:"errors"`
-	}
-	ContainerImage struct {
-		Author string `json:"author,omitempty"`
-		Name   string `json:"name"`
-		Tag    string `json:"tag,omitempty"`
-	}
-)
-
-var DummyContainer = new(Container)
+var DummyContainer = new(types.Container)
 
 var (
 	ErrNetworkNotFound = errors.New("network not found")
 	ErrNoNetwork       = errors.New("no network found")
 )
 
-func FromDocker(c *container.SummaryTrimmed, dockerHost string) (res *Container) {
+func FromDocker(c *container.Summary, dockerHost string) (res *types.Container) {
 	_, isExplicit := c.Labels[LabelAliases]
 	helper := containerHelper{c}
 	if !isExplicit {
@@ -78,7 +40,7 @@ func FromDocker(c *container.SummaryTrimmed, dockerHost string) (res *Container)
 	network := helper.getDeleteLabel(LabelNetwork)
 
 	isExcluded, _ := strconv.ParseBool(helper.getDeleteLabel(LabelExclude))
-	res = &Container{
+	res = &types.Container{
 		DockerHost:    dockerHost,
 		Image:         helper.parseImage(),
 		ContainerName: helper.getName(),
@@ -103,25 +65,25 @@ func FromDocker(c *container.SummaryTrimmed, dockerHost string) (res *Container)
 		var ok bool
 		res.Agent, ok = agent.GetAgent(dockerHost)
 		if !ok {
-			res.addError(fmt.Errorf("agent %q not found", dockerHost))
+			addError(res, fmt.Errorf("agent %q not found", dockerHost))
 		}
 	}
 
-	res.setPrivateHostname(helper)
-	res.setPublicHostname()
-	res.loadDeleteIdlewatcherLabels(helper)
+	setPrivateHostname(res, helper)
+	setPublicHostname(res)
+	loadDeleteIdlewatcherLabels(res, helper)
 
 	if res.PrivateHostname == "" && res.PublicHostname == "" && res.Running {
-		res.addError(ErrNoNetwork)
+		addError(res, ErrNoNetwork)
 	}
 	return
 }
 
-func (c *Container) IsBlacklisted() bool {
-	return c.Image.IsBlacklisted() || c.isDatabase()
+func IsBlacklisted(c *types.Container) bool {
+	return IsBlacklistedImage(c.Image) || isDatabase(c)
 }
 
-func (c *Container) UpdatePorts() error {
+func UpdatePorts(c *types.Container) error {
 	client, err := NewClient(c.DockerHost)
 	if err != nil {
 		return err
@@ -148,15 +110,15 @@ func (c *Container) UpdatePorts() error {
 	return nil
 }
 
-func (c *Container) DockerComposeProject() string {
+func DockerComposeProject(c *types.Container) string {
 	return c.Labels["com.docker.compose.project"]
 }
 
-func (c *Container) DockerComposeService() string {
+func DockerComposeService(c *types.Container) string {
 	return c.Labels["com.docker.compose.service"]
 }
 
-func (c *Container) Dependencies() []string {
+func Dependencies(c *types.Container) []string {
 	deps := c.Labels[LabelDependsOn]
 	if deps == "" {
 		deps = c.Labels["com.docker.compose.depends_on"]
@@ -173,7 +135,7 @@ var databaseMPs = map[string]struct{}{
 	"/var/lib/rabbitmq":        {},
 }
 
-func (c *Container) isDatabase() bool {
+func isDatabase(c *types.Container) bool {
 	for _, m := range c.Mounts {
 		if _, ok := databaseMPs[m]; ok {
 			return true
@@ -190,7 +152,7 @@ func (c *Container) isDatabase() bool {
 	return false
 }
 
-func (c *Container) isLocal() bool {
+func isLocal(c *types.Container) bool {
 	if strings.HasPrefix(c.DockerHost, "unix://") {
 		return true
 	}
@@ -206,11 +168,11 @@ func (c *Container) isLocal() bool {
 	return hostname == "localhost"
 }
 
-func (c *Container) setPublicHostname() {
+func setPublicHostname(c *types.Container) {
 	if !c.Running {
 		return
 	}
-	if c.isLocal() {
+	if isLocal(c) {
 		c.PublicHostname = "127.0.0.1"
 		return
 	}
@@ -222,8 +184,8 @@ func (c *Container) setPublicHostname() {
 	c.PublicHostname = url.Hostname()
 }
 
-func (c *Container) setPrivateHostname(helper containerHelper) {
-	if !c.isLocal() && c.Agent == nil {
+func setPrivateHostname(c *types.Container, helper containerHelper) {
+	if !isLocal(c) && c.Agent == nil {
 		return
 	}
 	if helper.NetworkSettings == nil {
@@ -236,7 +198,7 @@ func (c *Container) setPrivateHostname(helper containerHelper) {
 			return
 		}
 		// try {project_name}_{network_name}
-		if proj := c.DockerComposeProject(); proj != "" {
+		if proj := DockerComposeProject(c); proj != "" {
 			oldNetwork, newNetwork := c.Network, fmt.Sprintf("%s_%s", proj, c.Network)
 			if newNetwork != oldNetwork {
 				v, ok = helper.NetworkSettings.Networks[newNetwork]
@@ -248,7 +210,7 @@ func (c *Container) setPrivateHostname(helper containerHelper) {
 			}
 		}
 		nearest := gperr.DoYouMean(utils.NearestField(c.Network, helper.NetworkSettings.Networks))
-		c.addError(fmt.Errorf("network %q not found, %w", c.Network, nearest))
+		addError(c, fmt.Errorf("network %q not found, %w", c.Network, nearest))
 		return
 	}
 	// fallback to first network if no network is specified
@@ -261,7 +223,7 @@ func (c *Container) setPrivateHostname(helper containerHelper) {
 	}
 }
 
-func (c *Container) loadDeleteIdlewatcherLabels(helper containerHelper) {
+func loadDeleteIdlewatcherLabels(c *types.Container, helper containerHelper) {
 	cfg := map[string]any{
 		"idle_timeout":   helper.getDeleteLabel(LabelIdleTimeout),
 		"wake_timeout":   helper.getDeleteLabel(LabelWakeTimeout),
@@ -269,7 +231,7 @@ func (c *Container) loadDeleteIdlewatcherLabels(helper containerHelper) {
 		"stop_timeout":   helper.getDeleteLabel(LabelStopTimeout),
 		"stop_signal":    helper.getDeleteLabel(LabelStopSignal),
 		"start_endpoint": helper.getDeleteLabel(LabelStartEndpoint),
-		"depends_on":     c.Dependencies(),
+		"depends_on":     Dependencies(c),
 	}
 
 	// ensure it's deleted from labels
@@ -278,8 +240,8 @@ func (c *Container) loadDeleteIdlewatcherLabels(helper containerHelper) {
 	// set only if idlewatcher is enabled
 	idleTimeout := cfg["idle_timeout"]
 	if idleTimeout != "" {
-		idwCfg := new(idlewatcher.Config)
-		idwCfg.Docker = &idlewatcher.DockerConfig{
+		idwCfg := new(types.IdlewatcherConfig)
+		idwCfg.Docker = &types.DockerConfig{
 			DockerHost:    c.DockerHost,
 			ContainerID:   c.ContainerID,
 			ContainerName: c.ContainerName,
@@ -287,16 +249,16 @@ func (c *Container) loadDeleteIdlewatcherLabels(helper containerHelper) {
 
 		err := serialization.MapUnmarshalValidate(cfg, idwCfg)
 		if err != nil {
-			c.addError(err)
+			addError(c, err)
 		} else {
 			c.IdlewatcherConfig = idwCfg
 		}
 	}
 }
 
-func (c *Container) addError(err error) {
+func addError(c *types.Container, err error) {
 	if c.Errors == nil {
-		c.Errors = new(containerError)
+		c.Errors = new(types.ContainerError)
 	}
 	c.Errors.Add(err)
 }

internal/docker/container_helper.go

@@ -4,11 +4,12 @@ import (
 	"strings"
 
 	"github.com/docker/docker/api/types/container"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/utils/strutils"
 )
 
 type containerHelper struct {
-	*container.SummaryTrimmed
+	*container.Summary
 }
 
 // getDeleteLabel gets the value of a label and then deletes it from the container.
@@ -40,10 +41,10 @@ func (c containerHelper) getMounts() []string {
 	return m
 }
 
-func (c containerHelper) parseImage() *ContainerImage {
+func (c containerHelper) parseImage() *types.ContainerImage {
 	colonSep := strutils.SplitRune(c.Image, ':')
 	slashSep := strutils.SplitRune(colonSep[0], '/')
-	im := new(ContainerImage)
+	im := new(types.ContainerImage)
 	if len(slashSep) > 1 {
 		im.Author = strings.Join(slashSep[:len(slashSep)-1], "/")
 		im.Name = slashSep[len(slashSep)-1]
@@ -59,8 +60,8 @@ func (c containerHelper) parseImage() *ContainerImage {
 	return im
 }
 
-func (c containerHelper) getPublicPortMapping() PortMapping {
-	res := make(PortMapping)
+func (c containerHelper) getPublicPortMapping() types.PortMapping {
+	res := make(types.PortMapping)
 	for _, v := range c.Ports {
 		if v.PublicPort == 0 {
 			continue
@@ -70,8 +71,8 @@ func (c containerHelper) getPublicPortMapping() PortMapping {
 	return res
 }
 
-func (c containerHelper) getPrivatePortMapping() PortMapping {
-	res := make(PortMapping)
+func (c containerHelper) getPrivatePortMapping() types.PortMapping {
+	res := make(types.PortMapping)
 	for _, v := range c.Ports {
 		res[int(v.PrivatePort)] = v
 	}

internal/docker/errors.go

@@ -1,34 +0,0 @@
-package docker
-
-import (
-	"encoding/json"
-
-	"github.com/yusing/go-proxy/internal/gperr"
-)
-
-type containerError struct {
-	errs *gperr.Builder
-}
-
-func (e *containerError) Add(err error) {
-	if e.errs == nil {
-		e.errs = gperr.NewBuilder()
-	}
-	e.errs.Add(err)
-}
-
-func (e *containerError) Error() string {
-	if e.errs == nil {
-		return "<niL>"
-	}
-	return e.errs.String()
-}
-
-func (e *containerError) Unwrap() error {
-	return e.errs.Error()
-}
-
-func (e *containerError) MarshalJSON() ([]byte, error) {
-	err := e.errs.Error().(interface{ Plain() []byte })
-	return json.Marshal(string(err.Plain()))
-}

internal/docker/image_blacklist.go

@@ -1,5 +1,7 @@
 package docker
 
+import "github.com/yusing/go-proxy/internal/types"
+
 var imageBlacklist = map[string]struct{}{
 	// pure databases without UI
 	"postgres":  {},
@@ -45,7 +47,7 @@ var authorBlacklist = map[string]struct{}{
 	"docker": {},
 }
 
-func (image *ContainerImage) IsBlacklisted() bool {
+func IsBlacklistedImage(image *types.ContainerImage) bool {
 	_, ok := imageBlacklist[image.Name]
 	if ok {
 		return true

internal/docker/label.go

@@ -6,15 +6,14 @@ import (
 
 	"github.com/goccy/go-yaml"
 	"github.com/yusing/go-proxy/internal/gperr"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/utils/strutils"
 )
 
-type LabelMap = map[string]any
-
 var ErrInvalidLabel = gperr.New("invalid label")
 
-func ParseLabels(labels map[string]string, aliases ...string) (LabelMap, gperr.Error) {
-	nestedMap := make(LabelMap)
+func ParseLabels(labels map[string]string, aliases ...string) (types.LabelMap, gperr.Error) {
+	nestedMap := make(types.LabelMap)
 	errs := gperr.NewBuilder("labels error")
 
 	ExpandWildcard(labels, aliases...)
@@ -38,15 +37,15 @@ func ParseLabels(labels map[string]string, aliases ...string) (LabelMap, gperr.E
 			} else {
 				// If the key doesn't exist, create a new map
 				if _, exists := currentMap[k]; !exists {
-					currentMap[k] = make(LabelMap)
+					currentMap[k] = make(types.LabelMap)
 				}
 				// Move deeper into the nested map
-				m, ok := currentMap[k].(LabelMap)
+				m, ok := currentMap[k].(types.LabelMap)
 				if !ok && currentMap[k] != "" {
 					errs.Add(gperr.Errorf("expect mapping, got %T", currentMap[k]).Subject(lbl))
 					continue
 				} else if !ok {
-					m = make(LabelMap)
+					m = make(types.LabelMap)
 					currentMap[k] = m
 				}
 				currentMap = m

internal/docker/list_containers.go

@@ -21,7 +21,7 @@ var listOptions = container.ListOptions{
 	All: true,
 }
 
-func ListContainers(clientHost string) ([]container.SummaryTrimmed, error) {
+func ListContainers(clientHost string) ([]container.Summary, error) {
 	dockerClient, err := NewClient(clientHost)
 	if err != nil {
 		return nil, err

internal/entrypoint/entrypoint.go

@@ -12,13 +12,14 @@ import (
 	"github.com/yusing/go-proxy/internal/net/gphttp/middleware/errorpage"
 	"github.com/yusing/go-proxy/internal/route/routes"
 	"github.com/yusing/go-proxy/internal/task"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/utils/strutils"
 )
 
 type Entrypoint struct {
 	middleware    *middleware.Middleware
 	accessLogger  *accesslog.AccessLogger
-	findRouteFunc func(host string) (routes.HTTPRoute, error)
+	findRouteFunc func(host string) (types.HTTPRoute, error)
 }
 
 var ErrNoSuchRoute = errors.New("no such route")
@@ -104,7 +105,7 @@ func (ep *Entrypoint) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-func findRouteAnyDomain(host string) (routes.HTTPRoute, error) {
+func findRouteAnyDomain(host string) (types.HTTPRoute, error) {
 	hostSplit := strutils.SplitRune(host, '.')
 	target := hostSplit[0]
 
@@ -114,8 +115,8 @@ func findRouteAnyDomain(host string) (routes.HTTPRoute, error) {
 	return nil, fmt.Errorf("%w: %s", ErrNoSuchRoute, target)
 }
 
-func findRouteByDomains(domains []string) func(host string) (routes.HTTPRoute, error) {
-	return func(host string) (routes.HTTPRoute, error) {
+func findRouteByDomains(domains []string) func(host string) (types.HTTPRoute, error) {
+	return func(host string) (types.HTTPRoute, error) {
 		for _, domain := range domains {
 			if strings.HasSuffix(host, domain) {
 				target := strings.TrimSuffix(host, domain)

internal/homepage/homepage.go

@@ -8,8 +8,8 @@ import (
 )
 
 type (
-	Homepage map[string]Category
-	Category []*Item
+	Homepage map[string]Category // @name HomepageItems
+	Category []*Item             // @name HomepageCategory
 
 	ItemConfig struct {
 		Show        bool     `json:"show"`
@@ -23,6 +23,7 @@ type (
 
 	Item struct {
 		*ItemConfig
+
 		WidgetConfig *widgets.Config `json:"widget_config,omitempty" aliases:"widget"`
 
 		Alias     string `json:"alias"`

internal/homepage/list_icons.go

@@ -150,9 +150,9 @@ func ListAvailableIcons() (*Cache, error) {
 	return iconsCache, nil
 }
 
-func SearchIcons(keyword string, limit int) ([]IconMetaSearch, error) {
+func SearchIcons(keyword string, limit int) []IconMetaSearch {
 	if keyword == "" {
-		return make([]IconMetaSearch, 0), nil
+		return make([]IconMetaSearch, 0)
 	}
 	iconsCache.RLock()
 	defer iconsCache.RUnlock()
@@ -174,7 +174,7 @@ func SearchIcons(keyword string, limit int) ([]IconMetaSearch, error) {
 			break
 		}
 	}
-	return result, nil
+	return result
 }
 
 func HasIcon(icon *IconURL) bool {

internal/idlewatcher/handle_http.go

@@ -1,11 +1,12 @@
 package idlewatcher
 
 import (
+	"fmt"
 	"net/http"
 	"strconv"
 	"time"
 
-	"github.com/yusing/go-proxy/internal/api/v1/favicon"
+	api "github.com/yusing/go-proxy/internal/api/v1"
 	gphttp "github.com/yusing/go-proxy/internal/net/gphttp"
 	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
 )
@@ -62,7 +63,14 @@ func (w *Watcher) wakeFromHTTP(rw http.ResponseWriter, r *http.Request) (shouldN
 
 	// handle favicon request
 	if isFaviconPath(r.URL.Path) {
-		favicon.GetFavIconFromAlias(rw, r, w.route.Name())
+		result := api.GetFavIconFromAlias(r.Context(), w.route.Name())
+		if !result.OK() {
+			rw.WriteHeader(result.StatusCode)
+			fmt.Fprint(rw, result.ErrMsg)
+			return false
+		}
+		rw.Header().Set("Content-Type", result.ContentType())
+		rw.WriteHeader(result.StatusCode)
 		return false
 	}
 

internal/idlewatcher/health.go

@@ -6,7 +6,7 @@ import (
 	"github.com/yusing/go-proxy/internal/gperr"
 	idlewatcher "github.com/yusing/go-proxy/internal/idlewatcher/types"
 	"github.com/yusing/go-proxy/internal/task"
-	"github.com/yusing/go-proxy/internal/watcher/health"
+	"github.com/yusing/go-proxy/internal/types"
 )
 
 // Start implements health.HealthMonitor.
@@ -50,18 +50,18 @@ func (w *Watcher) Latency() time.Duration {
 }
 
 // Status implements health.HealthMonitor.
-func (w *Watcher) Status() health.Status {
+func (w *Watcher) Status() types.HealthStatus {
 	state := w.state.Load()
 	if state.err != nil {
-		return health.StatusError
+		return types.StatusError
 	}
 	if state.ready {
-		return health.StatusHealthy
+		return types.StatusHealthy
 	}
 	if state.status == idlewatcher.ContainerStatusRunning {
-		return health.StatusStarting
+		return types.StatusStarting
 	}
-	return health.StatusNapping
+	return types.StatusNapping
 }
 
 // Detail implements health.HealthMonitor.
@@ -89,7 +89,7 @@ func (w *Watcher) MarshalJSON() ([]byte, error) {
 	if err := w.error(); err != nil {
 		detail = err.Error()
 	}
-	return (&health.JSONRepresentation{
+	return (&types.HealthJSONRepr{
 		Name:   w.Name(),
 		Status: w.Status(),
 		Config: dummyHealthCheckConfig,

internal/idlewatcher/provider/docker.go

@@ -7,6 +7,7 @@ import (
 	"github.com/yusing/go-proxy/internal/docker"
 	"github.com/yusing/go-proxy/internal/gperr"
 	idlewatcher "github.com/yusing/go-proxy/internal/idlewatcher/types"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/watcher"
 )
 
@@ -42,14 +43,14 @@ func (p *DockerProvider) ContainerStart(ctx context.Context) error {
 	return p.client.ContainerStart(ctx, p.containerID, startOptions)
 }
 
-func (p *DockerProvider) ContainerStop(ctx context.Context, signal idlewatcher.Signal, timeout int) error {
+func (p *DockerProvider) ContainerStop(ctx context.Context, signal types.ContainerSignal, timeout int) error {
 	return p.client.ContainerStop(ctx, p.containerID, container.StopOptions{
 		Signal:  string(signal),
 		Timeout: &timeout,
 	})
 }
 
-func (p *DockerProvider) ContainerKill(ctx context.Context, signal idlewatcher.Signal) error {
+func (p *DockerProvider) ContainerKill(ctx context.Context, signal types.ContainerSignal) error {
 	return p.client.ContainerKill(ctx, p.containerID, string(signal))
 }
 

internal/idlewatcher/provider/proxmox.go

@@ -8,6 +8,7 @@ import (
 	"github.com/yusing/go-proxy/internal/gperr"
 	idlewatcher "github.com/yusing/go-proxy/internal/idlewatcher/types"
 	"github.com/yusing/go-proxy/internal/proxmox"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/watcher"
 	"github.com/yusing/go-proxy/internal/watcher/events"
 )
@@ -52,11 +53,11 @@ func (p *ProxmoxProvider) ContainerStart(ctx context.Context) error {
 	return p.LXCAction(ctx, p.vmid, proxmox.LXCStart)
 }
 
-func (p *ProxmoxProvider) ContainerStop(ctx context.Context, _ idlewatcher.Signal, _ int) error {
+func (p *ProxmoxProvider) ContainerStop(ctx context.Context, _ types.ContainerSignal, _ int) error {
 	return p.LXCAction(ctx, p.vmid, proxmox.LXCShutdown)
 }
 
-func (p *ProxmoxProvider) ContainerKill(ctx context.Context, _ idlewatcher.Signal) error {
+func (p *ProxmoxProvider) ContainerKill(ctx context.Context, _ types.ContainerSignal) error {
 	return p.LXCAction(ctx, p.vmid, proxmox.LXCShutdown)
 }
 

internal/idlewatcher/types/config.go

@@ -1,138 +1 @@
 package idlewatcher
-
-import (
-	"net/url"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/yusing/go-proxy/internal/gperr"
-)
-
-type (
-	ProviderConfig struct {
-		Proxmox *ProxmoxConfig `json:"proxmox,omitempty"`
-		Docker  *DockerConfig  `json:"docker,omitempty"`
-	}
-	IdlewatcherConfig struct {
-		// 0: no idle watcher.
-		// Positive: idle watcher with idle timeout.
-		// Negative: idle watcher as a dependency.	IdleTimeout time.Duration `json:"idle_timeout" json_ext:"duration"`
-		IdleTimeout time.Duration `json:"idle_timeout"`
-		WakeTimeout time.Duration `json:"wake_timeout"`
-		StopTimeout time.Duration `json:"stop_timeout"`
-		StopMethod  StopMethod    `json:"stop_method"`
-		StopSignal  Signal        `json:"stop_signal,omitempty"`
-	}
-	Config struct {
-		ProviderConfig
-		IdlewatcherConfig
-
-		StartEndpoint string   `json:"start_endpoint,omitempty"` // Optional path that must be hit to start container
-		DependsOn     []string `json:"depends_on,omitempty"`
-	}
-	StopMethod string
-	Signal     string
-
-	DockerConfig struct {
-		DockerHost    string `json:"docker_host" validate:"required"`
-		ContainerID   string `json:"container_id" validate:"required"`
-		ContainerName string `json:"container_name" validate:"required"`
-	}
-	ProxmoxConfig struct {
-		Node string `json:"node" validate:"required"`
-		VMID int    `json:"vmid" validate:"required"`
-	}
-)
-
-const (
-	WakeTimeoutDefault = 30 * time.Second
-	StopTimeoutDefault = 1 * time.Minute
-
-	StopMethodPause StopMethod = "pause"
-	StopMethodStop  StopMethod = "stop"
-	StopMethodKill  StopMethod = "kill"
-)
-
-func (c *Config) Key() string {
-	if c.Docker != nil {
-		return c.Docker.ContainerID
-	}
-	return c.Proxmox.Node + ":" + strconv.Itoa(c.Proxmox.VMID)
-}
-
-func (c *Config) ContainerName() string {
-	if c.Docker != nil {
-		return c.Docker.ContainerName
-	}
-	return "lxc-" + strconv.Itoa(c.Proxmox.VMID)
-}
-
-func (c *Config) Validate() gperr.Error {
-	if c.IdleTimeout == 0 { // zero idle timeout means no idle watcher
-		return nil
-	}
-	errs := gperr.NewBuilder("idlewatcher config validation error")
-	errs.AddRange(
-		c.validateProvider(),
-		c.validateTimeouts(),
-		c.validateStopMethod(),
-		c.validateStopSignal(),
-		c.validateStartEndpoint(),
-	)
-	return errs.Error()
-}
-
-func (c *Config) validateProvider() error {
-	if c.Docker == nil && c.Proxmox == nil {
-		return gperr.New("missing idlewatcher provider config")
-	}
-	return nil
-}
-
-func (c *Config) validateTimeouts() error { //nolint:unparam
-	if c.WakeTimeout == 0 {
-		c.WakeTimeout = WakeTimeoutDefault
-	}
-	if c.StopTimeout == 0 {
-		c.StopTimeout = StopTimeoutDefault
-	}
-	return nil
-}
-
-func (c *Config) validateStopMethod() error {
-	switch c.StopMethod {
-	case "":
-		c.StopMethod = StopMethodStop
-		return nil
-	case StopMethodPause, StopMethodStop, StopMethodKill:
-		return nil
-	default:
-		return gperr.New("invalid stop method").Subject(string(c.StopMethod))
-	}
-}
-
-func (c *Config) validateStopSignal() error {
-	switch c.StopSignal {
-	case "", "SIGINT", "SIGTERM", "SIGQUIT", "SIGHUP", "INT", "TERM", "QUIT", "HUP":
-		return nil
-	default:
-		return gperr.New("invalid stop signal").Subject(string(c.StopSignal))
-	}
-}
-
-func (c *Config) validateStartEndpoint() error {
-	if c.StartEndpoint == "" {
-		return nil
-	}
-	// checks needed as of Go 1.6 because of change https://github.com/golang/go/commit/617c93ce740c3c3cc28cdd1a0d712be183d0b328#diff-6c2d018290e298803c0c9419d8739885L195
-	// emulate browser and strip the '#' suffix prior to validation. see issue-#237
-	if i := strings.Index(c.StartEndpoint, "#"); i > -1 {
-		c.StartEndpoint = c.StartEndpoint[:i]
-	}
-	if len(c.StartEndpoint) == 0 {
-		return gperr.New("start endpoint must not be empty if defined")
-	}
-	_, err := url.ParseRequestURI(c.StartEndpoint)
-	return err
-}

internal/idlewatcher/types/provider.go

@@ -4,6 +4,7 @@ import (
 	"context"
 
 	"github.com/yusing/go-proxy/internal/gperr"
+	"github.com/yusing/go-proxy/internal/types"
 	"github.com/yusing/go-proxy/internal/watcher/events"
 )
 
@@ -11,8 +12,8 @@ type Provider interface {
 	ContainerPause(ctx context.Context) error
 	ContainerUnpause(ctx context.Context) error
 	ContainerStart(ctx context.Context) error
-	ContainerStop(ctx context.Context, signal Signal, timeout int) error
-	ContainerKill(ctx context.Context, signal Signal) error
+	ContainerStop(ctx context.Context, signal types.ContainerSignal, timeout int) error
+	ContainerKill(ctx context.Context, signal types.ContainerSignal) error
 	ContainerStatus(ctx context.Context) (ContainerStatus, error)
 	Watch(ctx context.Context) (eventCh <-chan events.Event, errCh <-chan gperr.Error)
 	Close()

internal/idlewatcher/types/waker.go

@@ -4,11 +4,11 @@ import (
 	"net/http"
 
 	nettypes "github.com/yusing/go-proxy/internal/net/types"
-	"github.com/yusing/go-proxy/internal/watcher/health"
+	"github.com/yusing/go-proxy/internal/types"
 )
 
 type Waker interface {
-	health.HealthMonitor
+	types.HealthMonitor
 	http.Handler
 	nettypes.Stream
 	Wake() error

internal/idlewatcher/watcher.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
+	"github.com/yusing/go-proxy/internal/docker"
 	"github.com/yusing/go-proxy/internal/gperr"
 	"github.com/yusing/go-proxy/internal/idlewatcher/provider"
 	idlewatcher "github.com/yusing/go-proxy/internal/idlewatcher/types"
@@ -17,10 +18,10 @@ import (
 	nettypes "github.com/yusing/go-proxy/internal/net/types"
 	"github.com/yusing/go-proxy/internal/route/routes"
 	"github.com/yusing/go-proxy/internal/task"
+	"github.com/yusing/go-proxy/internal/types"
 	U "github.com/yusing/go-proxy/internal/utils"
 	"github.com/yusing/go-proxy/internal/utils/atomic"
 	"github.com/yusing/go-proxy/internal/watcher/events"
-	"github.com/yusing/go-proxy/internal/watcher/health"
 	"github.com/yusing/go-proxy/internal/watcher/health/monitor"
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/sync/singleflight"
@@ -28,10 +29,10 @@ import (
 
 type (
 	routeHelper struct {
-		route  routes.Route
+		route  types.Route
 		rp     *reverseproxy.ReverseProxy
 		stream nettypes.Stream
-		hc     health.HealthChecker
+		hc     types.HealthChecker
 	}
 
 	containerState struct {
@@ -46,7 +47,7 @@ type (
 
 		l zerolog.Logger
 
-		cfg *idlewatcher.Config
+		cfg *types.IdlewatcherConfig
 
 		provider idlewatcher.Provider
 
@@ -80,7 +81,7 @@ const (
 	idleWakerCheckTimeout  = time.Second
 )
 
-var dummyHealthCheckConfig = &health.HealthCheckConfig{
+var dummyHealthCheckConfig = &types.HealthCheckConfig{
 	Interval: idleWakerCheckInterval,
 	Timeout:  idleWakerCheckTimeout,
 }
@@ -96,7 +97,7 @@ const reqTimeout = 3 * time.Second
 const neverTick = time.Duration(1<<63 - 1)
 
 // TODO: fix stream type.
-func NewWatcher(parent task.Parent, r routes.Route, cfg *idlewatcher.Config) (*Watcher, error) {
+func NewWatcher(parent task.Parent, r types.Route, cfg *types.IdlewatcherConfig) (*Watcher, error) {
 	key := cfg.Key()
 
 	watcherMapMu.RLock()
@@ -109,7 +110,7 @@ func NewWatcher(parent task.Parent, r routes.Route, cfg *idlewatcher.Config) (*W
 			w.cfg.DependsOn = cfg.DependsOn
 		}
 		if cfg.IdleTimeout > 0 {
-			w.cfg.IdlewatcherConfig = cfg.IdlewatcherConfig
+			w.cfg.IdlewatcherConfigBase = cfg.IdlewatcherConfigBase
 		}
 		cfg = w.cfg
 		w.resetIdleTimer()
@@ -147,12 +148,12 @@ func NewWatcher(parent task.Parent, r routes.Route, cfg *idlewatcher.Config) (*W
 
 		cont := r.ContainerInfo()
 
-		var depRoute routes.Route
+		var depRoute types.Route
 		var ok bool
 
 		// try to find the dependency in the same provider and the same docker compose project first
 		if cont != nil {
-			depRoute, ok = r.GetProvider().FindService(cont.DockerComposeProject(), dep)
+			depRoute, ok = r.GetProvider().FindService(docker.DockerComposeProject(cont), dep)
 		}
 
 		if !ok {
@@ -178,8 +179,8 @@ func NewWatcher(parent task.Parent, r routes.Route, cfg *idlewatcher.Config) (*W
 
 		depCfg := depRoute.IdlewatcherConfig()
 		if depCfg == nil {
-			depCfg = new(idlewatcher.Config)
-			depCfg.IdlewatcherConfig = cfg.IdlewatcherConfig
+			depCfg = new(types.IdlewatcherConfig)
+			depCfg.IdlewatcherConfigBase = cfg.IdlewatcherConfigBase
 			depCfg.IdleTimeout = neverTick // disable auto sleep for dependencies
 		} else if depCfg.IdleTimeout > 0 {
 			depErrors.Addf("dependency %q has positive idle timeout %s", dep, depCfg.IdleTimeout)
@@ -189,12 +190,12 @@ func NewWatcher(parent task.Parent, r routes.Route, cfg *idlewatcher.Config) (*W
 		if depCfg.Docker == nil && depCfg.Proxmox == nil {
 			depCont := depRoute.ContainerInfo()
 			if depCont != nil {
-				depCfg.Docker = &idlewatcher.DockerConfig{
+				depCfg.Docker = &types.DockerConfig{
 					DockerHost:    depCont.DockerHost,
 					ContainerID:   depCont.ContainerID,
 					ContainerName: depCont.ContainerName,
 				}
-				depCfg.DependsOn = depCont.Dependencies()
+				depCfg.DependsOn = docker.Dependencies(depCont)
 			} else {
 				depErrors.Addf("dependency %q has no idlewatcher config but is not a docker container", dep)
 				continue
@@ -258,9 +259,9 @@ func NewWatcher(parent task.Parent, r routes.Route, cfg *idlewatcher.Config) (*W
 	w.provider = p
 
 	switch r := r.(type) {
-	case routes.ReverseProxyRoute:
+	case types.ReverseProxyRoute:
 		w.rp = r.ReverseProxy()
-	case routes.StreamRoute:
+	case types.StreamRoute:
 		w.stream = r.Stream()
 	default:
 		w.provider.Close()
@@ -443,11 +444,11 @@ func (w *Watcher) stopByMethod() error {
 	// stop itself first.
 	var err error
 	switch cfg.StopMethod {
-	case idlewatcher.StopMethodPause:
+	case types.ContainerStopMethodPause:
 		err = w.provider.ContainerPause(ctx)
-	case idlewatcher.StopMethodStop:
+	case types.ContainerStopMethodStop:
 		err = w.provider.ContainerStop(ctx, cfg.StopSignal, int(cfg.StopTimeout.Seconds()))
-	case idlewatcher.StopMethodKill:
+	case types.ContainerStopMethodKill:
 		err = w.provider.ContainerKill(ctx, cfg.StopSignal)
 	default:
 		err = w.newWatcherError(gperr.Errorf("unexpected stop method: %q", cfg.StopMethod))

internal/jsonstore/jsonstore.go

@@ -51,6 +51,11 @@ func init() {
 func loadNS[T store](ns namespace) T {
 	store := reflect.New(reflect.TypeFor[T]().Elem()).Interface().(T)
 	store.Initialize()
+
+	if common.IsTest {
+		return store
+	}
+
 	path := filepath.Join(storesPath, string(ns)+".json")
 	file, err := os.Open(path)
 	if err != nil {

internal/logging/accesslog/config.go

@@ -13,7 +13,7 @@ type (
 		Path           string        `json:"path"`
 		Stdout         bool          `json:"stdout"`
 		Retention      *Retention    `json:"retention" aliases:"keep"`
-		RotateInterval time.Duration `json:"rotate_interval,omitempty"`
+		RotateInterval time.Duration `json:"rotate_interval,omitempty" swaggertype:"primitive,integer"`
 	}
 	ACLLoggerConfig struct {
 		ConfigBase
@@ -24,7 +24,7 @@ type (
 		Format  Format  `json:"format" validate:"oneof=common combined json"`
 		Filters Filters `json:"filters"`
 		Fields  Fields  `json:"fields"`
-	}
+	} // @name RequestLoggerConfig
 	Config struct {
 		*ConfigBase
 		acl *ACLLoggerConfig

internal/logging/accesslog/filter.go

@@ -14,19 +14,19 @@ type (
 	LogFilter[T Filterable] struct {
 		Negative bool
 		Values   []T
-	}
+	} // @name LogFilter
 	Filterable interface {
 		comparable
 		Fulfill(req *http.Request, res *http.Response) bool
 	}
-	HTTPMethod string
+	HTTPMethod string // @name HTTPMethod
 	HTTPHeader struct {
 		Key, Value string
-	}
-	Host string
+	} // @name HTTPHeader
+	Host string // @name Host
 	CIDR struct {
 		nettypes.CIDR
-	}
+	} // @name CIDR
 )
 
 var ErrInvalidHTTPHeaderFilter = gperr.New("invalid http header filter")

internal/logging/accesslog/retention.go

@@ -12,7 +12,7 @@ type Retention struct {
 	Days     uint64 `json:"days"`
 	Last     uint64 `json:"last"`
 	KeepSize uint64 `json:"keep_size"`
-}
+} // @name LogRetention
 
 var (
 	ErrInvalidSyntax = gperr.New("invalid syntax")

internal/logging/accesslog/status_code_range.go

@@ -10,7 +10,7 @@ import (
 type StatusCodeRange struct {
 	Start int
 	End   int
-}
+} // @name StatusCodeRange
 
 var ErrInvalidStatusCodeRange = gperr.New("invalid status code range")
 

internal/logging/memlogger/mem_logger.go

@@ -4,13 +4,13 @@ import (
 	"bytes"
 	"context"
 	"io"
-	"net/http"
 	"sync"
 	"time"
 
-	"github.com/gorilla/websocket"
+	"github.com/gin-gonic/gin"
 	"github.com/puzpuzpuz/xsync/v4"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
 )
 
 type logEntryRange struct {
@@ -20,6 +20,7 @@ type logEntryRange struct {
 type memLogger struct {
 	*bytes.Buffer
 	sync.RWMutex
+
 	notifyLock sync.RWMutex
 	connChans  *xsync.Map[chan *logEntryRange, struct{}]
 	listeners  *xsync.Map[chan []byte, struct{}]
@@ -31,6 +32,7 @@ const (
 	maxMemLogSize         = 16 * 1024
 	truncateSize          = maxMemLogSize / 2
 	initialWriteChunkSize = 4 * 1024
+	writeTimeout          = 10 * time.Second
 )
 
 var memLoggerInstance = &memLogger{
@@ -43,11 +45,7 @@ func GetMemLogger() MemLogger {
 	return memLoggerInstance
 }
 
-func Handler() http.Handler {
-	return memLoggerInstance
-}
-
-func HandlerFunc() http.HandlerFunc {
+func HandlerFunc() gin.HandlerFunc {
 	return memLoggerInstance.ServeHTTP
 }
 
@@ -70,9 +68,10 @@ func (m *memLogger) Write(p []byte) (n int, err error) {
 	return
 }
 
-func (m *memLogger) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	conn, err := gpwebsocket.Initiate(w, r)
+func (m *memLogger) ServeHTTP(c *gin.Context) {
+	manager, err := websocket.NewManagerWithUpgrade(c)
 	if err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to create websocket manager"))
 		return
 	}
 
@@ -80,20 +79,19 @@ func (m *memLogger) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	m.connChans.Store(logCh, struct{}{})
 
 	defer func() {
-		_ = conn.Close()
-
+		manager.Close()
 		m.notifyLock.Lock()
 		m.connChans.Delete(logCh)
 		close(logCh)
 		m.notifyLock.Unlock()
 	}()
 
-	if err := m.wsInitial(conn); err != nil {
-		http.Error(w, err.Error(), http.StatusInternalServerError)
+	if err := m.wsInitial(manager); err != nil {
+		c.Error(apitypes.InternalServerError(err, "failed to send initial log"))
 		return
 	}
 
-	m.wsStreamLog(r.Context(), conn, logCh)
+	m.wsStreamLog(c.Request.Context(), manager, logCh)
 }
 
 func (m *memLogger) truncateIfNeeded(n int) {
@@ -168,19 +166,14 @@ func (m *memLogger) events() (logs <-chan []byte, cancel func()) {
 	}
 }
 
-func (m *memLogger) writeBytes(conn *websocket.Conn, b []byte) error {
-	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
-	return conn.WriteMessage(websocket.TextMessage, b)
-}
-
-func (m *memLogger) wsInitial(conn *websocket.Conn) error {
+func (m *memLogger) wsInitial(manager *websocket.Manager) error {
 	m.Lock()
 	defer m.Unlock()
 
-	return m.writeBytes(conn, m.Bytes())
+	return manager.WriteData(websocket.TextMessage, m.Bytes(), writeTimeout)
 }
 
-func (m *memLogger) wsStreamLog(ctx context.Context, conn *websocket.Conn, ch <-chan *logEntryRange) {
+func (m *memLogger) wsStreamLog(ctx context.Context, manager *websocket.Manager, ch <-chan *logEntryRange) {
 	for {
 		select {
 		case <-ctx.Done():
@@ -188,7 +181,7 @@ func (m *memLogger) wsStreamLog(ctx context.Context, conn *websocket.Conn, ch <-
 		case logRange := <-ch:
 			m.RLock()
 			msg := m.Bytes()[logRange.Start:logRange.End]
-			err := m.writeBytes(conn, msg)
+			err := manager.WriteData(websocket.TextMessage, msg, writeTimeout)
 			m.RUnlock()
 			if err != nil {
 				return

internal/maxmind/maxmind.go

@@ -2,6 +2,7 @@ package maxmind
 
 import (
 	"archive/tar"
+	"bytes"
 	"compress/gzip"
 	"errors"
 	"fmt"
@@ -19,8 +20,15 @@ import (
 	"github.com/yusing/go-proxy/internal/task"
 )
 
+/*
+refactor(maxmind): switch to Country database
+
+- In compliance with [Title 28 of the Code of Federal Regulations of the United States of America Part 202](https://www.ecfr.gov/current/title-28/chapter-I/part-202), non US IPs are blocked from downloading the City database
+*/
+
 type MaxMind struct {
 	*Config
+
 	lastUpdate time.Time
 	db         struct {
 		*maxminddb.Reader
@@ -49,24 +57,21 @@ var (
 )
 
 func (cfg *MaxMind) dbPath() string {
-	if cfg.Database == maxmind.MaxMindGeoLite {
-		return filepath.Join(dataDir, "GeoLite2-City.mmdb")
-	}
-	return filepath.Join(dataDir, "GeoIP2-City.mmdb")
+	return filepath.Join(dataDir, cfg.dbFilename())
 }
 
 func (cfg *MaxMind) dbURL() string {
 	if cfg.Database == maxmind.MaxMindGeoLite {
-		return "https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz"
+		return "https://download.maxmind.com/geoip/databases/GeoLite2-Country/download?suffix=tar.gz"
 	}
-	return "https://download.maxmind.com/geoip/databases/GeoIP2-City/download?suffix=tar.gz"
+	return "https://download.maxmind.com/geoip/databases/GeoIP2-Country/download?suffix=tar.gz"
 }
 
 func (cfg *MaxMind) dbFilename() string {
 	if cfg.Database == maxmind.MaxMindGeoLite {
-		return "GeoLite2-City.mmdb"
+		return "GeoLite2-Country.mmdb"
 	}
-	return "GeoIP2-City.mmdb"
+	return "GeoIP2-Country.mmdb"
 }
 
 func (cfg *MaxMind) LoadMaxMindDB(parent task.Parent) gperr.Error {
@@ -219,34 +224,17 @@ func (cfg *MaxMind) download() error {
 	}
 
 	dbFile := dbPath(cfg)
-	tmpGZPath := dbFile + "-tmp.tar.gz"
 	tmpDBPath := dbFile + "-tmp"
 
-	tmpGZFile, err := os.OpenFile(tmpGZPath, os.O_CREATE|os.O_RDWR, 0o644)
-	if err != nil {
-		return err
-	}
-
-	// cleanup the tar.gz file
-	defer func() {
-		_ = tmpGZFile.Close()
-		_ = os.Remove(tmpGZPath)
-	}()
-
 	cfg.Logger().Info().Msg("MaxMind DB downloading...")
 
-	_, err = io.Copy(tmpGZFile, resp.Body)
+	databaseGZ, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return err
 	}
 
-	if _, err := tmpGZFile.Seek(0, io.SeekStart); err != nil {
-		return err
-	}
-
 	// extract .tar.gz and to database
-	err = extractFileFromTarGz(tmpGZFile, cfg.dbFilename(), tmpDBPath)
-
+	err = extractFileFromTarGz(databaseGZ, cfg.dbFilename(), tmpDBPath)
 	if err != nil {
 		return gperr.New("failed to extract database from archive").With(err)
 	}
@@ -284,15 +272,14 @@ func (cfg *MaxMind) download() error {
 	return nil
 }
 
-func extractFileFromTarGz(tarGzFile *os.File, targetFilename, destPath string) error {
-	defer tarGzFile.Close()
-
-	gzr, err := gzip.NewReader(tarGzFile)
+func extractFileFromTarGz(tarGzBytes []byte, targetFilename, destPath string) error {
+	gzr, err := gzip.NewReader(bytes.NewReader(tarGzBytes))
 	if err != nil {
 		return err
 	}
 	defer gzr.Close()
 
+	sumSize := int64(0)
 	tr := tar.NewReader(gzr)
 	for {
 		hdr, err := tr.Next()
@@ -302,6 +289,12 @@ func extractFileFromTarGz(tarGzFile *os.File, targetFilename, destPath string) e
 		if err != nil {
 			return err
 		}
+		// NOTE: it should be around 10MB, but just in case
+		// This is to prevent malicious tar.gz file (e.g. tar bomb)
+		sumSize += hdr.Size
+		if sumSize > 30*1024*1024 {
+			return errors.New("file size exceeds 30MB")
+		}
 		// Only extract the file that matches targetFilename (basename match)
 		if filepath.Base(hdr.Name) == targetFilename {
 			outFile, err := os.OpenFile(destPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, hdr.FileInfo().Mode())
@@ -309,7 +302,7 @@ func extractFileFromTarGz(tarGzFile *os.File, targetFilename, destPath string) e
 				return err
 			}
 			defer outFile.Close()
-			_, err = io.Copy(outFile, tr)
+			_, err = io.CopyN(outFile, tr, hdr.Size)
 			if err != nil {
 				return err
 			}

internal/metrics/period/handler.go

@@ -5,13 +5,18 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/gorilla/websocket"
+	"github.com/gin-gonic/gin"
+	apitypes "github.com/yusing/go-proxy/internal/api/types"
 	metricsutils "github.com/yusing/go-proxy/internal/metrics/utils"
-	"github.com/yusing/go-proxy/internal/net/gphttp"
-	"github.com/yusing/go-proxy/internal/net/gphttp/gpwebsocket"
 	"github.com/yusing/go-proxy/internal/net/gphttp/httpheaders"
+	"github.com/yusing/go-proxy/internal/net/gphttp/websocket"
 )
 
+type ResponseType[AggregateT any] struct {
+	Total int        `json:"total"`
+	Data  AggregateT `json:"data"`
+}
+
 // ServeHTTP serves the data for the given period.
 //
 // If the period is not specified, it serves the last result.
@@ -23,10 +28,10 @@ import (
 // If the data is not found, it returns a 204 error.
 //
 // If the request is a websocket request, it serves the data for the given period for every interval.
-func (p *Poller[T, AggregateT]) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
+func (p *Poller[T, AggregateT]) ServeHTTP(c *gin.Context) {
+	query := c.Request.URL.Query()
 
-	if httpheaders.IsWebsocket(r.Header) {
+	if httpheaders.IsWebsocket(c.Request.Header) {
 		interval := metricsutils.QueryDuration(query, "interval", 0)
 
 		minInterval := 1 * time.Second
@@ -36,27 +41,20 @@ func (p *Poller[T, AggregateT]) ServeHTTP(w http.ResponseWriter, r *http.Request
 		if interval < minInterval {
 			interval = minInterval
 		}
-		gpwebsocket.Periodic(w, r, interval, func(conn *websocket.Conn) error {
-			data, err := p.getRespData(r)
-			if err != nil {
-				return err
-			}
-			if data == nil {
-				return nil
-			}
-			return conn.WriteJSON(data)
+		websocket.PeriodicWrite(c, interval, func() (any, error) {
+			return p.getRespData(c.Request)
 		})
 	} else {
-		data, err := p.getRespData(r)
+		data, err := p.getRespData(c.Request)
 		if err != nil {
-			gphttp.ServerError(w, r, err)
+			c.Error(apitypes.InternalServerError(err, "failed to get response data"))
 			return
 		}
 		if data == nil {
-			http.Error(w, "no data", http.StatusNoContent)
+			c.JSON(http.StatusNoContent, apitypes.Error("no data"))
 			return
 		}
-		gphttp.RespondJSON(w, r, data)
+		c.JSON(http.StatusOK, data)
 	}
 }
 

internal/metrics/period/period.go

@@ -10,16 +10,24 @@ type Period[T any] struct {
 	mu      sync.RWMutex
 }
 
-type Filter string
+type Filter string // @name MetricsPeriod
+
+const (
+	MetricsPeriod5m  Filter = "5m"  // @name MetricsPeriod5m
+	MetricsPeriod15m Filter = "15m" // @name MetricsPeriod15m
+	MetricsPeriod1h  Filter = "1h"  // @name MetricsPeriod1h
+	MetricsPeriod1d  Filter = "1d"  // @name MetricsPeriod1d
+	MetricsPeriod1mo Filter = "1mo" // @name MetricsPeriod1mo
+)
 
 func NewPeriod[T any]() *Period[T] {
 	return &Period[T]{
 		Entries: map[Filter]*Entries[T]{
-			"5m":  newEntries[T](5 * time.Minute),
-			"15m": newEntries[T](15 * time.Minute),
-			"1h":  newEntries[T](1 * time.Hour),
-			"1d":  newEntries[T](24 * time.Hour),
-			"1mo": newEntries[T](30 * 24 * time.Hour),
+			MetricsPeriod5m:  newEntries[T](5 * time.Minute),
+			MetricsPeriod15m: newEntries[T](15 * time.Minute),
+			MetricsPeriod1h:  newEntries[T](1 * time.Hour),
+			MetricsPeriod1d:  newEntries[T](24 * time.Hour),
+			MetricsPeriod1mo: newEntries[T](30 * 24 * time.Hour),
 		},
 	}
 }

internal/metrics/systeminfo/system_info.go

@@ -23,7 +23,7 @@ import (
 // json tags are left for tests
 
 type (
-	Sensors    []sensors.TemperatureStat
+	Sensors    []sensors.TemperatureStat // @name Sensors
 	Aggregated []map[string]any
 )
 
@@ -35,7 +35,7 @@ type SystemInfo struct {
 	DisksIO    map[string]*disk.IOCountersStat `json:"disks_io"` // disk IO by device
 	Network    *net.IOCountersStat             `json:"network"`
 	Sensors    Sensors                         `json:"sensors"` // sensor temperature by key
-}
+} // @name SystemInfo
 
 const (
 	queryCPUAverage         = "cpu_average"

internal/metrics/uptime/uptime.go

@@ -4,35 +4,46 @@ import (
 	"context"
 	"encoding/json"
 	"net/url"
-	"sort"
+	"strings"
 	"time"
 
+	"slices"
+
 	"github.com/lithammer/fuzzysearch/fuzzy"
 	"github.com/yusing/go-proxy/internal/metrics/period"
 	metricsutils "github.com/yusing/go-proxy/internal/metrics/utils"
 	"github.com/yusing/go-proxy/internal/route/routes"
-	"github.com/yusing/go-proxy/internal/watcher/health"
+	"github.com/yusing/go-proxy/internal/types"
 )
 
 type (
 	StatusByAlias struct {
-		Map       map[string]*routes.HealthInfoRaw `json:"statuses"`
-		Timestamp int64                            `json:"timestamp"`
-	}
+		Map       map[string]routes.HealthInfo `json:"statuses"`
+		Timestamp int64                        `json:"timestamp"`
+	} // @name RouteStatusesByAlias
 	Status struct {
-		Status    health.Status `json:"status"`
-		Latency   int64         `json:"latency"`
-		Timestamp int64         `json:"timestamp"`
-	}
-	RouteStatuses map[string][]*Status
-	Aggregated    []map[string]any
+		Status    types.HealthStatus `json:"status" swaggertype:"string" enums:"healthy,unhealthy,unknown,napping,starting"`
+		Latency   int64              `json:"latency"`
+		Timestamp int64              `json:"timestamp"`
+	} // @name RouteStatus
+	RouteStatuses  map[string][]*Status // @name RouteStatuses
+	RouteAggregate struct {
+		Alias       string    `json:"alias"`
+		DisplayName string    `json:"display_name"`
+		Uptime      float64   `json:"uptime"`
+		Downtime    float64   `json:"downtime"`
+		Idle        float64   `json:"idle"`
+		AvgLatency  float64   `json:"avg_latency"`
+		Statuses    []*Status `json:"statuses"`
+	} // @name RouteUptimeAggregate
+	Aggregated []RouteAggregate
 )
 
 var Poller = period.NewPoller("uptime", getStatuses, aggregateStatuses)
 
 func getStatuses(ctx context.Context, _ *StatusByAlias) (*StatusByAlias, error) {
 	return &StatusByAlias{
-		Map:       routes.HealthInfo(),
+		Map:       routes.GetHealthInfo(),
 		Timestamp: time.Now().Unix(),
 	}, nil
 }
@@ -78,11 +89,11 @@ func (rs RouteStatuses) calculateInfo(statuses []*Status) (up float64, down floa
 	latency := float64(0)
 	for _, status := range statuses {
 		// ignoring unknown; treating napping and starting as downtime
-		if status.Status == health.StatusUnknown {
+		if status.Status == types.StatusUnknown {
 			continue
 		}
 		switch {
-		case status.Status == health.StatusHealthy:
+		case status.Status == types.StatusHealthy:
 			up++
 		case status.Status.Idling():
 			idle++
@@ -110,28 +121,39 @@ func (rs RouteStatuses) aggregate(limit int, offset int) Aggregated {
 		sortedAliases[i] = alias
 		i++
 	}
-	sort.Strings(sortedAliases)
+	// unknown statuses are at the end, then sort by alias
+	slices.SortFunc(sortedAliases, func(a, b string) int {
+		if rs[a][len(rs[a])-1].Status == types.StatusUnknown {
+			return 1
+		}
+		if rs[b][len(rs[b])-1].Status == types.StatusUnknown {
+			return -1
+		}
+		return strings.Compare(a, b)
+	})
 	sortedAliases = sortedAliases[beg:end]
 	result := make(Aggregated, len(sortedAliases))
 	for i, alias := range sortedAliases {
 		statuses := rs[alias]
 		up, down, idle, latency := rs.calculateInfo(statuses)
-		result[i] = map[string]any{
-			"alias":       alias,
-			"uptime":      up,
-			"downtime":    down,
-			"idle":        idle,
-			"avg_latency": latency,
-			"statuses":    statuses,
+		result[i] = RouteAggregate{
+			Alias:      alias,
+			Uptime:     up,
+			Downtime:   down,
+			Idle:       idle,
+			AvgLatency: latency,
+			Statuses:   statuses,
 		}
 		r, ok := routes.Get(alias)
 		if ok {
-			result[i]["display_name"] = r.HomepageConfig().Name
+			result[i].DisplayName = r.HomepageConfig().Name
+		} else {
+			result[i].DisplayName = alias
 		}
 	}
 	return result
 }
 
 func (result Aggregated) MarshalJSON() ([]byte, error) {
-	return json.Marshal([]map[string]any(result))
+	return json.Marshal([]RouteAggregate(result))
 }

internal/net/gphttp/gpwebsocket/writer.go

@@ -1,30 +0,0 @@
-package gpwebsocket
-
-import (
-	"context"
-
-	"github.com/gorilla/websocket"
-)
-
-type Writer struct {
-	conn    *websocket.Conn
-	msgType int
-	ctx     context.Context
-}
-
-func NewWriter(ctx context.Context, conn *websocket.Conn, msgType int) *Writer {
-	return &Writer{
-		ctx:     ctx,
-		conn:    conn,
-		msgType: msgType,
-	}
-}
-
-func (w *Writer) Write(p []byte) (int, error) {
-	select {
-	case <-w.ctx.Done():
-		return 0, w.ctx.Err()
-	default:
-		return len(p), w.conn.WriteMessage(w.msgType, p)
-	}
-}