From 10acf638f81bdddaf1f4dd28d246429d488f721d Mon Sep 17 00:00:00 2001
From: Guy Lewin <guy.lewin@microsoft.com>
Date: Sat, 14 Mar 2020 11:26:35 -0400
Subject: [PATCH] [Feature] Include RunId in FRP Server Plugin NewProxy message
 (#1700)

* feat: include RunId in FRP Server Plugin NewProxy message

* doc: rewrite server plugin documentation
---
 doc/server_plugin.md          | 57 +++++++++++++++++++++--------------
 models/plugin/server/types.go |  1 +
 server/control.go             |  1 +
 3 files changed, 37 insertions(+), 22 deletions(-)

diff --git a/doc/server_plugin.md b/doc/server_plugin.md
index 7d9be12..fa511b3 100644
--- a/doc/server_plugin.md
+++ b/doc/server_plugin.md
@@ -1,24 +1,25 @@
-### Manage Plugin
+### Server Plugin
 
-frp manage plugin is aim to extend frp's ability without modifing self code.
+frp server plugin is aimed to extend frp's ability without modifying the Golang code.
 
-It runs as a process and listen on a port to provide RPC interface. Before frps doing some operations, frps will send RPC requests to manage plugin and do operations by it's response.
+An external server should run in a different process receiving RPC calls from frps.
+Before frps is doing some operations, it will send RPC requests to notify the external RPC server and act according to its response.
 
 ### RPC request
 
-Support HTTP first.
+RPC requests are based on JSON over HTTP.
 
-When manage plugin accept the operation request, it can give three different responses.
+When a server plugin accepts an operation request, it can respond with three different responses:
 
-* Reject operation and return the reason.
+* Reject operation and return a reason.
 * Allow operation and keep original content.
 * Allow operation and return modified content.
 
 ### Interface
 
-HTTP path can be configured for each manage plugin in frps. Assume here is `/handler`.
+HTTP path can be configured for each manage plugin in frps. We'll assume for this example that it's `/handler`.
 
-Request
+A request to the RPC server will look like:
 
 ```
 POST /handler
@@ -30,15 +31,15 @@ POST /handler
     }
 }
 
-Request Header
+Request Header:
 X-Frp-Reqid: for tracing
 ```
 
-Response
+The response can look like any of the following:
 
-Error if not return 200 http code.
+* Non-200 HTTP response status code (this will automatically tell frps that the request should fail)
 
-Reject opeartion
+* Reject operation:
 
 ```
 {
@@ -47,7 +48,7 @@ Reject opeartion
 }
 ```
 
-Allow operation and keep original content
+* Allow operation and keep original content:
 
 ```
 {
@@ -56,7 +57,7 @@ Allow operation and keep original content
 }
 ```
 
-Allow opeartion and modify content
+* Allow operation and modify content
 
 ```
 {
@@ -69,7 +70,7 @@ Allow opeartion and modify content
 
 ### Operation
 
-Now it supports `Login` and `NewProxy`.
+Currently `Login` and `NewProxy` operations are supported.
 
 #### Login
 
@@ -102,6 +103,7 @@ Create new proxy
         "user": {
             "user": <string>,
             "metas": map<string>string
+            "run_id": <string>
         },
         "proxy_name": <string>,
         "proxy_type": <string>,
@@ -122,14 +124,21 @@ Create new proxy
         "host_header_rewrite": <string>,
         "headers": map<string>string,
 
+        // stcp only
+        "sk": <string>,
+
+        // tcpmux only
+        "multiplexer": <string>
+
         "metas": map<string>string
     }
 }
 ```
 
-### manage plugin configure
+### Server Plugin Configuration
 
 ```ini
+# frps.ini
 [common]
 bind_port = 7000
 
@@ -144,15 +153,19 @@ path = /handler
 ops = NewProxy
 ```
 
-addr: plugin listen on.
-path: http request url path.
-ops: opeartions plugin needs handle.
+addr: the address where the external RPC service listens on.
+path: http request url path for the POST request.
+ops: operations plugin needs to handle (e.g. "Login", "NewProxy").
+
+### Metadata
 
-### meta data
+Metadata will be sent to the server plugin in each RPC request.
 
-Meta data will be sent to manage plugin in each RCP request.
+There are 2 types of metadata entries - 1 under `[common]` and the other under each proxy configuration.
+Metadata entries under `[common]` will be sent in `Login` under the key `metas`, and in any other RPC request under `user.metas`.
+Metadata entries under each proxy configuration will be sent in `NewProxy` op only, under `metas`.
 
-Meta data start with `meta_`. It can be configured in `common` and each proxy.
+Metadata entries start with `meta_`. This is an example of metadata entries in `[common]` and under the proxy named `[ssh]`:
 
 ```
 # frpc.ini
diff --git a/models/plugin/server/types.go b/models/plugin/server/types.go
index 4e392b7..5d9c695 100644
--- a/models/plugin/server/types.go
+++ b/models/plugin/server/types.go
@@ -38,6 +38,7 @@ type LoginContent struct {
 type UserInfo struct {
 	User  string            `json:"user"`
 	Metas map[string]string `json:"metas"`
+	RunId string            `json:"run_id"`
 }
 
 type NewProxyContent struct {
diff --git a/server/control.go b/server/control.go
index f4ed481..e832ea9 100644
--- a/server/control.go
+++ b/server/control.go
@@ -422,6 +422,7 @@ func (ctl *Control) manager() {
 					User: plugin.UserInfo{
 						User:  ctl.loginMsg.User,
 						Metas: ctl.loginMsg.Metas,
+						RunId: ctl.loginMsg.RunId,
 					},
 					NewProxy: *m,
 				}