From 4dfd851c462e7b17a2177a79419e7063897d1ff5 Mon Sep 17 00:00:00 2001 From: Tyler Compton Date: Sat, 24 Aug 2019 15:20:34 -0700 Subject: [PATCH] Add docs for common config fields & sessions Now that the common configuration objects and session objects are part of a public API, they need to be documented in a way that can be read with godoc. This commit should lead to easier development with FRP as a library. --- client/service.go | 2 + models/config/client_common.go | 120 ++++++++++++++++++++++++------- models/config/server_common.go | 126 ++++++++++++++++++++++++++------- 3 files changed, 196 insertions(+), 52 deletions(-) diff --git a/client/service.go b/client/service.go index 266ab49..9f86ec7 100644 --- a/client/service.go +++ b/client/service.go @@ -34,6 +34,7 @@ import ( fmux "github.com/hashicorp/yamux" ) +// Service is a client service. type Service struct { // uniq id got from frps, attach it in loginMsg runId string @@ -58,6 +59,7 @@ type Service struct { closedCh chan int } +// NewService creates a new client service with the given configuration. func NewService(cfg config.ClientCommonConf, pxyCfgs map[string]config.ProxyConf, visitorCfgs map[string]config.VisitorConf, cfgFile string) (svr *Service, err error) { svr = &Service{ cfg: cfg, diff --git a/models/config/client_common.go b/models/config/client_common.go index 5d9d127..fe87e08 100644 --- a/models/config/client_common.go +++ b/models/config/client_common.go @@ -23,34 +23,101 @@ import ( ini "github.com/vaughan0/go-ini" ) -// client common config +// ClientCommonConf contains information for a client service. It is +// recommended to use GetDefaultClientConf instead of creating this object +// directly, so that all unspecified fields have reasonable default values. type ClientCommonConf struct { - ServerAddr string `json:"server_addr"` - ServerPort int `json:"server_port"` - HttpProxy string `json:"http_proxy"` - LogFile string `json:"log_file"` - LogWay string `json:"log_way"` - LogLevel string `json:"log_level"` - LogMaxDays int64 `json:"log_max_days"` - DisableLogColor bool `json:"disable_log_color"` - Token string `json:"token"` - AdminAddr string `json:"admin_addr"` - AdminPort int `json:"admin_port"` - AdminUser string `json:"admin_user"` - AdminPwd string `json:"admin_pwd"` - AssetsDir string `json:"assets_dir"` - PoolCount int `json:"pool_count"` - TcpMux bool `json:"tcp_mux"` - User string `json:"user"` - DnsServer string `json:"dns_server"` - LoginFailExit bool `json:"login_fail_exit"` - Start map[string]struct{} `json:"start"` - Protocol string `json:"protocol"` - TLSEnable bool `json:"tls_enable"` - HeartBeatInterval int64 `json:"heartbeat_interval"` - HeartBeatTimeout int64 `json:"heartbeat_timeout"` + // ServerAddr specifies the address of the server to connect to. By + // default, this value is "0.0.0.0". + ServerAddr string `json:"server_addr"` + // ServerPort specifies the port to connect to the server on. By default, + // this value is 7000. + ServerPort int `json:"server_port"` + // HttpProxy specifies a proxy address to connect to the server through. If + // this value is "", the server will be connected to directly. By default, + // this value is read from the "http_proxy" environment variable. + HttpProxy string `json:"http_proxy"` + // LogFile specifies a file where logs will be written to. This value will + // only be used if LogWay is set appropriately. By default, this value is + // "console". + LogFile string `json:"log_file"` + // LogWay specifies the way logging is managed. Valid values are "console" + // or "file". If "console" is used, logs will be printed to stdout. If + // "file" is used, logs will be printed to LogFile. By default, this value + // is "console". + LogWay string `json:"log_way"` + // LogLevel specifies the minimum log level. Valid values are "trace", + // "debug", "info", "warn", and "error". By default, this value is "info". + LogLevel string `json:"log_level"` + // LogMaxDays specifies the maximum number of days to store log information + // before deletion. This is only used if LogWay == "file". By default, this + // value is 0. + LogMaxDays int64 `json:"log_max_days"` + // DisableLogColor disables log colors when LogWay == "console" when set to + // true. By default, this value is false. + DisableLogColor bool `json:"disable_log_color"` + // Token specifies the authorization token used to create keys to be sent + // to the server. The server must have a matching token for authorization + // to succeed. By default, this value is "". + Token string `json:"token"` + // AdminAddr specifies the address that the admin server binds to. By + // default, this value is "127.0.0.1". + AdminAddr string `json:"admin_addr"` + // AdminPort specifies the port for the admin server to listen on. If this + // value is 0, the admin server will not be started. By default, this value + // is 0. + AdminPort int `json:"admin_port"` + // AdminUser specifies the username that the admin server will use for + // login. By default, this value is "admin". + AdminUser string `json:"admin_user"` + // AdminPwd specifies the password that the admin server will use for + // login. By default, this value is "admin". + AdminPwd string `json:"admin_pwd"` + // AssetsDir specifies the local directory that the admin server will load + // resources from. If this value is "", assets will be loaded from the + // bundled executable using statik. By default, this value is "". + AssetsDir string `json:"assets_dir"` + // PoolCount specifies the number of connections the client will make to + // the server in advance. By default, this value is 0. + PoolCount int `json:"pool_count"` + // TcpMux toggles TCP stream multiplexing. This allows multiple requests + // from a client to share a single TCP connection. If this value is true, + // the server must have TCP multiplexing enabled as well. By default, this + // value is true. + TcpMux bool `json:"tcp_mux"` + // User specifies a prefix for proxy names to distinguish them from other + // clients. If this value is not "", proxy names will automatically be + // changed to "{user}.{proxy_name}". By default, this value is "". + User string `json:"user"` + // DnsServer specifies a DNS server address for FRPC to use. If this value + // is "", the default DNS will be used. By default, this value is "". + DnsServer string `json:"dns_server"` + // LoginFailExit controls whether or not the client should exit after a + // failed login attempt. If false, the client will retry until a login + // attempt succeeds. By default, this value is true. + LoginFailExit bool `json:"login_fail_exit"` + // Start specifies a set of enabled proxies by name. If this set is empty, + // all supplied proxies are enabled. By default, this value is an empty + // set. + Start map[string]struct{} `json:"start"` + // Protocol specifies the protocol to use when interacting with the server. + // Valid values are "tcp", "kcp", and "websocket". By default, this value + // is "tcp". + Protocol string `json:"protocol"` + // TLSEnable specifies whether or not TLS should be used when communicating + // with the server. + TLSEnable bool `json:"tls_enable"` + // HeartBeatInterval specifies at what interval heartbeats are sent to the + // server, in seconds. It is not recommended to change this value. By + // default, this value is 30. + HeartBeatInterval int64 `json:"heartbeat_interval"` + // HeartBeatTimeout specifies the maximum allowed heartbeat response delay + // before the connection is terminated, in seconds. It is not recommended + // to change this value. By default, this value is 90. + HeartBeatTimeout int64 `json:"heartbeat_timeout"` } +// GetDefaultClientConf returns a client configuration with default values. func GetDefaultClientConf() ClientCommonConf { return ClientCommonConf{ ServerAddr: "0.0.0.0", @@ -85,8 +152,7 @@ func UnmarshalClientConfFromIni(content string) (cfg ClientCommonConf, err error conf, err := ini.Load(strings.NewReader(content)) if err != nil { - err = fmt.Errorf("parse ini conf file error: %v", err) - return ClientCommonConf{}, err + return ClientCommonConf{}, fmt.Errorf("parse ini conf file error: %v", err) } var ( diff --git a/models/config/server_common.go b/models/config/server_common.go index 8a486fb..a190a61 100644 --- a/models/config/server_common.go +++ b/models/config/server_common.go @@ -24,46 +24,120 @@ import ( "github.com/fatedier/frp/utils/util" ) -// common config +// ServerCommonConf contains information for a server service. It is +// recommended to use GetDefaultServerConf instead of creating this object +// directly, so that all unspecified fields have reasonable default values. type ServerCommonConf struct { - BindAddr string `json:"bind_addr"` - BindPort int `json:"bind_port"` - BindUdpPort int `json:"bind_udp_port"` - KcpBindPort int `json:"kcp_bind_port"` + // BindAddr specifies the address that the server binds to. By default, + // this value is "0.0.0.0". + BindAddr string `json:"bind_addr"` + // BindPort specifies the port that the server listens on. By default, this + // value is 7000. + BindPort int `json:"bind_port"` + // BindUdpPort specifies the UDP port that the server listens on. If this + // value is 0, the server will not listen for UDP connections. By default, + // this value is 0 + BindUdpPort int `json:"bind_udp_port"` + // BindKcpPort specifies the KCP port that the server listens on. If this + // value is 0, the server will not listen for KCP connections. By default, + // this value is 0. + KcpBindPort int `json:"kcp_bind_port"` + // ProxyBindAddr specifies the address that the proxy binds to. This value + // may be the same as BindAddr. By default, this value is "0.0.0.0". ProxyBindAddr string `json:"proxy_bind_addr"` - // If VhostHttpPort equals 0, don't listen a public port for http protocol. + // VhostHttpPort specifies the port that the server listens for HTTP Vhost + // requests. If this value is 0, the server will not listen for HTTP + // requests. By default, this value is 0. VhostHttpPort int `json:"vhost_http_port"` - // if VhostHttpsPort equals 0, don't listen a public port for https protocol + // VhostHttpsPort specifies the port that the server listens for HTTPS + // Vhost requests. If this value is 0, the server will not listen for HTTPS + // requests. By default, this value is 0. VhostHttpsPort int `json:"vhost_https_port"` + // VhostHttpTimeout specifies the response header timeout for the Vhost + // HTTP server, in seconds. By default, this value is 60. VhostHttpTimeout int64 `json:"vhost_http_timeout"` + // DashboardAddr specifies the address that the dashboard binds to. By + // default, this value is "0.0.0.0". DashboardAddr string `json:"dashboard_addr"` - // if DashboardPort equals 0, dashboard is not available - DashboardPort int `json:"dashboard_port"` - DashboardUser string `json:"dashboard_user"` - DashboardPwd string `json:"dashboard_pwd"` - AssetsDir string `json:"asserts_dir"` - LogFile string `json:"log_file"` - LogWay string `json:"log_way"` // console or file - LogLevel string `json:"log_level"` - LogMaxDays int64 `json:"log_max_days"` - DisableLogColor bool `json:"disable_log_color"` - Token string `json:"token"` - SubDomainHost string `json:"subdomain_host"` - TcpMux bool `json:"tcp_mux"` - Custom404Page string `json:"custom_404_page"` + // DashboardPort specifies the port that the dashboard listens on. If this + // value is 0, the dashboard will not be started. By default, this value is + // 0. + DashboardPort int `json:"dashboard_port"` + // DashboardUser specifies the username that the dashboard will use for + // login. By default, this value is "admin". + DashboardUser string `json:"dashboard_user"` + // DashboardUser specifies the password that the dashboard will use for + // login. By default, this value is "admin". + DashboardPwd string `json:"dashboard_pwd"` + // AssetsDir specifies the local directory that the dashboard will load + // resources from. If this value is "", assets will be loaded from the + // bundled executable using statik. By default, this value is "". + AssetsDir string `json:"asserts_dir"` + // LogFile specifies a file where logs will be written to. This value will + // only be used if LogWay is set appropriately. By default, this value is + // "console". + LogFile string `json:"log_file"` + // LogWay specifies the way logging is managed. Valid values are "console" + // or "file". If "console" is used, logs will be printed to stdout. If + // "file" is used, logs will be printed to LogFile. By default, this value + // is "console". + LogWay string `json:"log_way"` + // LogLevel specifies the minimum log level. Valid values are "trace", + // "debug", "info", "warn", and "error". By default, this value is "info". + LogLevel string `json:"log_level"` + // LogMaxDays specifies the maximum number of days to store log information + // before deletion. This is only used if LogWay == "file". By default, this + // value is 0. + LogMaxDays int64 `json:"log_max_days"` + // DisableLogColor disables log colors when LogWay == "console" when set to + // true. By default, this value is false. + DisableLogColor bool `json:"disable_log_color"` + // Token specifies the authorization token used to authenticate keys + // received from clients. Clients must have a matching token to be + // authorized to use the server. By default, this value is "". + Token string `json:"token"` + // SubDomainHost specifies the domain that will be attached to sub-domains + // requested by the client when using Vhost proxying. For example, if this + // value is set to "frps.com" and the client requested the subdomain + // "test", the resulting URL would be "test.frps.com". By default, this + // value is "". + SubDomainHost string `json:"subdomain_host"` + // TcpMux toggles TCP stream multiplexing. This allows multiple requests + // from a client to share a single TCP connection. By default, this value + // is true. + TcpMux bool `json:"tcp_mux"` + // Custom404Page specifies a path to a custom 404 page to display. If this + // value is "", a default page will be displayed. By default, this value is + // "". + Custom404Page string `json:"custom_404_page"` - AllowPorts map[int]struct{} - MaxPoolCount int64 `json:"max_pool_count"` + // AllowPorts specifies a set of ports that clients are able to proxy to. + // If the length of this value is 0, all ports are allowed. By default, + // this value is an empty set. + AllowPorts map[int]struct{} + // MaxPoolCount specifies the maximum pool size for each proxy. By default, + // this value is 5. + MaxPoolCount int64 `json:"max_pool_count"` + // MaxPortsPerClient specifies the maximum number of ports a single client + // may proxy to. If this value is 0, no limit will be applied. By default, + // this value is 0. MaxPortsPerClient int64 `json:"max_ports_per_client"` - HeartBeatTimeout int64 `json:"heart_beat_timeout"` - UserConnTimeout int64 `json:"user_conn_timeout"` + // HeartBeatTimeout specifies the maximum time to wait for a heartbeat + // before terminating the connection. It is not recommended to change this + // value. By default, this value is 90. + HeartBeatTimeout int64 `json:"heart_beat_timeout"` + // UserConnTimeout specifies the maximum time to wait for a work + // connection. By default, this value is 10. + UserConnTimeout int64 `json:"user_conn_timeout"` } +// GetDefaultServerConf returns a server configuration with reasonable +// defaults. func GetDefaultServerConf() ServerCommonConf { return ServerCommonConf{ BindAddr: "0.0.0.0", @@ -96,6 +170,8 @@ func GetDefaultServerConf() ServerCommonConf { } } +// UnmarshalServerConfFromIni parses the contents of a server configuration ini +// file and returns the resulting server configuration. func UnmarshalServerConfFromIni(content string) (cfg ServerCommonConf, err error) { cfg = GetDefaultServerConf()