logical/framework: make help look nicer

logical/framework/backend.go

@@ -3,6 +3,7 @@ package framework
 import (
 	"fmt"
 	"regexp"
+	"sort"
 	"sync"
 	"time"
 
@@ -184,14 +185,29 @@ func (b *Backend) route(path string) (*Path, map[string]string) {
 }
 
 func (b *Backend) handleRootHelp() (*logical.Response, error) {
+	// Build a mapping of the paths and get the paths alphabetized to
+	// make the output prettier.
+	pathsMap := make(map[string]*Path)
 	paths := make([]string, 0, len(b.Paths))
-	for _, p := range b.pathsRe {
+	for i, p := range b.pathsRe {
 		paths = append(paths, p.String())
+		pathsMap[p.String()] = b.Paths[i]
+	}
+	sort.Strings(paths)
+
+	// Build the path data
+	pathData := make([]rootHelpTemplatePath, 0, len(paths))
+	for _, route := range paths {
+		p := pathsMap[route]
+		pathData = append(pathData, rootHelpTemplatePath{
+			Path: route,
+			Help: p.HelpSynopsis,
+		})
 	}
 
 	help, err := executeTemplate(rootHelpTemplate, &rootHelpTemplateData{
 		Help:  b.Help,
-		Paths: paths,
+		Paths: pathData,
 	})
 	if err != nil {
 		return nil, err
@@ -327,7 +343,12 @@ func (t FieldType) Zero() interface{} {
 
 type rootHelpTemplateData struct {
 	Help  string
-	Paths []string
+	Paths []rootHelpTemplatePath
+}
+
+type rootHelpTemplatePath struct {
+	Path string
+	Help string
 }
 
 const rootHelpTemplate = `
@@ -339,9 +360,12 @@ const rootHelpTemplate = `
 
 The following paths are supported by this backend. To view help for
 any of the paths below, use the help command with any route matching
-the path pattern.
+the path pattern. Note that depending on the policy of your auth token,
+you may or may not be able to access certain paths.
+
+{{range .Paths}}{{indent 4 .Path}}
+{{indent 8 .Help}}
 
-{{range .Paths}}    {{.}}
 {{end}}
 
 `

logical/framework/template.go

@@ -1,6 +1,7 @@
 package framework
 
 import (
+	"bufio"
 	"bytes"
 	"fmt"
 	"strings"
@@ -8,8 +9,13 @@ import (
 )
 
 func executeTemplate(tpl string, data interface{}) (string, error) {
+	// Define the functions
+	funcs := map[string]interface{}{
+		"indent": funcIndent,
+	}
+
 	// Parse the help template
-	t, err := template.New("root").Parse(tpl)
+	t, err := template.New("root").Funcs(funcs).Parse(tpl)
 	if err != nil {
 		return "", fmt.Errorf("error parsing template: %s", err)
 	}
@@ -22,3 +28,14 @@ func executeTemplate(tpl string, data interface{}) (string, error) {
 
 	return strings.TrimSpace(buf.String()), nil
 }
+
+func funcIndent(count int, text string) string {
+	var buf bytes.Buffer
+	prefix := strings.Repeat(" ", count)
+	scan := bufio.NewScanner(strings.NewReader(text))
+	for scan.Scan() {
+		buf.WriteString(prefix + scan.Text() + "\n")
+	}
+
+	return strings.TrimRight(buf.String(), "\n")
+}

vault/logical_system.go

@@ -12,6 +12,8 @@ func NewSystemBackend(core *Core) logical.Backend {
 	b := &SystemBackend{Core: core}
 
 	return &framework.Backend{
+		Help: strings.TrimSpace(sysHelpRoot),
+
 		PathsSpecial: &logical.Paths{
 			Root: []string{
 				"mounts/*",
@@ -656,6 +658,12 @@ func (b *SystemBackend) handleRawDelete(
 	return nil, nil
 }
 
+const sysHelpRoot = `
+The system backend is built-in to Vault and cannot be remounted or
+unmounted. It contains the paths that are used to configure Vault itself
+as well as perform core operations.
+`
+
 // sysHelp is all the help text for the sys backend.
 var sysHelp = map[string][2]string{
 	"mounts": {