feat(filetree): structured entries in DirectoryReply (#3425)

Benefits include not forcing clients of the API to understand the Kythe ticket format for files/directories and allowing for extensions (e.g. build configurations) to each directory entry by making it its own message.

This change includes the proposed DirectoryReply fields, deprecates the existing subdirectory/file fields, and updates all known implementers of the filetree.Interface.  Later changes will update clients of the API.

kythe/go/services/filetree/BUILD

@@ -13,5 +13,6 @@ go_library(
         "//kythe/go/util/schema/nodes",
         "//kythe/proto:filetree_go_proto",
         "//kythe/proto:storage_go_proto",
+        "@com_github_golang_protobuf//proto:go_default_library",
     ],
 )

kythe/go/services/filetree/filetree.go

@@ -34,12 +34,13 @@ import (
 	"kythe.io/kythe/go/util/schema/facts"
 	"kythe.io/kythe/go/util/schema/nodes"
 
+	"github.com/golang/protobuf/proto"
+
 	ftpb "kythe.io/kythe/proto/filetree_go_proto"
 	spb "kythe.io/kythe/proto/storage_go_proto"
 )
 
 // Service provides an interface to explore a tree of VName files.
-// TODO(schroederc): add Context argument to interface methods
 type Service interface {
 	// Directory returns the contents of the directory at the given corpus/root/path.
 	Directory(context.Context, *ftpb.DirectoryRequest) (*ftpb.DirectoryReply, error)
@@ -90,6 +91,10 @@ func (m *Map) AddFile(file *spb.VName) {
 	dirPath := CleanDirPath(path.Dir(file.Path))
 	dir := m.ensureDir(file.Corpus, file.Root, dirPath)
 	dir.File = addToSet(dir.File, ticket)
+	dir.Entry = addEntry(dir.Entry, &ftpb.DirectoryReply_Entry{
+		Kind: ftpb.DirectoryReply_FILE,
+		Name: filepath.Base(file.Path),
+	})
 }
 
 // CorpusRoots implements part of the filetree.Service interface.
@@ -147,7 +152,11 @@ func (m *Map) ensureDir(corpus, root, path string) *ftpb.DirectoryReply {
 	dirs := m.ensureCorpusRoot(corpus, root)
 	dir := dirs[path]
 	if dir == nil {
-		dir = &ftpb.DirectoryReply{}
+		dir = &ftpb.DirectoryReply{
+			Corpus: corpus,
+			Root:   root,
+			Path:   path,
+		}
 		dirs[path] = dir
 
 		if path != "" {
@@ -158,6 +167,10 @@ func (m *Map) ensureDir(corpus, root, path string) *ftpb.DirectoryReply {
 				Path:   path,
 			}
 			parent.Subdirectory = addToSet(parent.Subdirectory, uri.String())
+			parent.Entry = addEntry(parent.Entry, &ftpb.DirectoryReply_Entry{
+				Kind: ftpb.DirectoryReply_DIRECTORY,
+				Name: filepath.Base(path),
+			})
 		}
 	}
 	return dir
@@ -172,6 +185,15 @@ func addToSet(strs []string, str string) []string {
 	return append(strs, str)
 }
 
+func addEntry(entries []*ftpb.DirectoryReply_Entry, e *ftpb.DirectoryReply_Entry) []*ftpb.DirectoryReply_Entry {
+	for _, x := range entries {
+		if proto.Equal(x, e) {
+			return entries
+		}
+	}
+	return append(entries, e)
+}
+
 type webClient struct{ addr string }
 
 // CorpusRoots implements part of the Service interface.

kythe/go/serving/filetree/BUILD

@@ -7,6 +7,7 @@ go_library(
     srcs = ["filetree.go"],
     deps = [
         "//kythe/go/storage/table",
+        "//kythe/go/util/kytheuri",
         "//kythe/proto:filetree_go_proto",
         "//kythe/proto:serving_go_proto",
     ],

kythe/go/serving/filetree/filetree.go

@@ -25,9 +25,11 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"path/filepath"
 	"strings"
 
 	"kythe.io/kythe/go/storage/table"
+	"kythe.io/kythe/go/util/kytheuri"
 
 	ftpb "kythe.io/kythe/proto/filetree_go_proto"
 	srvpb "kythe.io/kythe/proto/serving_go_proto"
@@ -72,12 +74,40 @@ func (t *Table) Directory(ctx context.Context, req *ftpb.DirectoryRequest) (*ftp
 	} else if err != nil {
 		return nil, fmt.Errorf("lookup error: %v", err)
 	}
+	entries, err := parseLegacyEntries(nil, ftpb.DirectoryReply_FILE, d.FileTicket)
+	if err != nil {
+		return nil, err
+	}
+	entries, err = parseLegacyEntries(entries, ftpb.DirectoryReply_DIRECTORY, d.Subdirectory)
+	if err != nil {
+		return nil, err
+	}
 	return &ftpb.DirectoryReply{
+		// TODO(schroederc): remove deprecated fields
 		Subdirectory: d.Subdirectory,
 		File:         d.FileTicket,
+
+		Corpus: req.Corpus,
+		Root:   req.Root,
+		Path:   req.Path,
+		Entry:  entries,
 	}, nil
 }
 
+func parseLegacyEntries(entries []*ftpb.DirectoryReply_Entry, kind ftpb.DirectoryReply_Kind, tickets []string) ([]*ftpb.DirectoryReply_Entry, error) {
+	for _, ticket := range tickets {
+		uri, err := kytheuri.Parse(ticket)
+		if err != nil {
+			return nil, fmt.Errorf("invalid serving data: %v", err)
+		}
+		entries = append(entries, &ftpb.DirectoryReply_Entry{
+			Kind: kind,
+			Name: filepath.Base(uri.Path),
+		})
+	}
+	return entries, nil
+}
+
 // CorpusRoots implements part of the filetree Service interface.
 func (t *Table) CorpusRoots(ctx context.Context, req *ftpb.CorpusRootsRequest) (*ftpb.CorpusRootsReply, error) {
 	key := CorpusRootsKey

kythe/proto/filetree.proto

@@ -46,9 +46,35 @@ message DirectoryRequest {
 }
 
 message DirectoryReply {
-  // Set of tickets for each contained sub-directory's corpus, root, and path.
-  repeated string subdirectory = 1;
+  // The corpus of the requested directory.
+  string corpus = 3;
+  // The root of the requested directory.
+  string root = 4;
+  // The path of the requested directory.
+  string path = 5;
 
-  // Set of file tickets contained within this directory.
-  repeated string file = 2;
+  // Each known entry in the requested directory.  Each entry shares the above
+  // corpus, root, and path prefix.
+  repeated Entry entry = 6;
+
+  message Entry {
+    // The kind of entry.
+    Kind kind = 1;
+
+    // The basename of the entry within the directory.
+    string name = 2;
+
+    // TODO(schroederc): repeated string build_configuration = 3;
+  }
+  enum Kind {
+    UNKNOWN = 0;
+    FILE = 1;
+    DIRECTORY = 2;
+  }
+
+  // DEPRECATED: Set of tickets for each contained sub-directory's corpus, root,
+  // and path.
+  repeated string subdirectory = 1 [deprecated = true];
+  // DEPRECATED: Set of file tickets contained within this directory.
+  repeated string file = 2 [deprecated = true];
 }