add comments

Author: anik120

catalogd/internal/storage/index.go

@@ -12,12 +12,25 @@ import (
 	"github.com/operator-framework/operator-registry/alpha/declcfg"
 )
 
+// index is an index of sections of an FBC file used to lookup FBC blobs that
+// match any combination of their schema, package, and name fields.
+
+// This index strikes a balance between space and performance. It indexes each field
+// separately, and performs logical set intersections at lookup time in order to implement
+// a multi-parameter query.
+//
+// Note: it is permissible to change the indexing algorithm later if it is necessary to
+// tune the space / performance tradeoff. However care should be taken to ensure
+// that the actual content returned by the index remains identical, as users of the index
+// may be sensitive to differences introduced by index algorithm changes (e.g. if the
+// order of the returned sections changes).
 type index struct {
 	BySchema  map[string][]section `json:"by_schema"`
 	ByPackage map[string][]section `json:"by_package"`
 	ByName    map[string][]section `json:"by_name"`
 }
 
+// A section is the byte offset and length of an FBC blob within the file.
 type section struct {
 	offset int64
 	length int64

catalogd/internal/storage/localdir.go

@@ -22,15 +22,22 @@ import (
 
 // LocalDirV1 is a storage Instance. When Storing a new FBC contained in
 // fs.FS, the content is first written to a temporary file, after which
-// it is copied to its final destination in RootDir/catalogName/. This is
-// done so that clients accessing the content stored in RootDir/catalogName have
-// atomic view of the content for a catalog.
+// it is copied to its final destination in RootDir/<catalogName>.jsonl. This is
+// done so that clients accessing the content stored in RootDir/<catalogName>.json1
+// have an atomic view of the content for a catalog.
 type LocalDirV1 struct {
 	RootDir            string
 	RootURL            *url.URL
 	EnableQueryHandler bool
 
-	m  sync.RWMutex
+	m sync.RWMutex
+	// this singleflight Group is used in `getIndex()`` to handle concurrent HTTP requests
+	// optimally. With the use of this slightflight group, the index is loaded from disk
+	// once per concurrent group of HTTP requests being handled by the query handler.
+	// The single flight instance gives us a way to load the index from disk exactly once
+	// per concurrent group of callers, and then let every concurrent caller have access to
+	// the loaded index. This avoids lots of unnecessary open/decode/close cycles when concurrent
+	// requests are being handled, which improves overall performance and decreases response latency.
 	sf singleflight.Group
 }