doc: sync Goroutine-Local-Storage 功能使用 (cloudwego#862)

Co-authored-by: Yi Duan <[email protected]>

Author: alice-yyds

content/en/docs/kitex/Tutorials/advanced-feature/GLS.md

@@ -0,0 +1,54 @@
+---
+title: "GLS Feature Usage"
+date: 2023-11-29
+weight: 11
+keywords: ["GLS","context"]
+description: "Goroutine local storage for implicitly pass context"
+---
+
+## Server side enable request context backup
+
+- Option on
+  - Use the server option `WithContextBackup`;
+  - The first parameter `enable` indicates that the GLS is enabled;
+  - The second option, `async`, means to enable asynchronous implicitly pass-through (indicating that the context in the asynchronous call to go func () is also transparent fallback)
+
+```go
+svr := xxx.NewServer(new(XXXImpl), server.WithContextBackup(true, true))
+
+```
+
+- Adjust localsession [management options](https://github.com/cloudwego/localsession/blob/main/manager.go#L24) by environment variables
+  - First, enable `WithContextBackup` on the Server side.
+  - Configure `CLOUDWEGO_SESSION_CONFIG_KEY ``= [{Whether to enable asynchronous pass-through}] [, {Global sharding number}] [, {GC interval}] in environment variables `, all three options are optional, **null means use default value**
+    - Ex: `true,10,1h ` means, turn on asynchronous + sharding 10 buckets + 1 hour GC interval
+
+## Client start request context fallback
+
+- Option on
+  - Use the client option `WithContextBackup`;
+  - The parameter handler represents the backup logic BackupHandler customized by the business.
+
+```go
+func(prev, cur context.Context) (ctx context.Context, backup bool)
+
+```
+
+- `Prev` parameter represents the context of the backup
+- `Cur` parameter represents the context obtained by the current client
+- `Ctx` return value represents the final context where the user completes processing
+- `Backup` return value indicates whether to continue localsession [built-in fallback backup ](https://github.com/cloudwego/localsession/blob/main/backup/metainfo.go#L54),  mainly metainfo Persistent KVS pass-through at present
+
+```go
+var expectedKey interface{}
+cli := xxx.NewClient(serverName, client.WithContextBackup(func(prev, cur context.Context) (ctx context.Context, backup bool) {
+    if v := cur.Value(expectedKey); v != nil {
+    // expectedKey exists, no need for recover context
+        return cur, false
+    }
+    // expectedKey doesn't exists, need recover context from prev
+    ctx = context.WithValue(cur, expectedKey, prev.Value(expectedKey))
+    return ctx, true
+})
+
+```

content/zh/docs/kitex/Tutorials/advanced-feature/GLS.md

@@ -0,0 +1,63 @@
+---
+title: "Goroutine-Local-Storage 功能使用"
+date: 2023-11-29
+weight: 11
+keywords: ["GLS","上下文"]
+description: "协程上下文隐式传递"
+---
+
+## Introduction
+
+GLS 用于存储 goroutine 内的上下文信息，作用类似于 context。相比 context 有如下优势：
+
+1. **不需要显式传递**，在任意函数位置都可调用 CurSession() 获取上下文（如果有）
+2. **可以在父子****协程****间传递**（需要开启选项）
+
+框架目前主要使用 GLS 进行 context 备份，以避免用户误传 context 导致链路透传信息（如 logid、metainfo 等）丢失
+
+## Server 端开启请求 context 备份
+
+- 选项开启
+  - 使用 server option WithContextBackup；
+  - 第一个参数 enable 表示开启备份功能；
+  - 第二个选项 async 表示开启异步隐式透传（表示对 go func() 异步调用中的 context 也进行透明兜底）
+
+```go
+svr := xxx.NewServer(new(XXXImpl), server.WithContextBackup(true, true))
+
+```
+
+- 环境变量调整 localsession [管理选项](https://github.com/cloudwego/localsession/blob/main/manager.go#L24)
+  1. 首先在【Server 端开启 WithContextBackup】
+  2. 环境变量中配置 `CLOUDWEGO_SESSION_CONFIG_KEY``=[{是否开启异步透传}][,{全局分片数}][,{GC间隔}]`，三个选项都为可选，**空表示使用默认值**
+     1. ex: `true,10,1h ` 表示 开启异步 + 分片 10+1 小时 GC 间隔
+
+## Client 端开启请求 context 兜底
+
+- 选项开启
+  - 使用 client option `client.``WithContextBackup``(handler)`；
+  - 参数 handler 表示业务自定义的备份逻辑 BackupHandler，其签名为
+
+```go
+func(prev, cur context.Context) (ctx context.Context, backup bool)
+
+```
+
+- prev 参数表示备份的 context
+- cur 参数表示当前 client 拿到的 context
+- ctx 返回值表示用户处理完成的最终 context
+- backup 返回值表示是否继续进行 localsession[ 内置的兜底备份](https://github.com/cloudwego/localsession/blob/main/backup/metainfo.go#L54)，当前主要是 metainfo Persistent KVS 的透传
+
+```go
+var expectedKey interface{}
+cli := client.New(serverName, client.WithContextBackup(func(prev, cur context.Context) (ctx context.Context, backup bool) {
+    if v := cur.Value(expectedKey); v != nil {
+    // expectedKey exists, no need for recover context
+        return cur, false
+    }
+    // expectedKey doesn't exists, need recover context from prev
+    ctx = context.WithValue(cur, expectedKey, prev.Value(expectedKey))
+    return ctx, true
+})
+
+```