add comments

Author: umputun

client.go

@@ -10,16 +10,20 @@ import (
 )
 
 // Client implements remote engine and delegates all calls to remote http server
+// if AuthUser and AuthPasswd defined will be used for basic auth in each call to server
 type Client struct {
-	API        string // URL to jrpc server with entrypoint, i.e. http://127.0.0.1:8080/command
-	Client     http.Client
-	AuthUser   string
-	AuthPasswd string
+	API        string      // URL to jrpc server with entrypoint, i.e. http://127.0.0.1:8080/command
+	Client     http.Client // http client injected by user
+	AuthUser   string      // basic auth user name, should match Server.AuthUser, optional
+	AuthPasswd string      // basic auth password, should match Server.AuthPasswd, optional
 
-	id uint64 // used with atomic
+	id uint64 // used with atomic to populate unique id to Request.ID
 }
 
-// Call remote server with given method and arguments
+// Call remote server with given method and arguments.
+// Empty args will be ignored, single arg will be marshaled as-us and multiple args marshalled as []interface{}.
+// Returns Response and error. Note: Response has it's own Error field, but that onw controlled by server.
+// Returned error represent client-level errors, like failed http call, failed marshaling and so on.
 func (r *Client) Call(method string, args ...interface{}) (*Response, error) {
 
 	var b []byte

jrpc.go

@@ -10,16 +10,16 @@ import (
 
 // Request encloses method name and all params
 type Request struct {
-	Method string      `json:"method"`
-	Params interface{} `json:"params,omitempty"`
-	ID     uint64      `json:"id"`
+	Method string      `json:"method"`           // method (function) name
+	Params interface{} `json:"params,omitempty"` // function arguments
+	ID     uint64      `json:"id"`               // unique call id
 }
 
 // Response encloses result and error received from remote server
 type Response struct {
-	Result *json.RawMessage `json:"result,omitempty"`
-	Error  string           `json:"error,omitempty"`
-	ID     uint64           `json:"id"`
+	Result *json.RawMessage `json:"result,omitempty"` // response json
+	Error  string           `json:"error,omitempty"`  // optional remote (server side / plugin side) error
+	ID     uint64           `json:"id"`               // unique call id, echoed Request.ID to allow calls tracing
 }
 
 // EncodeResponse convert anything (type interface{}) and incoming error (if any) to Response

server.go

@@ -20,13 +20,14 @@ import (
 
 // Server is json-rpc server with an optional basic auth
 type Server struct {
-	API        string
-	AuthUser   string
-	AuthPasswd string
-	Version    string
-	AppName    string
-	Logger     L
-	funcs      struct {
+	API        string // url path, i.e. "/command" or "/rpc" etc.
+	AuthUser   string // basic auth user name, should match Client.AuthUser, optional
+	AuthPasswd string // basic auth password, should match Client.AuthPasswd, optional
+	Version    string // server version, injected from main and used for informational headers only
+	AppName    string // plugin name, injected from main and used for informational headers only
+	Logger     L      // logger, if nil will default to NoOpLogger
+
+	funcs struct {
 		m    map[string]ServerFn
 		once sync.Once
 	}
@@ -37,11 +38,8 @@ type Server struct {
 	}
 }
 
-// Encoder is a function to encode call's result to Response
-type Encoder func(id uint64, resp interface{}, e error) (Response, error)
-
-// ServerFn handler registered for each method with Add
-// Implementations provided by consumer and define response logic.
+// ServerFn handler registered for each method with Add or Group.
+// Implementations provided by consumer and defines response logic.
 type ServerFn func(id uint64, params json.RawMessage) Response
 
 // Run http server on given port
@@ -92,7 +90,7 @@ func (s *Server) Shutdown() error {
 	return s.httpServer.Shutdown(ctx)
 }
 
-// Add method handler
+// Add method handler. Handler will be called on matching method (Request.Method)
 func (s *Server) Add(method string, fn ServerFn) {
 	s.httpServer.Lock()
 	defer s.httpServer.Unlock()
@@ -112,13 +110,14 @@ func (s *Server) Add(method string, fn ServerFn) {
 // HandlersGroup alias for map of handlers
 type HandlersGroup map[string]ServerFn
 
-// Group of handlers with common prefix
+// Group of handlers with common prefix, match on group.method
 func (s *Server) Group(prefix string, m HandlersGroup) {
 	for k, v := range m {
 		s.Add(prefix+"."+k, v)
 	}
 }
 
+// handler is http handler multiplexing calls by req.Method
 func (s *Server) handler(w http.ResponseWriter, r *http.Request) {
 	req := struct {
 		ID     uint64           `json:"id"`
@@ -144,6 +143,7 @@ func (s *Server) handler(w http.ResponseWriter, r *http.Request) {
 	render.JSON(w, r, fn(req.ID, params))
 }
 
+// basicAuth middleware. enabled only if both AuthUser and AuthPasswd defined.
 func (s *Server) basicAuth(h http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {