From 00e4ab76e3c98b6e600cc2bd94201444f43f10a1 Mon Sep 17 00:00:00 2001
From: vicanso <tree.xie@outlook.com>
Date: Fri, 5 Apr 2024 10:58:01 +0800
Subject: [PATCH] docs: update location description

---
 conf/pingap.toml        |  2 +-
 docs/introduction_zh.md | 58 ++++++++++++++++++++---------------------
 docs/location_zh.md     | 52 ++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 30 deletions(-)
 create mode 100644 docs/location_zh.md

diff --git a/conf/pingap.toml b/conf/pingap.toml
index a1b6a6e7..22f855ce 100644
--- a/conf/pingap.toml
+++ b/conf/pingap.toml
@@ -67,7 +67,7 @@ addrs = ["file://~/Downloads"]
 # The upstream for location, it will be the name of one upstream.
 upstream = "charts"
 # How to match the location, it returns true if `host` of http request header
-# equal the config. Default `None` means all match.
+# equal the config, multiple hosts are separated by ",". Default `None` means all match.
 host = ""
 # How to match the location, it returns true if the `url` starts with `path`.
 # Default `None` means all match
diff --git a/docs/introduction_zh.md b/docs/introduction_zh.md
index 9ba730f4..2ef35125 100644
--- a/docs/introduction_zh.md
+++ b/docs/introduction_zh.md
@@ -2,7 +2,7 @@
 description: Pingap 简述
 ---
 
-Pingap是基于[pingora](https://github.com/cloudflare/pingora)开发的，pingora提供了各类模块便于rust开发者使用，但并不方便非rust开发者使用，因此pingap提供了以toml的形式配置简单易用的反向代理，在以下流程中接入调整，实现支持多location代理转发。特性如下：
+Pingap是基于[pingora](https://github.com/cloudflare/pingora)开发的，pingora提供了各类模块便于rust开发者使用，但并不方便非rust开发者使用，因此pingap提供了以toml的形式配置简单易用的反向代理，实现支持多location代理转发。特性如下：
 
 - 可通过请求的路径与域名筛选对应的location
 - 支持静态文件目录处理
@@ -15,37 +15,37 @@ TODO 接入http缓存的逻辑
 
 [Pingap处理流程](./phase_chart_zh.md)
 
-## Location
+## 根据请求的路径选择对应的服务
 
-Location支持配置对应的host与path规则，path支持以下的规则，权重由高至低：
+Pingap支持两种特别的服务类型，以及常规的反向代理服务，具体如下：
 
-- 全等模式，配置以`=`开始，如`=/api`表示匹配path等于`/api`的请求
-- 正则模式，配置以`~`开始，如`~^/(api|rest)`表示匹配path以`/api`或`/rest`开始请求
-- 前缀模式，如`/api`表示匹配path为`/api`开始的请求
+- `Stats`: 获取Server所对应的性能指标
+- `Admin`: 根据启动时指定的admin地址或者配置的`admin path`转发至对应的管理后台服务
+- `其它`: 常规的反向代理服务，根据域名与路径选择对应的转发节点
 
-在server中会根据所添加的所有location列表，计算对应的权重重新排序，location的计算权限逻辑如下：
+```mermaid
+graph TD;
+    start("新的请求")-->ServiceFilter{{请求服务筛选}};
+    ServiceFilter--是否匹配stats-->stats的处理;
+    ServiceFilter--是否匹配admin-->admin的处理;
+    ServiceFilter--根据host与path选择对应的Location-->Location筛选处理;
+```
+
+## Location的处理逻辑
+
+该Server下的所有location在初始化时根据权重按高至低排序，接受到请求时按顺序一个个匹配到符合的location为止，若无符合的则返回出错。根据符合的location重写path(若无则不需要)，添加请求头(若无则不需要)，成功响应时添加响应头(若无则不需要)。
 
 ```rust
-pub fn get_weight(&self) -> u32 {
-    // path starts with
-    // = 65536
-    // prefix(default) 32768
-    // ~ 16384
-    // host exist 8192
-    let mut weighted: u32 = 0;
-    if let Some(path) = &self.path {
-        if path.starts_with('=') {
-            weighted += 65536;
-        } else if path.starts_with('~') {
-            weighted += 16384;
-        } else {
-            weighted += 32768;
-        }
-        weighted += path.len() as u32;
-    };
-    if self.host.is_some() {
-        weighted += 8192;
-    }
-    weighted
-}
+let header = session.req_header_mut();
+let path = header.uri.path();
+let host = header.uri.host().unwrap_or_default();
+
+let (location_index, lo) = self
+    .locations
+    .iter()
+    .enumerate()
+    .find(|(_, item)| item.matched(host, path))
+    .ok_or_else(|| pingora::Error::new_str(LOCATION_NOT_FOUND))?;
 ```
+
+[Location的详细说明](./location_zh.md)
diff --git a/docs/location_zh.md b/docs/location_zh.md
new file mode 100644
index 00000000..40e38766
--- /dev/null
+++ b/docs/location_zh.md
@@ -0,0 +1,52 @@
+---
+description: Location的详细介绍
+---
+
+## Location
+
+Location支持配置对应的多个host与path规则，path支持以下的规则，权重由高至低：
+
+- 全等模式，配置以`=`开始，如`=/api`表示匹配path等于`/api`的请求
+- 正则模式，配置以`~`开始，如`~^/(api|rest)`表示匹配path以`/api`或`/rest`开始请求
+- 前缀模式，如`/api`表示匹配path为`/api`开始的请求
+- 空模式，若未指定path则表示所有的path均匹配，一般建议配置一个`/`的前缀模式即可，无需使用空模式
+
+在server中会根据所添加的所有location列表，计算对应的权重重新排序，也可自定义权重，location的计算权限逻辑如下：
+
+```rust
+pub fn get_weight(&self) -> u16 {
+    if let Some(weight) = self.weight {
+        return weight;
+    }
+    // path starts with
+    // = 1024
+    // prefix(default) 512
+    // ~ 256
+    // host exist 128
+    let mut weight: u16 = 0;
+    if let Some(path) = &self.path {
+        if path.starts_with('=') {
+            weight += 1024;
+        } else if path.starts_with('~') {
+            weight += 256;
+        } else {
+            weight += 512;
+        }
+        weight += path.len().min(64) as u16;
+    };
+    if self.host.is_some() {
+        weight += 128;
+    }
+    weight
+}
+```
+
+一般而言，权重均无需自定义，由规则计算即可。有时可定义一个用于禁用服务的location，其匹配规则为无`host`与`path`限制并指定最高的权重`2048`，在平时并不添加此location，仅在有时需要禁用所有服务时才添加使用。
+
+### 添加请求头与响应头
+
+可按需配置该location对应的请求头与响应头，两个配置的方式均比较简单，需要注意的是，有些`upstream`是需要匹配对应的`Host`的，因此有此要求的则需要在请求头中设置对应的配置`Host:xxx`。
+
+### 重写请求路径
+
+可按需配置请求路径重写规则，支持正则匹配处理，如`^/api/ /`表示将请求前缀的`/api/`替换为`/`，仅支持配置一个重写规则，若逻辑过于复杂建议可配置多个location来分开实现。