vulndb/govulncheck: add forgotten cache documentation
Change-Id: I61439c7dbf7685908b789a4ccc51471952f55cf5
Reviewed-on: https://go-review.googlesource.com/c/exp/+/347469
Run-TryBot: Zvonimir Pavlinovic <zpavlinovic@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>
Trust: Zvonimir Pavlinovic <zpavlinovic@google.com>
diff --git a/vulndb/govulncheck/cache.go b/vulndb/govulncheck/cache.go
index 7021d7c..96a281d 100644
--- a/vulndb/govulncheck/cache.go
+++ b/vulndb/govulncheck/cache.go
@@ -15,7 +15,32 @@
"golang.org/x/vulndb/osv"
)
+// NOTE: this cache implementation should be kept internal to the go tooling
+// (i.e. cmd/go/internal/something) so that the vulndb cache is owned by the
+// go command. Also it is currently NOT CONCURRENCY SAFE since it does not
+// implement file locking. If ported to the stdlib it should use
+// cmd/go/internal/lockedfile.
+
+// The cache uses a single JSON index file for each vulnerability database
+// which contains the map from packages to the time the last
+// vulnerability for that package was added/modified and the time that
+// the index was retrieved from the vulnerability database. The JSON
+// format is as follows:
+//
+// $GOPATH/pkg/mod/cache/download/vulndb/{db hostname}/indexes/index.json
+// {
+// Retrieved time.Time
+// Index osv.DBIndex
+// }
+//
+// Each package also has a JSON file which contains the array of vulnerability
+// entries for the package. The JSON format is as follows:
+//
+// $GOPATH/pkg/mod/cache/download/vulndb/{db hostname}/{import path}/vulns.json
+// []*osv.Entry
+
// fsCache is file-system cache implementing osv.Cache
+// TODO: make cache thread-safe
type fsCache struct {
rootDir string
}
