docs: rework current repo docs

docs/README.md

@@ -1,80 +1,12 @@
 # Knowledge Base
 
-Below lies a list of resources that may be helpful to those looking to understand the go-control-plane API. The aim of these artifacts is to provide enough knowledge and understanding to newcomers and users who wish to use this API within their own codebases to implement an xDS compliant control-plane.
+Below lies a list of resources that may be helpful to those looking to understand the go-control-plane API.
 
-## Snapshot Cache
+## Implementations
 The following guides may be helpful on how to use go-control-plane's Snapshot Cache:
-- [Snapshot.md](cache/Snapshot.md)
-- [Server.md](cache/Server.md)
+- [cache.md](snapshot.md)
+- [server.md](server.md)
 
 ## Getting Started
-Below is an example of a simple xDS ready server utilizing the provided Snapshot Cache and gRPC server logic.
 
-```go
-import (
-    "context"
-    "net"
-    "time"
-
-    "google.golang.org/grpc"
-    "google.golang.org/grpc/keepalive"
-
-    api "github.com/envoyproxy/go-control-plane/envoy/api/v2"
-    discovery "github.com/envoyproxy/go-control-plane/envoy/service/discovery/v2"
-    "github.com/envoyproxy/go-control-plane/pkg/cache/v2"
-    xds "github.com/envoyproxy/go-control-plane/pkg/server/v2"
-)
-
-const (
-    grpcKeepaliveTime        = 30 * time.Second
-    grpcKeepaliveTimeout     = 5 * time.Second
-    grpcKeepaliveMinTime     = 30 * time.Second
-    grpcMaxConcurrentStreams = 1000000
-)
-
-func main() {
-    snapshotCache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
-    server := xds.NewServer(context.Background(), snapshotCache, nil)
-    var grpcOptions []grpc.ServerOption
-    grpcOptions = append(grpcOptions,
-        grpc.MaxConcurrentStreams(grpcMaxConcurrentStreams),
-        grpc.KeepaliveParams(keepalive.ServerParameters{
-            Time:    grpcKeepaliveTime,
-            Timeout: grpcKeepaliveTimeout,
-        }),
-        grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
-            MinTime:             grpcKeepaliveMinTime,
-            PermitWithoutStream: true,
-        }),
-    )
-    grpcServer := grpc.NewServer(grpcOptions...)
-    lis, _ := net.Listen("tcp", ":8080")
-
-    discovery.RegisterAggregatedDiscoveryServiceServer(grpcServer, server)
-    api.RegisterEndpointDiscoveryServiceServer(grpcServer, server)
-    api.RegisterClusterDiscoveryServiceServer(grpcServer, server)
-    api.RegisterRouteDiscoveryServiceServer(grpcServer, server)
-    api.RegisterListenerDiscoveryServiceServer(grpcServer, server)
-    go func() {
-        if err := grpcServer.Serve(lis); err != nil {
-            // error handling
-        }
-    }()
-}
-```
-
-As mentioned in the README's [Scope](https://github.com/envoyproxy/go-control-plane/blob/master/README.md#scope), you need to cache Envoy configurations.
-Generate the key for the corresponding snapshot based on the node information provided from an Envoy node, then cache the configurations.
-
-```go
-import (
-    "github.com/envoyproxy/go-control-plane/pkg/cache/v2"
-    "github.com/envoyproxy/go-control-plane/pkg/cache/types"
-)
-
-var clusters, endpoints, routes, listeners, runtimes []types.Resource
-
-snapshotCache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
-snapshot := cache.NewSnapshot("1.0", endpoints, clusters, routes, listeners, runtimes)
-_ = snapshotCache.SetSnapshot("node1", snapshot)
-```
+A fully functional server/cache example is provided inside `internal/example`. Head there to see how a basic control-plane is initialized with a go-control-plane backed cache and server.

docs/cache.md

@@ -0,0 +1,65 @@
+# SnapshotCache
+
+[SnapshotCache](https://github.com/envoyproxy/go-control-plane/blob/main/pkg/cache/v3/simple.go#L40) is a snapshot-based caching mechanism that maintains a versioned config snapshot per node. See the original README scope section for more detailed explanations on the individual cache systems.
+
+> *NOTE*: SnapshotCache can operate as a REST or bi-di streaming xDS server
+
+## Create a Snapshot Cache
+
+To create a snapshot cache, we simply call the provided constructor:
+```go
+// Create a cache
+cache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
+```
+This `cache` object holds a fully compliant [SnapshotCache](https://github.com/envoyproxy/go-control-plane/blob/main/pkg/cache/v3/simple.go#L40) with the necessary methods to manage a configuration cache lifecycle.
+
+> *NOTE*: The cache needs a high access level inside the management server as it's the source of truth for xDS resources.
+
+## Snapshots
+
+Snapshots are groupings of resources at a given point in time for a node cluster. In other words Envoy's and consuming xDS clients registering as node `abc` all share a snapshot of config. This snapshot is the singular source of truth in the cache that represents config for any of those consumers.
+
+> *NOTE*: Snapshots can be partial, e.g., only including RDS or EDS resources. 
+
+```go
+snap, err := cache.NewSnapshot("v0", map[resource.Type][]types.Resource{
+    resource.EndpointType:        endpoints,
+    resource.ClusterType:         clusters,
+    resource.RouteType:           routes,
+    resource.ScopedRouteType:     scopedRoutes,
+    resource.ListenerType:        listeners,
+    resource.RuntimeType:         runtimes,
+    resource.SecretType:          secrets,
+    resource.ExtensionConfigType: extensions,
+})
+```
+
+For a more in-depth example of how to genereate a snapshot, explore our example found [here](https://github.com/envoyproxy/go-control-plane/blob/main/internal/example/resource.go#L168).
+
+We recommend verifying that your new `snapshot` is consistent within itself meaning that the dependent resources are exactly listed in the snapshot:
+
+```go
+if err := snapshot.Consistent(); err != nil {
+   l.Errorf("snapshot inconsistency: %+v\n%+v", snapshot, err)
+   os.Exit(1)
+}
+```
+
+- all EDS resources are listed by name in CDS resources
+- all SRDS/RDS resources are listed by name in LDS resources
+- all RDS resources are listed by name in SRDS resources
+
+> *NOTE*: Clusters and Listeners are requested without name references, so Envoy will accept the snapshot list of clusters as-is even if it does not match all references found in xDS.
+
+Setting a snapshot is as simple as:
+```go
+// Add the snapshot to the cache
+if err := cache.SetSnapshot("envoy-node-id", snapshot); err != nil {
+    l.Errorf("snapshot error %q for %+v", err, snapshot)
+    os.Exit(1)
+}
+```
+
+This will trigger all open watches internal to the caching [config watchers](https://github.com/envoyproxy/go-control-plane/blob/main/pkg/cache/v3/cache.go#L45) and anything listening for changes will received updates and responses from the new snapshot.
+
+*Note*: that a node ID must be provided along with the snapshot object. Internally a mapping of the two is kept so each node can receive the latest version of its configuration.