📃 docs: update doc

cmd/merge.go

@@ -24,7 +24,7 @@ import (
 var mergeCmd = &cobra.Command{
 	Use:   "merge [files...]",
 	Short: "Merge multiple coherent Go coverage files into a single file.",
-	Long: `merge will merge multiple Go coverage files into a single coverage file.
+	Long: `Merge will merge multiple Go coverage files into a single coverage file.
 merge requires that the files are 'coherent', meaning that if they both contain references to the
 same paths, then the contents of those source files were identical for the binary that generated
 each file.

cmd/profile.go

@@ -23,12 +23,6 @@ var profileCmd = &cobra.Command{
 	Use:   "profile",
 	Short: "Get coverage profile from service registry center",
 	Long:  `Get code coverage profile for the services under test at runtime.`,
-	Example: `
-# Get coverage counter from default register center http://127.0.0.1:7777, the result output to stdout.
-goc profile
-# Get coverage counter from specified register center, the result output to specified file.
-goc profile --host=http://192.168.1.1:8080 --output=./coverage.cov
-`,
 	//Run: profile,
 }
 

cmd/server.go

@@ -22,8 +22,7 @@ import (
 
 var serverCmd = &cobra.Command{
 	Use:     "server",
-	Short:   "start a service registry center",
-	Long:    "start a service registry center",
+	Short:   "Start a service registry center",
 	Example: "",
 
 	Run: serve,

cmd/service.go

@@ -16,12 +16,15 @@ package cmd
 import (
 	"github.com/qiniu/goc/v2/pkg/client"
 	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 )
 
 var listCmd = &cobra.Command{
 	Use:   "service",
-	Short: "Lists all the registered services",
-	Long:  "Lists all the registered services",
+	Short: "Deal with the registered services",
+	Long: `It can be used to list, remove the registered services. 
+For disconnected services, remove will delete these serivces forever, 
+for connected services remove will force these services register again.`,
 }
 
 var (
@@ -31,9 +34,15 @@ var (
 )
 
 func init() {
-	listCmd.PersistentFlags().StringVar(&listHost, "host", "127.0.0.1:7777", "specify the host of the goc server")
-	listCmd.PersistentFlags().BoolVar(&listWide, "wide", false, "list all services with more information (such as pid)")
-	listCmd.PersistentFlags().StringSliceVar(&listIds, "id", nil, "specify the ids of the services")
+
+	add1Flags := func(f *pflag.FlagSet) {
+		f.StringVar(&listHost, "host", "127.0.0.1:7777", "specify the host of the goc server")
+		f.BoolVar(&listWide, "wide", false, "list all services with more information (such as pid)")
+		f.StringSliceVar(&listIds, "id", nil, "specify the ids of the services")
+	}
+
+	add1Flags(getServiceCmd.Flags())
+	add1Flags(deleteServiceCmd.Flags())
 
 	listCmd.AddCommand(getServiceCmd)
 	listCmd.AddCommand(deleteServiceCmd)

doc/protocol.md

@@ -49,10 +49,10 @@ websocket + jsonrpc2 有流式调用，消息边界。非常适合
 
 ### 注册
 
-注册信息放入 websocket url 中，例如：
+agent 首先通过以下 url 完成注册：
 
 ```
-/v2/internal/ws/rpcstream?cmdline=.%2Fcmd&hostname=nuc&pid=1699804
+GET /internal/register?cmdline=.%2Fcmd&hostname=nuc&pid=1699804
 ```
 
 注册信息为：
@@ -61,7 +61,22 @@ websocket + jsonrpc2 有流式调用，消息边界。非常适合
 2. hostname
 3. 进程 PID
 
-goc server 再加上 remote ip 对四个元信息生成一个唯一 hash id，作为该 agent 的 ID。
+goc server 会生成一个自增 id (全局唯一) 和 token (全局唯一) 返回给 agent。
+
+### websocket 连接
+
+agent 通过以下 url 发起 websocket 连接：
+
+```
+/internal/ws/rpcstream?id=[id]&token=[token]
+/internal/ws/watchstream?id=[id]&token=[token]
+```
+
+分别代表 rpc 通道和 watch 通道。
+
+服务端会校验 id 和 token 是否存在及是否匹配。不匹配返回错误。
+
+agent 收到错误会重新注册。
 
 ### 获取覆盖率
 
@@ -85,4 +100,5 @@ ProfileReq: resetprofile
 
 ### 异常处理
 
-goc server 端遇到 err 就关闭对应 agent 的 websocket 连接。
+1. goc server 端遇到 err 就关闭对应 agent 的 websocket 连接。
+2. goc server 会将 id 和 token 持久化，重启后，agent 再次上报时可直接校验，若成功保持 id 不变。