Improve info and health endpoints (#432)

- Properly return version for web and CLI status - Remove FQDN from /v2/info endpoint - Update API docs
shieldproject · Jul 13, 2018 · 19ab3dd · 19ab3dd
1 parent 40afef8
commit 19ab3dd
Show file tree

Hide file tree

Showing 8 changed files with 106 additions and 87 deletions.
diff --git a/client/v2/shield/info.go b/client/v2/shield/info.go
@@ -3,7 +3,6 @@ package shield
 type Info struct {
 	Version string `json:"version,omitempty"`
 	IP      string `json:"ip,omitempty"`
-	FQDN    string `json:"fqdn,omitempty"`
 	Env     string `json:"env,omitempty"`
 	Color   string `json:"color,omitempty"`
 	MOTD    string `json:"motd,omitempty"`

diff --git a/client/v2/shield/status.go b/client/v2/shield/status.go
@@ -1,39 +1,36 @@
 package shield
 
 type Status struct {
-	SHIELD struct {
-		Version string `json:"version"`
-		IP      string `json:"ip"`
-		FQDN    string `json:"fqdn"`
-		Env     string `json:"env"`
-		MOTD    string `json:"motd"`
-	} `json:"shield"`
+	Health  StatusHealth  `json:"health"`
+	Storage StatusStorage `json:"storage"`
+	Jobs    StatusJobs    `json:"jobs"`
+	Stats   StatusStats   `json:"stats"`
+}
 
-	Health struct {
-		Core      string `json:"core"`
-		StorageOK bool   `json:"storage_ok"`
-		JobsOK    bool   `json:"jobs_ok"`
-	} `json:"health"`
+type StatusHealth struct {
+	Core      string `json:"core"`
+	StorageOK bool   `json:"storage_ok"`
+	JobsOK    bool   `json:"jobs_ok"`
+}
 
-	Storage []struct {
-		Name   string `json:"name"`
-		Health bool   `json:"healthy"`
-	} `json:"storage"`
+type StatusStorage []struct {
+	Name   string `json:"name"`
+	Health bool   `json:"healthy"`
+}
 
-	Jobs []struct {
-		UUID    string `json:"uuid"`
-		Target  string `json:"target"`
-		Job     string `json:"job"`
-		Healthy bool   `json:"healthy"`
-	} `json:"jobs"`
+type StatusJobs []struct {
+	UUID    string `json:"uuid"`
+	Target  string `json:"target"`
+	Job     string `json:"job"`
+	Healthy bool   `json:"healthy"`
+}
 
-	Stats struct {
-		Jobs        int   `json:"jobs"`
-		Systems     int   `json:"systems"`
-		Archives    int   `json:"archives"`
-		StorageUsed int64 `json:"storage"`
-		DailyDelta  int   `json:"daily"`
-	} `json:"stats"`
+type StatusStats struct {
+	Jobs        int   `json:"jobs"`
+	Systems     int   `json:"systems"`
+	Archives    int   `json:"archives"`
+	StorageUsed int64 `json:"storage"`
+	DailyDelta  int   `json:"daily"`
 }
 
 func (c *Client) GlobalStatus() (*Status, error) {

diff --git a/cmd/shield/main.go b/cmd/shield/main.go
@@ -976,7 +976,20 @@ func main() {
 		}
 
 		if opts.JSON {
-			fmt.Printf("%s\n", asJSON(status))
+			fmt.Printf("%s\n", asJSON(
+				struct {
+					Shield  *shield.Info         `json:"shield"`
+					Health  shield.StatusHealth  `json:"health"`
+					Storage shield.StatusStorage `json:"storage"`
+					Jobs    shield.StatusJobs    `json:"jobs"`
+					Stats   shield.StatusStats   `json:"stats"`
+				}{
+					Shield:  info,
+					Health:  status.Health,
+					Storage: status.Storage,
+					Jobs:    status.Jobs,
+					Stats:   status.Stats,
+				}))
 			break
 		}
 

diff --git a/core/api.go b/core/api.go
@@ -189,16 +189,6 @@ func (core *Core) initJS(w http.ResponseWriter, req *http.Request) {
 	fmt.Fprintf(w, "// init.js\n")
 	fmt.Fprintf(w, "var $global = {}\n")
 
-	info := core.checkInfo()
-	b, err := json.Marshal(info)
-	if err != nil {
-		log.Errorf("init.js: failed to marshal SHIELD core info into JSON: %s", err)
-		fmt.Fprintf(w, "// failed to retrieve SHIELD core info...\n")
-		fmt.Fprintf(w, "$global.shield = {};\n")
-	} else {
-		fmt.Fprintf(w, "$global.shield = %s;\n", string(b))
-	}
-
 	const unauthFail = "// failed to determine user authentication state...\n"
 	const unauthJS = "$global.auth = {\"unauthenticated\":true};\n"
 
@@ -209,6 +199,16 @@ func (core *Core) initJS(w http.ResponseWriter, req *http.Request) {
 		fmt.Fprintf(w, unauthJS)
 		return
 	}
+
+	b, err := json.Marshal(core.checkInfo(user != nil))
+	if err != nil {
+		log.Errorf("init.js: failed to marshal SHIELD core info into JSON: %s", err)
+		fmt.Fprintf(w, "// failed to retrieve SHIELD core info...\n")
+		fmt.Fprintf(w, "$global.shield = {};\n")
+	} else {
+		fmt.Fprintf(w, "$global.shield = %s;\n", string(b))
+	}
+
 	if user == nil {
 		fmt.Fprintf(w, unauthJS)
 		return

diff --git a/core/info.go b/core/info.go
@@ -3,21 +3,23 @@ package core
 type Info struct {
 	Version string `json:"version,omitempty"`
 	IP      string `json:"ip,omitempty"`
-	FQDN    string `json:"fqdn,omitempty"`
 	Env     string `json:"env,omitempty"`
 	Color   string `json:"color,omitempty"`
 	MOTD    string `json:"motd,omitempty"`
 
 	API int `json:"api"`
 }
 
-func (core *Core) checkInfo() Info {
-	return Info{
+func (core *Core) checkInfo(auth bool) Info {
+	info := Info{
 		IP:    core.ip,
-		FQDN:  core.fqdn,
 		MOTD:  core.motd,
 		Color: core.color,
 		Env:   core.env,
 		API:   2,
 	}
+	if auth {
+		info.Version = Version
+	}
+	return info
 }
diff --git a/core/v2.go b/core/v2.go
@@ -112,15 +112,14 @@ func (core *Core) v2API() *route.Router {
 	}
 
 	r.Dispatch("GET /v2/info", func(r *route.Request) { // {{{
-		info := core.checkInfo()
-
-		/* only show sensitive things like version numbers
-		   to authenticated sessions. */
+		auth := false
 		if u, _ := core.AuthenticatedUser(r); u != nil {
-			info.Version = Version
+			/* only show sensitive things like version numbers
+			to authenticated sessions. */
+			auth = true
 		}
 
-		r.OK(info)
+		r.OK(core.checkInfo(auth))
 	})
 	// }}}
 	r.Dispatch("GET /v2/health", func(r *route.Request) { // {{{

diff --git a/docs/API.md b/docs/API.md
@@ -99,6 +99,9 @@ with different versions of SHIELD Core and clients.
     {
       "version" : "6.7.2",
       "env"     : "PRODUCTION",
+      "color"   : "yellow",
+      "motd"    : "Welcome to S.H.I.E.L.D.",
+      "ip"      : "10.0.0.5",
       "api"     : 2
     }
 
@@ -108,6 +111,15 @@ context of an authenticated session.
 The `env` key is configurable by the SHIELD site administrator,
 at deployment / boot time.
 
+Similar to env, the `color` key is configurable by the SHIELD site
+administrator, used to visually differentiate various SHIELD 
+deployments in the WebUI.
+
+The `motd` is what is displayed upon login, and can be changed by
+the SHIELD site administrator.
+
+The `ip` key is the ip of the SHIELD core.
+
 The `api` key is a single integer that identifies which version
 of the SHIELD API this core implements.  Currently, there are
 two possible values:
@@ -143,14 +155,6 @@ of `application/json`, and something similar to the following JSON
 payload in the response body:
 
     {
-      "shield": {
-        "version" : "6.7.2",
-        "ip"      : "10.0.0.5",
-        "fqdn"    : "shield.example.com",
-        "env"     : "PRODUCTION",
-        "color"   : "",
-        "motd"    : "Welcome to S.H.I.E.L.D."
-      },
       "health": {
         "core"       : "unsealed",
         "storage_ok" : true,
@@ -184,7 +188,7 @@ payload in the response body:
 
 **Access Control**
 
-This endpoint requires no authentication or authorization.
+You must be authenticated to access this API endpoint.
 
 **Errors**
 
@@ -194,6 +198,11 @@ The following error messages can be returned:
   an internal error occurred and should be investigated by the
   site administrators
 
+- **Authorization required**:
+  The request was made without an authenticated session or auth token.
+  See **Authentication** for more details.  The request may be retried
+  after authentication.
+
 
 ### GET /v2/tenants/:tenant/health
 
@@ -216,14 +225,6 @@ of `application/json`, and something similar to the following JSON
 payload in the response body:
 
     {
-      "shield": {
-        "version" : "6.7.2",
-        "ip"      : "10.0.0.5",
-        "fqdn"    : "shield.example.com",
-        "env"     : "PRODUCTION",
-        "color"   : "",
-        "motd"    : "Welcome to S.H.I.E.L.D."
-      },
       "health": {
         "core"       : "unsealed",
         "storage_ok" : true,
@@ -257,7 +258,9 @@ payload in the response body:
 
 **Access Control**
 
-This endpoint requires no authentication or authorization.
+You must be authenticated to access this API endpoint.
+
+You must also have the `operator` role on the tenant.
 
 **Errors**
 
@@ -267,6 +270,16 @@ The following error messages can be returned:
   an internal error occurred and should be investigated by the
   site administrators
 
+- **Authorization required**:
+  The request was made without an authenticated session or auth token.
+  See **Authentication** for more details.  The request may be retried
+  after authentication.
+
+- **Access denied**:
+  The requester lacks sufficient tenant or system role assignment.
+  Refer to the **Access Control** subsection, above.
+  The request should not be retried.
+
 
 ## SHIELD Authentication
 

diff --git a/docs/API.yml b/docs/API.yml
@@ -114,6 +114,9 @@ sections:
             {
               "version" : "6.7.2",
               "env"     : "PRODUCTION",
+              "color"   : "yellow",
+              "motd"    : "Welcome to S.H.I.E.L.D.",
+              "ip"      : "10.0.0.5",
               "api"     : 2
             }
           summary: |
@@ -125,6 +128,15 @@ sections:
             The `env` key is configurable by the SHIELD site administrator,
             at deployment / boot time.
 
+            Similar to env, the `color` key is configurable by the SHIELD site
+            administrator, used to visually differentiate various SHIELD
+            deployments in the WebUI.
+
+            The `motd` is what is displayed upon login, and can be changed by
+            the SHIELD site administrator.
+
+            The `ip` key is the ip of the SHIELD core.
+
             The `api` key is a single integer that identifies which version
             of the SHIELD API this core implements.  Currently, there are
             two possible values:
@@ -140,7 +152,7 @@ sections:
         intro: |
           Returns health information about the SHIELD Core, connected
           storage accounts, and general metrics, at a global scope.
-        access: ~
+        access: any
 
         response:
           summary: |
@@ -152,14 +164,6 @@ sections:
 
           json: |
             {
-              "shield": {
-                "version" : "6.7.2",
-                "ip"      : "10.0.0.5",
-                "fqdn"    : "shield.example.com",
-                "env"     : "PRODUCTION",
-                "color"   : "",
-                "motd"    : "Welcome to S.H.I.E.L.D."
-              },
               "health": {
                 "core"       : "unsealed",
                 "storage_ok" : true,
@@ -202,7 +206,7 @@ sections:
           Returns health information about the SHIELD Core, connected
           storage accounts, and general metrics, restricted to the scope
           visible to a single tenant.
-        access: ~
+        access: [tenant, operator]
 
         response:
           summary: |
@@ -214,14 +218,6 @@ sections:
 
           json: |
             {
-              "shield": {
-                "version" : "6.7.2",
-                "ip"      : "10.0.0.5",
-                "fqdn"    : "shield.example.com",
-                "env"     : "PRODUCTION",
-                "color"   : "",
-                "motd"    : "Welcome to S.H.I.E.L.D."
-              },
               "health": {
                 "core"       : "unsealed",
                 "storage_ok" : true,