refactor: restructure API packages into client/http and server/http with typed proxy/visitor models (#5193)

client/http/controller.go

@@ -0,0 +1,395 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package http
+
+import (
+	"cmp"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"slices"
+	"strconv"
+	"time"
+
+	"github.com/fatedier/frp/client/configmgmt"
+	"github.com/fatedier/frp/client/http/model"
+	"github.com/fatedier/frp/client/proxy"
+	httppkg "github.com/fatedier/frp/pkg/util/http"
+	"github.com/fatedier/frp/pkg/util/jsonx"
+)
+
+// Controller handles HTTP API requests for frpc.
+type Controller struct {
+	serverAddr string
+	manager    configmgmt.ConfigManager
+}
+
+// ControllerParams contains parameters for creating an APIController.
+type ControllerParams struct {
+	ServerAddr string
+	Manager    configmgmt.ConfigManager
+}
+
+func NewController(params ControllerParams) *Controller {
+	return &Controller{
+		serverAddr: params.ServerAddr,
+		manager:    params.Manager,
+	}
+}
+
+func (c *Controller) toHTTPError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	code := http.StatusInternalServerError
+	switch {
+	case errors.Is(err, configmgmt.ErrInvalidArgument):
+		code = http.StatusBadRequest
+	case errors.Is(err, configmgmt.ErrNotFound), errors.Is(err, configmgmt.ErrStoreDisabled):
+		code = http.StatusNotFound
+	case errors.Is(err, configmgmt.ErrConflict):
+		code = http.StatusConflict
+	}
+	return httppkg.NewError(code, err.Error())
+}
+
+// Reload handles GET /api/reload
+func (c *Controller) Reload(ctx *httppkg.Context) (any, error) {
+	strictConfigMode := false
+	strictStr := ctx.Query("strictConfig")
+	if strictStr != "" {
+		strictConfigMode, _ = strconv.ParseBool(strictStr)
+	}
+
+	if err := c.manager.ReloadFromFile(strictConfigMode); err != nil {
+		return nil, c.toHTTPError(err)
+	}
+	return nil, nil
+}
+
+// Stop handles POST /api/stop
+func (c *Controller) Stop(ctx *httppkg.Context) (any, error) {
+	go c.manager.GracefulClose(100 * time.Millisecond)
+	return nil, nil
+}
+
+// Status handles GET /api/status
+func (c *Controller) Status(ctx *httppkg.Context) (any, error) {
+	res := make(model.StatusResp)
+	ps := c.manager.GetProxyStatus()
+	if ps == nil {
+		return res, nil
+	}
+
+	for _, status := range ps {
+		res[status.Type] = append(res[status.Type], c.buildProxyStatusResp(status))
+	}
+
+	for _, arrs := range res {
+		if len(arrs) <= 1 {
+			continue
+		}
+		slices.SortFunc(arrs, func(a, b model.ProxyStatusResp) int {
+			return cmp.Compare(a.Name, b.Name)
+		})
+	}
+	return res, nil
+}
+
+// GetConfig handles GET /api/config
+func (c *Controller) GetConfig(ctx *httppkg.Context) (any, error) {
+	content, err := c.manager.ReadConfigFile()
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+	return content, nil
+}
+
+// PutConfig handles PUT /api/config
+func (c *Controller) PutConfig(ctx *httppkg.Context) (any, error) {
+	body, err := ctx.Body()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("read request body error: %v", err))
+	}
+
+	if len(body) == 0 {
+		return nil, httppkg.NewError(http.StatusBadRequest, "body can't be empty")
+	}
+
+	if err := c.manager.WriteConfigFile(body); err != nil {
+		return nil, c.toHTTPError(err)
+	}
+	return nil, nil
+}
+
+func (c *Controller) buildProxyStatusResp(status *proxy.WorkingStatus) model.ProxyStatusResp {
+	psr := model.ProxyStatusResp{
+		Name:   status.Name,
+		Type:   status.Type,
+		Status: status.Phase,
+		Err:    status.Err,
+	}
+	baseCfg := status.Cfg.GetBaseConfig()
+	if baseCfg.LocalPort != 0 {
+		psr.LocalAddr = net.JoinHostPort(baseCfg.LocalIP, strconv.Itoa(baseCfg.LocalPort))
+	}
+	psr.Plugin = baseCfg.Plugin.Type
+
+	if status.Err == "" {
+		psr.RemoteAddr = status.RemoteAddr
+		if slices.Contains([]string{"tcp", "udp"}, status.Type) {
+			psr.RemoteAddr = c.serverAddr + psr.RemoteAddr
+		}
+	}
+
+	if c.manager.IsStoreProxyEnabled(status.Name) {
+		psr.Source = model.SourceStore
+	}
+	return psr
+}
+
+func (c *Controller) ListStoreProxies(ctx *httppkg.Context) (any, error) {
+	proxies, err := c.manager.ListStoreProxies()
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	resp := model.ProxyListResp{Proxies: make([]model.ProxyDefinition, 0, len(proxies))}
+	for _, p := range proxies {
+		payload, err := model.ProxyDefinitionFromConfigurer(p)
+		if err != nil {
+			return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+		}
+		resp.Proxies = append(resp.Proxies, payload)
+	}
+	slices.SortFunc(resp.Proxies, func(a, b model.ProxyDefinition) int {
+		return cmp.Compare(a.Name, b.Name)
+	})
+	return resp, nil
+}
+
+func (c *Controller) GetStoreProxy(ctx *httppkg.Context) (any, error) {
+	name := ctx.Param("name")
+	if name == "" {
+		return nil, httppkg.NewError(http.StatusBadRequest, "proxy name is required")
+	}
+
+	p, err := c.manager.GetStoreProxy(name)
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	payload, err := model.ProxyDefinitionFromConfigurer(p)
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+	}
+
+	return payload, nil
+}
+
+func (c *Controller) CreateStoreProxy(ctx *httppkg.Context) (any, error) {
+	body, err := ctx.Body()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("read body error: %v", err))
+	}
+
+	var payload model.ProxyDefinition
+	if err := jsonx.Unmarshal(body, &payload); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("parse JSON error: %v", err))
+	}
+
+	if err := payload.Validate("", false); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	cfg, err := payload.ToConfigurer()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	created, err := c.manager.CreateStoreProxy(cfg)
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	resp, err := model.ProxyDefinitionFromConfigurer(created)
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+	}
+	return resp, nil
+}
+
+func (c *Controller) UpdateStoreProxy(ctx *httppkg.Context) (any, error) {
+	name := ctx.Param("name")
+	if name == "" {
+		return nil, httppkg.NewError(http.StatusBadRequest, "proxy name is required")
+	}
+
+	body, err := ctx.Body()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("read body error: %v", err))
+	}
+
+	var payload model.ProxyDefinition
+	if err := jsonx.Unmarshal(body, &payload); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("parse JSON error: %v", err))
+	}
+
+	if err := payload.Validate(name, true); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	cfg, err := payload.ToConfigurer()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	updated, err := c.manager.UpdateStoreProxy(name, cfg)
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	resp, err := model.ProxyDefinitionFromConfigurer(updated)
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+	}
+	return resp, nil
+}
+
+func (c *Controller) DeleteStoreProxy(ctx *httppkg.Context) (any, error) {
+	name := ctx.Param("name")
+	if name == "" {
+		return nil, httppkg.NewError(http.StatusBadRequest, "proxy name is required")
+	}
+
+	if err := c.manager.DeleteStoreProxy(name); err != nil {
+		return nil, c.toHTTPError(err)
+	}
+	return nil, nil
+}
+
+func (c *Controller) ListStoreVisitors(ctx *httppkg.Context) (any, error) {
+	visitors, err := c.manager.ListStoreVisitors()
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	resp := model.VisitorListResp{Visitors: make([]model.VisitorDefinition, 0, len(visitors))}
+	for _, v := range visitors {
+		payload, err := model.VisitorDefinitionFromConfigurer(v)
+		if err != nil {
+			return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+		}
+		resp.Visitors = append(resp.Visitors, payload)
+	}
+	slices.SortFunc(resp.Visitors, func(a, b model.VisitorDefinition) int {
+		return cmp.Compare(a.Name, b.Name)
+	})
+	return resp, nil
+}
+
+func (c *Controller) GetStoreVisitor(ctx *httppkg.Context) (any, error) {
+	name := ctx.Param("name")
+	if name == "" {
+		return nil, httppkg.NewError(http.StatusBadRequest, "visitor name is required")
+	}
+
+	v, err := c.manager.GetStoreVisitor(name)
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	payload, err := model.VisitorDefinitionFromConfigurer(v)
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+	}
+
+	return payload, nil
+}
+
+func (c *Controller) CreateStoreVisitor(ctx *httppkg.Context) (any, error) {
+	body, err := ctx.Body()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("read body error: %v", err))
+	}
+
+	var payload model.VisitorDefinition
+	if err := jsonx.Unmarshal(body, &payload); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("parse JSON error: %v", err))
+	}
+
+	if err := payload.Validate("", false); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	cfg, err := payload.ToConfigurer()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	created, err := c.manager.CreateStoreVisitor(cfg)
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	resp, err := model.VisitorDefinitionFromConfigurer(created)
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+	}
+	return resp, nil
+}
+
+func (c *Controller) UpdateStoreVisitor(ctx *httppkg.Context) (any, error) {
+	name := ctx.Param("name")
+	if name == "" {
+		return nil, httppkg.NewError(http.StatusBadRequest, "visitor name is required")
+	}
+
+	body, err := ctx.Body()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("read body error: %v", err))
+	}
+
+	var payload model.VisitorDefinition
+	if err := jsonx.Unmarshal(body, &payload); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, fmt.Sprintf("parse JSON error: %v", err))
+	}
+
+	if err := payload.Validate(name, true); err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	cfg, err := payload.ToConfigurer()
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusBadRequest, err.Error())
+	}
+	updated, err := c.manager.UpdateStoreVisitor(name, cfg)
+	if err != nil {
+		return nil, c.toHTTPError(err)
+	}
+
+	resp, err := model.VisitorDefinitionFromConfigurer(updated)
+	if err != nil {
+		return nil, httppkg.NewError(http.StatusInternalServerError, err.Error())
+	}
+	return resp, nil
+}
+
+func (c *Controller) DeleteStoreVisitor(ctx *httppkg.Context) (any, error) {
+	name := ctx.Param("name")
+	if name == "" {
+		return nil, httppkg.NewError(http.StatusBadRequest, "visitor name is required")
+	}
+
+	if err := c.manager.DeleteStoreVisitor(name); err != nil {
+		return nil, c.toHTTPError(err)
+	}
+	return nil, nil
+}

client/http/controller_test.go

@@ -0,0 +1,531 @@
+package http
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gorilla/mux"
+
+	"github.com/fatedier/frp/client/configmgmt"
+	"github.com/fatedier/frp/client/http/model"
+	"github.com/fatedier/frp/client/proxy"
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+	httppkg "github.com/fatedier/frp/pkg/util/http"
+)
+
+type fakeConfigManager struct {
+	reloadFromFileFn      func(strict bool) error
+	readConfigFileFn      func() (string, error)
+	writeConfigFileFn     func(content []byte) error
+	getProxyStatusFn      func() []*proxy.WorkingStatus
+	isStoreProxyEnabledFn func(name string) bool
+	storeEnabledFn        func() bool
+
+	listStoreProxiesFn  func() ([]v1.ProxyConfigurer, error)
+	getStoreProxyFn     func(name string) (v1.ProxyConfigurer, error)
+	createStoreProxyFn  func(cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error)
+	updateStoreProxyFn  func(name string, cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error)
+	deleteStoreProxyFn  func(name string) error
+	listStoreVisitorsFn func() ([]v1.VisitorConfigurer, error)
+	getStoreVisitorFn   func(name string) (v1.VisitorConfigurer, error)
+	createStoreVisitFn  func(cfg v1.VisitorConfigurer) (v1.VisitorConfigurer, error)
+	updateStoreVisitFn  func(name string, cfg v1.VisitorConfigurer) (v1.VisitorConfigurer, error)
+	deleteStoreVisitFn  func(name string) error
+	gracefulCloseFn     func(d time.Duration)
+}
+
+func (m *fakeConfigManager) ReloadFromFile(strict bool) error {
+	if m.reloadFromFileFn != nil {
+		return m.reloadFromFileFn(strict)
+	}
+	return nil
+}
+
+func (m *fakeConfigManager) ReadConfigFile() (string, error) {
+	if m.readConfigFileFn != nil {
+		return m.readConfigFileFn()
+	}
+	return "", nil
+}
+
+func (m *fakeConfigManager) WriteConfigFile(content []byte) error {
+	if m.writeConfigFileFn != nil {
+		return m.writeConfigFileFn(content)
+	}
+	return nil
+}
+
+func (m *fakeConfigManager) GetProxyStatus() []*proxy.WorkingStatus {
+	if m.getProxyStatusFn != nil {
+		return m.getProxyStatusFn()
+	}
+	return nil
+}
+
+func (m *fakeConfigManager) IsStoreProxyEnabled(name string) bool {
+	if m.isStoreProxyEnabledFn != nil {
+		return m.isStoreProxyEnabledFn(name)
+	}
+	return false
+}
+
+func (m *fakeConfigManager) StoreEnabled() bool {
+	if m.storeEnabledFn != nil {
+		return m.storeEnabledFn()
+	}
+	return false
+}
+
+func (m *fakeConfigManager) ListStoreProxies() ([]v1.ProxyConfigurer, error) {
+	if m.listStoreProxiesFn != nil {
+		return m.listStoreProxiesFn()
+	}
+	return nil, nil
+}
+
+func (m *fakeConfigManager) GetStoreProxy(name string) (v1.ProxyConfigurer, error) {
+	if m.getStoreProxyFn != nil {
+		return m.getStoreProxyFn(name)
+	}
+	return nil, nil
+}
+
+func (m *fakeConfigManager) CreateStoreProxy(cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error) {
+	if m.createStoreProxyFn != nil {
+		return m.createStoreProxyFn(cfg)
+	}
+	return cfg, nil
+}
+
+func (m *fakeConfigManager) UpdateStoreProxy(name string, cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error) {
+	if m.updateStoreProxyFn != nil {
+		return m.updateStoreProxyFn(name, cfg)
+	}
+	return cfg, nil
+}
+
+func (m *fakeConfigManager) DeleteStoreProxy(name string) error {
+	if m.deleteStoreProxyFn != nil {
+		return m.deleteStoreProxyFn(name)
+	}
+	return nil
+}
+
+func (m *fakeConfigManager) ListStoreVisitors() ([]v1.VisitorConfigurer, error) {
+	if m.listStoreVisitorsFn != nil {
+		return m.listStoreVisitorsFn()
+	}
+	return nil, nil
+}
+
+func (m *fakeConfigManager) GetStoreVisitor(name string) (v1.VisitorConfigurer, error) {
+	if m.getStoreVisitorFn != nil {
+		return m.getStoreVisitorFn(name)
+	}
+	return nil, nil
+}
+
+func (m *fakeConfigManager) CreateStoreVisitor(cfg v1.VisitorConfigurer) (v1.VisitorConfigurer, error) {
+	if m.createStoreVisitFn != nil {
+		return m.createStoreVisitFn(cfg)
+	}
+	return cfg, nil
+}
+
+func (m *fakeConfigManager) UpdateStoreVisitor(name string, cfg v1.VisitorConfigurer) (v1.VisitorConfigurer, error) {
+	if m.updateStoreVisitFn != nil {
+		return m.updateStoreVisitFn(name, cfg)
+	}
+	return cfg, nil
+}
+
+func (m *fakeConfigManager) DeleteStoreVisitor(name string) error {
+	if m.deleteStoreVisitFn != nil {
+		return m.deleteStoreVisitFn(name)
+	}
+	return nil
+}
+
+func (m *fakeConfigManager) GracefulClose(d time.Duration) {
+	if m.gracefulCloseFn != nil {
+		m.gracefulCloseFn(d)
+	}
+}
+
+func newRawTCPProxyConfig(name string) *v1.TCPProxyConfig {
+	return &v1.TCPProxyConfig{
+		ProxyBaseConfig: v1.ProxyBaseConfig{
+			Name: name,
+			Type: "tcp",
+			ProxyBackend: v1.ProxyBackend{
+				LocalPort: 10080,
+			},
+		},
+	}
+}
+
+func TestBuildProxyStatusRespStoreSourceEnabled(t *testing.T) {
+	status := &proxy.WorkingStatus{
+		Name:       "shared-proxy",
+		Type:       "tcp",
+		Phase:      proxy.ProxyPhaseRunning,
+		RemoteAddr: ":8080",
+		Cfg:        newRawTCPProxyConfig("shared-proxy"),
+	}
+
+	controller := &Controller{
+		serverAddr: "127.0.0.1",
+		manager: &fakeConfigManager{
+			isStoreProxyEnabledFn: func(name string) bool {
+				return name == "shared-proxy"
+			},
+		},
+	}
+
+	resp := controller.buildProxyStatusResp(status)
+	if resp.Source != "store" {
+		t.Fatalf("unexpected source: %q", resp.Source)
+	}
+	if resp.RemoteAddr != "127.0.0.1:8080" {
+		t.Fatalf("unexpected remote addr: %q", resp.RemoteAddr)
+	}
+}
+
+func TestReloadErrorMapping(t *testing.T) {
+	tests := []struct {
+		name         string
+		err          error
+		expectedCode int
+	}{
+		{name: "invalid arg", err: fmtError(configmgmt.ErrInvalidArgument, "bad cfg"), expectedCode: http.StatusBadRequest},
+		{name: "apply fail", err: fmtError(configmgmt.ErrApplyConfig, "reload failed"), expectedCode: http.StatusInternalServerError},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			controller := &Controller{
+				manager: &fakeConfigManager{reloadFromFileFn: func(bool) error { return tc.err }},
+			}
+			ctx := httppkg.NewContext(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/api/reload", nil))
+			_, err := controller.Reload(ctx)
+			if err == nil {
+				t.Fatal("expected error")
+			}
+			assertHTTPCode(t, err, tc.expectedCode)
+		})
+	}
+}
+
+func TestStoreProxyErrorMapping(t *testing.T) {
+	tests := []struct {
+		name         string
+		err          error
+		expectedCode int
+	}{
+		{name: "not found", err: fmtError(configmgmt.ErrNotFound, "not found"), expectedCode: http.StatusNotFound},
+		{name: "conflict", err: fmtError(configmgmt.ErrConflict, "exists"), expectedCode: http.StatusConflict},
+		{name: "internal", err: errors.New("persist failed"), expectedCode: http.StatusInternalServerError},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			body := []byte(`{"name":"shared-proxy","type":"tcp","tcp":{"localPort":10080}}`)
+			req := httptest.NewRequest(http.MethodPut, "/api/store/proxies/shared-proxy", bytes.NewReader(body))
+			req = mux.SetURLVars(req, map[string]string{"name": "shared-proxy"})
+			ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+			controller := &Controller{
+				manager: &fakeConfigManager{
+					updateStoreProxyFn: func(_ string, _ v1.ProxyConfigurer) (v1.ProxyConfigurer, error) {
+						return nil, tc.err
+					},
+				},
+			}
+
+			_, err := controller.UpdateStoreProxy(ctx)
+			if err == nil {
+				t.Fatal("expected error")
+			}
+			assertHTTPCode(t, err, tc.expectedCode)
+		})
+	}
+}
+
+func TestStoreVisitorErrorMapping(t *testing.T) {
+	body := []byte(`{"name":"shared-visitor","type":"xtcp","xtcp":{"serverName":"server","bindPort":10081,"secretKey":"secret"}}`)
+	req := httptest.NewRequest(http.MethodDelete, "/api/store/visitors/shared-visitor", bytes.NewReader(body))
+	req = mux.SetURLVars(req, map[string]string{"name": "shared-visitor"})
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			deleteStoreVisitFn: func(string) error {
+				return fmtError(configmgmt.ErrStoreDisabled, "disabled")
+			},
+		},
+	}
+
+	_, err := controller.DeleteStoreVisitor(ctx)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	assertHTTPCode(t, err, http.StatusNotFound)
+}
+
+func TestCreateStoreProxyIgnoresUnknownFields(t *testing.T) {
+	var gotName string
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			createStoreProxyFn: func(cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error) {
+				gotName = cfg.GetBaseConfig().Name
+				return cfg, nil
+			},
+		},
+	}
+
+	body := []byte(`{"name":"raw-proxy","type":"tcp","unexpected":"value","tcp":{"localPort":10080,"unknownInBlock":"value"}}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/store/proxies", bytes.NewReader(body))
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	resp, err := controller.CreateStoreProxy(ctx)
+	if err != nil {
+		t.Fatalf("create store proxy: %v", err)
+	}
+	if gotName != "raw-proxy" {
+		t.Fatalf("unexpected proxy name: %q", gotName)
+	}
+
+	payload, ok := resp.(model.ProxyDefinition)
+	if !ok {
+		t.Fatalf("unexpected response type: %T", resp)
+	}
+	if payload.Type != "tcp" || payload.TCP == nil {
+		t.Fatalf("unexpected payload: %#v", payload)
+	}
+}
+
+func TestCreateStoreVisitorIgnoresUnknownFields(t *testing.T) {
+	var gotName string
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			createStoreVisitFn: func(cfg v1.VisitorConfigurer) (v1.VisitorConfigurer, error) {
+				gotName = cfg.GetBaseConfig().Name
+				return cfg, nil
+			},
+		},
+	}
+
+	body := []byte(`{
+			"name":"raw-visitor","type":"xtcp","unexpected":"value",
+			"xtcp":{"serverName":"server","bindPort":10081,"secretKey":"secret","unknownInBlock":"value"}
+		}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/store/visitors", bytes.NewReader(body))
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	resp, err := controller.CreateStoreVisitor(ctx)
+	if err != nil {
+		t.Fatalf("create store visitor: %v", err)
+	}
+	if gotName != "raw-visitor" {
+		t.Fatalf("unexpected visitor name: %q", gotName)
+	}
+
+	payload, ok := resp.(model.VisitorDefinition)
+	if !ok {
+		t.Fatalf("unexpected response type: %T", resp)
+	}
+	if payload.Type != "xtcp" || payload.XTCP == nil {
+		t.Fatalf("unexpected payload: %#v", payload)
+	}
+}
+
+func TestCreateStoreProxyPluginUnknownFieldsAreIgnored(t *testing.T) {
+	var gotPluginType string
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			createStoreProxyFn: func(cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error) {
+				gotPluginType = cfg.GetBaseConfig().Plugin.Type
+				return cfg, nil
+			},
+		},
+	}
+
+	body := []byte(`{"name":"plugin-proxy","type":"tcp","tcp":{"plugin":{"type":"http2https","localAddr":"127.0.0.1:8080","unknownInPlugin":"value"}}}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/store/proxies", bytes.NewReader(body))
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	resp, err := controller.CreateStoreProxy(ctx)
+	if err != nil {
+		t.Fatalf("create store proxy: %v", err)
+	}
+	if gotPluginType != "http2https" {
+		t.Fatalf("unexpected plugin type: %q", gotPluginType)
+	}
+	payload, ok := resp.(model.ProxyDefinition)
+	if !ok {
+		t.Fatalf("unexpected response type: %T", resp)
+	}
+	if payload.TCP == nil {
+		t.Fatalf("unexpected response payload: %#v", payload)
+	}
+	pluginType := payload.TCP.Plugin.Type
+
+	if pluginType != "http2https" {
+		t.Fatalf("unexpected plugin type in response payload: %q", pluginType)
+	}
+}
+
+func TestCreateStoreVisitorPluginUnknownFieldsAreIgnored(t *testing.T) {
+	var gotPluginType string
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			createStoreVisitFn: func(cfg v1.VisitorConfigurer) (v1.VisitorConfigurer, error) {
+				gotPluginType = cfg.GetBaseConfig().Plugin.Type
+				return cfg, nil
+			},
+		},
+	}
+
+	body := []byte(`{
+			"name":"plugin-visitor","type":"stcp",
+			"stcp":{"serverName":"server","bindPort":10081,"plugin":{"type":"virtual_net","destinationIP":"10.0.0.1","unknownInPlugin":"value"}}
+		}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/store/visitors", bytes.NewReader(body))
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	resp, err := controller.CreateStoreVisitor(ctx)
+	if err != nil {
+		t.Fatalf("create store visitor: %v", err)
+	}
+	if gotPluginType != "virtual_net" {
+		t.Fatalf("unexpected plugin type: %q", gotPluginType)
+	}
+	payload, ok := resp.(model.VisitorDefinition)
+	if !ok {
+		t.Fatalf("unexpected response type: %T", resp)
+	}
+	if payload.STCP == nil {
+		t.Fatalf("unexpected response payload: %#v", payload)
+	}
+	pluginType := payload.STCP.Plugin.Type
+
+	if pluginType != "virtual_net" {
+		t.Fatalf("unexpected plugin type in response payload: %q", pluginType)
+	}
+}
+
+func TestUpdateStoreProxyRejectsMismatchedTypeBlock(t *testing.T) {
+	controller := &Controller{manager: &fakeConfigManager{}}
+	body := []byte(`{"name":"p1","type":"tcp","udp":{"localPort":10080}}`)
+	req := httptest.NewRequest(http.MethodPut, "/api/store/proxies/p1", bytes.NewReader(body))
+	req = mux.SetURLVars(req, map[string]string{"name": "p1"})
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	_, err := controller.UpdateStoreProxy(ctx)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	assertHTTPCode(t, err, http.StatusBadRequest)
+}
+
+func TestUpdateStoreProxyRejectsNameMismatch(t *testing.T) {
+	controller := &Controller{manager: &fakeConfigManager{}}
+	body := []byte(`{"name":"p2","type":"tcp","tcp":{"localPort":10080}}`)
+	req := httptest.NewRequest(http.MethodPut, "/api/store/proxies/p1", bytes.NewReader(body))
+	req = mux.SetURLVars(req, map[string]string{"name": "p1"})
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	_, err := controller.UpdateStoreProxy(ctx)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	assertHTTPCode(t, err, http.StatusBadRequest)
+}
+
+func TestListStoreProxiesReturnsSortedPayload(t *testing.T) {
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			listStoreProxiesFn: func() ([]v1.ProxyConfigurer, error) {
+				b := newRawTCPProxyConfig("b")
+				a := newRawTCPProxyConfig("a")
+				return []v1.ProxyConfigurer{b, a}, nil
+			},
+		},
+	}
+	ctx := httppkg.NewContext(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/api/store/proxies", nil))
+
+	resp, err := controller.ListStoreProxies(ctx)
+	if err != nil {
+		t.Fatalf("list store proxies: %v", err)
+	}
+	out, ok := resp.(model.ProxyListResp)
+	if !ok {
+		t.Fatalf("unexpected response type: %T", resp)
+	}
+	if len(out.Proxies) != 2 {
+		t.Fatalf("unexpected proxy count: %d", len(out.Proxies))
+	}
+	if out.Proxies[0].Name != "a" || out.Proxies[1].Name != "b" {
+		t.Fatalf("proxies are not sorted by name: %#v", out.Proxies)
+	}
+}
+
+func fmtError(sentinel error, msg string) error {
+	return fmt.Errorf("%w: %s", sentinel, msg)
+}
+
+func assertHTTPCode(t *testing.T, err error, expected int) {
+	t.Helper()
+	var httpErr *httppkg.Error
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("unexpected error type: %T", err)
+	}
+	if httpErr.Code != expected {
+		t.Fatalf("unexpected status code: got %d, want %d", httpErr.Code, expected)
+	}
+}
+
+func TestUpdateStoreProxyReturnsTypedPayload(t *testing.T) {
+	controller := &Controller{
+		manager: &fakeConfigManager{
+			updateStoreProxyFn: func(_ string, cfg v1.ProxyConfigurer) (v1.ProxyConfigurer, error) {
+				return cfg, nil
+			},
+		},
+	}
+
+	body := map[string]any{
+		"name": "shared-proxy",
+		"type": "tcp",
+		"tcp": map[string]any{
+			"localPort":  10080,
+			"remotePort": 7000,
+		},
+	}
+	data, err := json.Marshal(body)
+	if err != nil {
+		t.Fatalf("marshal request: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPut, "/api/store/proxies/shared-proxy", bytes.NewReader(data))
+	req = mux.SetURLVars(req, map[string]string{"name": "shared-proxy"})
+	ctx := httppkg.NewContext(httptest.NewRecorder(), req)
+
+	resp, err := controller.UpdateStoreProxy(ctx)
+	if err != nil {
+		t.Fatalf("update store proxy: %v", err)
+	}
+	payload, ok := resp.(model.ProxyDefinition)
+	if !ok {
+		t.Fatalf("unexpected response type: %T", resp)
+	}
+	if payload.TCP == nil || payload.TCP.RemotePort != 7000 {
+		t.Fatalf("unexpected response payload: %#v", payload)
+	}
+}

client/http/model/proxy_definition.go

@@ -0,0 +1,148 @@
+package model
+
+import (
+	"fmt"
+	"strings"
+
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+)
+
+type ProxyDefinition struct {
+	Name string `json:"name"`
+	Type string `json:"type"`
+
+	TCP    *v1.TCPProxyConfig    `json:"tcp,omitempty"`
+	UDP    *v1.UDPProxyConfig    `json:"udp,omitempty"`
+	HTTP   *v1.HTTPProxyConfig   `json:"http,omitempty"`
+	HTTPS  *v1.HTTPSProxyConfig  `json:"https,omitempty"`
+	TCPMux *v1.TCPMuxProxyConfig `json:"tcpmux,omitempty"`
+	STCP   *v1.STCPProxyConfig   `json:"stcp,omitempty"`
+	SUDP   *v1.SUDPProxyConfig   `json:"sudp,omitempty"`
+	XTCP   *v1.XTCPProxyConfig   `json:"xtcp,omitempty"`
+}
+
+func (p *ProxyDefinition) Validate(pathName string, isUpdate bool) error {
+	if strings.TrimSpace(p.Name) == "" {
+		return fmt.Errorf("proxy name is required")
+	}
+	if !IsProxyType(p.Type) {
+		return fmt.Errorf("invalid proxy type: %s", p.Type)
+	}
+	if isUpdate && pathName != "" && pathName != p.Name {
+		return fmt.Errorf("proxy name in URL must match name in body")
+	}
+
+	_, blockType, blockCount := p.activeBlock()
+	if blockCount != 1 {
+		return fmt.Errorf("exactly one proxy type block is required")
+	}
+	if blockType != p.Type {
+		return fmt.Errorf("proxy type block %q does not match type %q", blockType, p.Type)
+	}
+	return nil
+}
+
+func (p *ProxyDefinition) ToConfigurer() (v1.ProxyConfigurer, error) {
+	block, _, _ := p.activeBlock()
+	if block == nil {
+		return nil, fmt.Errorf("exactly one proxy type block is required")
+	}
+
+	cfg := block
+	cfg.GetBaseConfig().Name = p.Name
+	cfg.GetBaseConfig().Type = p.Type
+	return cfg, nil
+}
+
+func ProxyDefinitionFromConfigurer(cfg v1.ProxyConfigurer) (ProxyDefinition, error) {
+	if cfg == nil {
+		return ProxyDefinition{}, fmt.Errorf("proxy config is nil")
+	}
+
+	base := cfg.GetBaseConfig()
+	payload := ProxyDefinition{
+		Name: base.Name,
+		Type: base.Type,
+	}
+
+	switch c := cfg.(type) {
+	case *v1.TCPProxyConfig:
+		payload.TCP = c
+	case *v1.UDPProxyConfig:
+		payload.UDP = c
+	case *v1.HTTPProxyConfig:
+		payload.HTTP = c
+	case *v1.HTTPSProxyConfig:
+		payload.HTTPS = c
+	case *v1.TCPMuxProxyConfig:
+		payload.TCPMux = c
+	case *v1.STCPProxyConfig:
+		payload.STCP = c
+	case *v1.SUDPProxyConfig:
+		payload.SUDP = c
+	case *v1.XTCPProxyConfig:
+		payload.XTCP = c
+	default:
+		return ProxyDefinition{}, fmt.Errorf("unsupported proxy configurer type %T", cfg)
+	}
+
+	return payload, nil
+}
+
+func (p *ProxyDefinition) activeBlock() (v1.ProxyConfigurer, string, int) {
+	count := 0
+	var block v1.ProxyConfigurer
+	var blockType string
+
+	if p.TCP != nil {
+		count++
+		block = p.TCP
+		blockType = "tcp"
+	}
+	if p.UDP != nil {
+		count++
+		block = p.UDP
+		blockType = "udp"
+	}
+	if p.HTTP != nil {
+		count++
+		block = p.HTTP
+		blockType = "http"
+	}
+	if p.HTTPS != nil {
+		count++
+		block = p.HTTPS
+		blockType = "https"
+	}
+	if p.TCPMux != nil {
+		count++
+		block = p.TCPMux
+		blockType = "tcpmux"
+	}
+	if p.STCP != nil {
+		count++
+		block = p.STCP
+		blockType = "stcp"
+	}
+	if p.SUDP != nil {
+		count++
+		block = p.SUDP
+		blockType = "sudp"
+	}
+	if p.XTCP != nil {
+		count++
+		block = p.XTCP
+		blockType = "xtcp"
+	}
+
+	return block, blockType, count
+}
+
+func IsProxyType(typ string) bool {
+	switch typ {
+	case "tcp", "udp", "http", "https", "tcpmux", "stcp", "sudp", "xtcp":
+		return true
+	default:
+		return false
+	}
+}

client/http/model/types.go

@@ -0,0 +1,42 @@
+// Copyright 2025 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package model
+
+const SourceStore = "store"
+
+// StatusResp is the response for GET /api/status
+type StatusResp map[string][]ProxyStatusResp
+
+// ProxyStatusResp contains proxy status information
+type ProxyStatusResp struct {
+	Name       string `json:"name"`
+	Type       string `json:"type"`
+	Status     string `json:"status"`
+	Err        string `json:"err"`
+	LocalAddr  string `json:"local_addr"`
+	Plugin     string `json:"plugin"`
+	RemoteAddr string `json:"remote_addr"`
+	Source     string `json:"source,omitempty"` // "store" or "config"
+}
+
+// ProxyListResp is the response for GET /api/store/proxies
+type ProxyListResp struct {
+	Proxies []ProxyDefinition `json:"proxies"`
+}
+
+// VisitorListResp is the response for GET /api/store/visitors
+type VisitorListResp struct {
+	Visitors []VisitorDefinition `json:"visitors"`
+}

client/http/model/visitor_definition.go

@@ -0,0 +1,107 @@
+package model
+
+import (
+	"fmt"
+	"strings"
+
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+)
+
+type VisitorDefinition struct {
+	Name string `json:"name"`
+	Type string `json:"type"`
+
+	STCP *v1.STCPVisitorConfig `json:"stcp,omitempty"`
+	SUDP *v1.SUDPVisitorConfig `json:"sudp,omitempty"`
+	XTCP *v1.XTCPVisitorConfig `json:"xtcp,omitempty"`
+}
+
+func (p *VisitorDefinition) Validate(pathName string, isUpdate bool) error {
+	if strings.TrimSpace(p.Name) == "" {
+		return fmt.Errorf("visitor name is required")
+	}
+	if !IsVisitorType(p.Type) {
+		return fmt.Errorf("invalid visitor type: %s", p.Type)
+	}
+	if isUpdate && pathName != "" && pathName != p.Name {
+		return fmt.Errorf("visitor name in URL must match name in body")
+	}
+
+	_, blockType, blockCount := p.activeBlock()
+	if blockCount != 1 {
+		return fmt.Errorf("exactly one visitor type block is required")
+	}
+	if blockType != p.Type {
+		return fmt.Errorf("visitor type block %q does not match type %q", blockType, p.Type)
+	}
+	return nil
+}
+
+func (p *VisitorDefinition) ToConfigurer() (v1.VisitorConfigurer, error) {
+	block, _, _ := p.activeBlock()
+	if block == nil {
+		return nil, fmt.Errorf("exactly one visitor type block is required")
+	}
+
+	cfg := block
+	cfg.GetBaseConfig().Name = p.Name
+	cfg.GetBaseConfig().Type = p.Type
+	return cfg, nil
+}
+
+func VisitorDefinitionFromConfigurer(cfg v1.VisitorConfigurer) (VisitorDefinition, error) {
+	if cfg == nil {
+		return VisitorDefinition{}, fmt.Errorf("visitor config is nil")
+	}
+
+	base := cfg.GetBaseConfig()
+	payload := VisitorDefinition{
+		Name: base.Name,
+		Type: base.Type,
+	}
+
+	switch c := cfg.(type) {
+	case *v1.STCPVisitorConfig:
+		payload.STCP = c
+	case *v1.SUDPVisitorConfig:
+		payload.SUDP = c
+	case *v1.XTCPVisitorConfig:
+		payload.XTCP = c
+	default:
+		return VisitorDefinition{}, fmt.Errorf("unsupported visitor configurer type %T", cfg)
+	}
+
+	return payload, nil
+}
+
+func (p *VisitorDefinition) activeBlock() (v1.VisitorConfigurer, string, int) {
+	count := 0
+	var block v1.VisitorConfigurer
+	var blockType string
+
+	if p.STCP != nil {
+		count++
+		block = p.STCP
+		blockType = "stcp"
+	}
+	if p.SUDP != nil {
+		count++
+		block = p.SUDP
+		blockType = "sudp"
+	}
+	if p.XTCP != nil {
+		count++
+		block = p.XTCP
+		blockType = "xtcp"
+	}
+	return block, blockType, count
+}
+
+func IsVisitorType(typ string) bool {
+	switch typ {
+	case "stcp", "sudp", "xtcp":
+		return true
+	default:
+		return false
+	}
+}