Add dashboard support for API service

Author: nekohasekai

docs/configuration/rule-set/index.md

@@ -119,7 +119,16 @@ HTTP Client for downloading rule-set.
 
 See [HTTP Client Fields](/configuration/shared/http-client/) for details.
 
-Default transport will be used if empty.
+When empty, the default HTTP client is used: the one named by
+[`default_http_client`](/configuration/route/#default_http_client), or the first top-level
+`http_clients` entry when `default_http_client` is empty.
+
+!!! failure "Implicit default deprecated in sing-box 1.14.0"
+
+    When neither `http_clients` nor `default_http_client` is configured, an implicit HTTP
+    client connecting through the default outbound is used. This implicit default is
+    deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0; define
+    `http_clients` instead.
 
 #### update_interval
 

docs/configuration/rule-set/index.zh.md

@@ -119,7 +119,13 @@
 
 参阅 [HTTP 客户端字段](/zh/configuration/shared/http-client/) 了解详情。
 
-如果为空，将使用默认传输。
+留空时使用默认 HTTP 客户端：即由 [`default_http_client`](/zh/configuration/route/#default_http_client)
+指定的客户端，或当 `default_http_client` 为空时使用顶级 `http_clients` 的第一项。
+
+!!! failure "隐式默认已在 sing-box 1.14.0 废弃"
+
+    当 `http_clients` 与 `default_http_client` 均未配置时，将使用通过默认出站连接的隐式 HTTP 客户端。
+    该隐式默认已在 sing-box 1.14.0 废弃，并将在 sing-box 1.16.0 移除；请改为定义 `http_clients`。
 
 #### update_interval
 

docs/configuration/service/api.md

@@ -23,6 +23,13 @@ for bidirectional streaming methods.
   "secret": "",
   "access_control_allow_origin": [],
   "access_control_allow_private_network": false,
+  "dashboard": {
+    "enabled": true,
+    "path": "",
+    "download_url": "",
+    "http_client": "", // or {}
+    "update_interval": ""
+  },
   "tls": {}
 }
 ```
@@ -49,6 +56,59 @@ CORS allowed origins, `*` will be used if empty.
 
 Allow access from private network.
 
+#### dashboard
+
+Web dashboard downloaded and served over the API listener at `/dashboard/`; other browser
+requests are redirected to it.
+
+!!! info ""
+
+    The object can be replaced with a boolean value (equivalent to `{ "enabled": <bool> }`),
+    or with a string path (equivalent to `{ "enabled": true, "path": "<string>" }`).
+
+##### enabled
+
+Enable the dashboard.
+
+##### path
+
+Directory the dashboard files are stored in.
+
+`dashboard` in the working directory will be used by default.
+
+If the directory is empty, the dashboard is downloaded and an `.etag` file is stored inside
+it to skip unchanged updates. A non-empty directory without an `.etag` file is served as-is
+and never updated automatically.
+
+##### download_url
+
+Download URL of the dashboard archive (zip).
+
+`https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip` will be used by default.
+
+##### http_client
+
+HTTP client used to download the dashboard, with the same behavior as remote rule-sets.
+
+See [HTTP Client Fields](/configuration/shared/http-client/) for details.
+
+When empty, the default HTTP client is used: the one named by
+[`default_http_client`](/configuration/route/#default_http_client), or the first top-level
+`http_clients` entry when `default_http_client` is empty.
+
+!!! failure "Implicit default deprecated in sing-box 1.14.0"
+
+    When neither `http_clients` nor `default_http_client` is configured, an implicit HTTP
+    client connecting through the default outbound is used. This implicit default is
+    deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0; define
+    `http_clients` instead.
+
+##### update_interval
+
+Update interval of the dashboard.
+
+`1d` will be used by default.
+
 #### tls
 
 TLS configuration, see [TLS](/configuration/shared/tls/#inbound).

docs/configuration/service/api.zh.md

@@ -22,6 +22,13 @@ sing-box API 服务是用于观察与控制正在运行的 sing-box 实例的 gR
   "secret": "",
   "access_control_allow_origin": [],
   "access_control_allow_private_network": false,
+  "dashboard": {
+    "enabled": true,
+    "path": "",
+    "download_url": "",
+    "http_client": "", // 或 {}
+    "update_interval": ""
+  },
   "tls": {}
 }
 ```
@@ -38,7 +45,7 @@ API 密钥。
 
 客户端通过标准的 `authorization: Bearer <secret>` gRPC metadata 头认证。
 
-留空则禁用认证。
+默认无需认证。
 
 #### access_control_allow_origin
 
@@ -48,6 +55,54 @@ API 密钥。
 
 允许从私有网络访问。
 
+#### dashboard
+
+下载并通过 API 监听器在 `/dashboard/` 提供的 Web 仪表板；其他浏览器请求将被重定向到该路径。
+
+!!! info ""
+
+    该对象可以替换为布尔值（等同于 `{ "enabled": <bool> }`），
+    或字符串路径（等同于 `{ "enabled": true, "path": "<string>" }`）。
+
+##### enabled
+
+启用仪表板。
+
+##### path
+
+存放仪表板文件的目录。
+
+默认使用工作目录下的 `dashboard`。
+
+如果目录为空，将下载仪表板，并在其中存放 `.etag` 文件以跳过未变更的更新。
+非空且不含 `.etag` 文件的目录将按原样提供，且不会自动更新。
+
+##### download_url
+
+仪表板压缩包（zip）的下载 URL。
+
+默认使用 `https://github.com/SagerNet/sing-box-dashboard/archive/refs/heads/gh-pages.zip`。
+
+##### http_client
+
+用于下载仪表板的 HTTP 客户端，行为与远程规则集相同。
+
+参阅 [HTTP 客户端字段](/zh/configuration/shared/http-client/)。
+
+留空时使用默认 HTTP 客户端：即由 [`default_http_client`](/zh/configuration/route/#default_http_client)
+指定的客户端，或当 `default_http_client` 为空时使用顶级 `http_clients` 的第一项。
+
+!!! failure "隐式默认已在 sing-box 1.14.0 废弃"
+
+    当 `http_clients` 与 `default_http_client` 均未配置时，将使用通过默认出站连接的隐式 HTTP 客户端。
+    该隐式默认已在 sing-box 1.14.0 废弃，并将在 sing-box 1.16.0 移除；请改为定义 `http_clients`。
+
+##### update_interval
+
+仪表板的更新间隔。
+
+默认使用 `1d`。
+
 #### tls
 
 TLS 配置,参阅 [TLS](/zh/configuration/shared/tls/#inbound)。

option/api.go

@@ -1,11 +1,50 @@
 package option
 
-import "github.com/sagernet/sing/common/json/badoption"
+import (
+	"github.com/sagernet/sing/common/json"
+	"github.com/sagernet/sing/common/json/badoption"
+)
 
 type APIServiceOptions struct {
 	ListenOptions
 	Secret                           string                     `json:"secret,omitempty"`
 	AccessControlAllowOrigin         badoption.Listable[string] `json:"access_control_allow_origin,omitempty"`
 	AccessControlAllowPrivateNetwork bool                       `json:"access_control_allow_private_network,omitempty"`
+	Dashboard                        *APIDashboardOptions       `json:"dashboard,omitempty"`
 	InboundTLSOptionsContainer
 }
+
+type _APIDashboardOptions struct {
+	Enabled        bool               `json:"enabled,omitempty"`
+	Path           string             `json:"path,omitempty"`
+	DownloadURL    string             `json:"download_url,omitempty"`
+	HTTPClient     *HTTPClientOptions `json:"http_client,omitempty"`
+	UpdateInterval badoption.Duration `json:"update_interval,omitempty"`
+}
+
+type APIDashboardOptions _APIDashboardOptions
+
+func (o APIDashboardOptions) MarshalJSON() ([]byte, error) {
+	if o.DownloadURL == "" && o.HTTPClient == nil && o.UpdateInterval == 0 {
+		if o.Path == "" {
+			return json.Marshal(o.Enabled)
+		}
+		if o.Enabled {
+			return json.Marshal(o.Path)
+		}
+	}
+	return json.Marshal(_APIDashboardOptions(o))
+}
+
+func (o *APIDashboardOptions) UnmarshalJSON(bytes []byte) error {
+	err := json.Unmarshal(bytes, &o.Enabled)
+	if err == nil {
+		return nil
+	}
+	err = json.Unmarshal(bytes, &o.Path)
+	if err == nil {
+		o.Enabled = true
+		return nil
+	}
+	return json.UnmarshalDisallowUnknownFields(bytes, (*_APIDashboardOptions)(o))
+}