add documentation

Author: zac-nixon

pkg/gateway/routeutils/backend.go

@@ -10,6 +10,7 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// Backend an abstraction on the Gateway Backend, meant to hide the underlying backend type from consumers (unless they really want to see it :))
 type Backend struct {
 	Service             *corev1.Service
 	ServicePort         *corev1.ServicePort
@@ -18,7 +19,12 @@ type Backend struct {
 	// Add TG config here //
 }
 
+// TODOs:
+// 1/ Add reference grant checking
+// 2/ Add target group configuration resolution
+
 // NOTE: Currently routeKind is not used, however, we will need it to load TG specific configuration.
+// commonBackendLoader this function will load the services and target group configurations associated with this gateway backend.
 func commonBackendLoader(ctx context.Context, k8sClient client.Client, typeSpecificBackend interface{}, backendRef gwv1.BackendRef, routeIdentifier types.NamespacedName, routeKind string) (*Backend, error) {
 
 	// We only support references of type service.

pkg/gateway/routeutils/constants.go

@@ -6,6 +6,7 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// Route Kinds
 const (
 	TCPRouteKind  = "TCPRoute"
 	UDPRouteKind  = "UDPRoute"
@@ -14,6 +15,7 @@ const (
 	GRPCRouteKind = "GRPCRoute"
 )
 
+// RouteKind to Route Loader. These functions will pull data directly from the kube api or local cache.
 var allRoutes = map[string]func(context context.Context, client client.Client) ([]preLoadRouteDescriptor, error){
 	TCPRouteKind:  ListTCPRoutes,
 	UDPRouteKind:  ListUDPRoutes,
@@ -22,6 +24,7 @@ var allRoutes = map[string]func(context context.Context, client client.Client) (
 	GRPCRouteKind: ListGRPCRoutes,
 }
 
+// Default protocol map used to infer accepted route kinds when a listener doesn't specify the `allowedRoutes` field.
 var defaultProtocolToRouteKindMap = map[gwv1.ProtocolType]string{
 	gwv1.TCPProtocolType:   TCPRouteKind,
 	gwv1.UDPProtocolType:   UDPRouteKind,

pkg/gateway/routeutils/descriptor.go

@@ -7,6 +7,9 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// routeMetadataDescriptor a common set of functions that will describe a route.
+// These are intentionally meant to be type agnostic;
+// however, consumers can use `GetRawRoute()` to inspect the actual route fields if needed.
 type routeMetadataDescriptor interface {
 	GetRouteNamespacedName() types.NamespacedName
 	GetRouteKind() string
@@ -15,11 +18,17 @@ type routeMetadataDescriptor interface {
 	GetRawRoute() interface{}
 }
 
+// preLoadRouteDescriptor this object is used to represent a route description that has not loaded its child data (services, tg config)
+// generally use this interface to represent broad data, filter that data down to the absolutely required data, and the call
+// loadAttachedRules() to generate a full route description.
 type preLoadRouteDescriptor interface {
 	routeMetadataDescriptor
 	loadAttachedRules(context context.Context, k8sClient client.Client) (RouteDescriptor, error)
 }
 
+// RouteDescriptor is a type agnostic representation of a Gateway Route.
+// This interface holds all data necessary to construct
+// an ELBv2 object out of Kubernetes objects.
 type RouteDescriptor interface {
 	routeMetadataDescriptor
 	GetAttachedRules() []RouteRule

pkg/gateway/routeutils/grpc.go

@@ -8,6 +8,12 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+/*
+This class holds the representation of a GRPC route.
+Generally, outside consumers will use GetRawRouteRule to inspect the
+GRPC specific features of the route.
+*/
+
 /* Route Rule */
 
 var _ RouteRule = &convertedGRPCRouteRule{}

pkg/gateway/routeutils/http.go

@@ -8,6 +8,12 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+/*
+This class holds the representation of an HTTP route.
+Generally, outside consumers will use GetRawRouteRule to inspect the
+HTTP specific features of the route.
+*/
+
 /* Route Rule */
 
 var _ RouteRule = &convertedHTTPRouteRule{}

pkg/gateway/routeutils/listener_attachment_helper.go

@@ -2,39 +2,43 @@ package routeutils
 
 import (
 	"context"
-	"fmt"
 	"k8s.io/apimachinery/pkg/util/sets"
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// listenerAttachmentHelper is an internal utility interface that can be used to determine if a listener will allow
+// a route to attach to it.
 type listenerAttachmentHelper interface {
 	listenerAllowsAttachment(ctx context.Context, gw gwv1.Gateway, listener gwv1.Listener, route preLoadRouteDescriptor) (bool, error)
 }
 
 var _ listenerAttachmentHelper = &listenerAttachmentHelperImpl{}
 
+// listenerAttachmentHelperImpl implements the listenerAttachmentHelper interface.
 type listenerAttachmentHelperImpl struct {
 	namespaceSelector namespaceSelector
 }
 
+// listenerAllowsAttachment utility method to determine if a listener will allow a route to connect using
+// Gateway API rules to determine compatibility between lister and route.
 func (attachmentHelper *listenerAttachmentHelperImpl) listenerAllowsAttachment(ctx context.Context, gw gwv1.Gateway, listener gwv1.Listener, route preLoadRouteDescriptor) (bool, error) {
 	namespaceOK, err := attachmentHelper.namespaceCheck(ctx, gw, listener, route)
 	if err != nil {
 		return false, err
 	}
 
 	if !namespaceOK {
-		fmt.Printf("name ok is false\n")
 		return false, nil
 	}
 
 	if !attachmentHelper.kindCheck(listener, route) {
-		fmt.Printf("kind ok is false\n")
 		return false, nil
 	}
 	return true, nil
 }
 
+// namespaceCheck namespace check implements the Gateway API spec for namespace matching between listener
+// and route to determine compatibility.
 func (attachmentHelper *listenerAttachmentHelperImpl) namespaceCheck(ctx context.Context, gw gwv1.Gateway, listener gwv1.Listener, route preLoadRouteDescriptor) (bool, error) {
 	var allowedNamespaces gwv1.FromNamespaces
 
@@ -71,6 +75,8 @@ func (attachmentHelper *listenerAttachmentHelperImpl) namespaceCheck(ctx context
 	}
 }
 
+// kindCheck kind check implements the Gateway API spec for kindCheck matching between listener
+// and route to determine compatibility.
 func (attachmentHelper *listenerAttachmentHelperImpl) kindCheck(listener gwv1.Listener, route preLoadRouteDescriptor) bool {
 
 	var allowedRoutes sets.Set[string]

pkg/gateway/routeutils/loader.go

@@ -8,10 +8,12 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// LoadRouteFilter is an interface that consumers can use to tell the loader which routes to load.
 type LoadRouteFilter interface {
 	IsApplicable(kind string) bool
 }
 
+// routeFilterImpl implements LoadRouteFilter
 type routeFilterImpl struct {
 	acceptedKinds sets.Set[string]
 }
@@ -41,18 +43,21 @@ var L7RouteFilter LoadRouteFilter = &routeFilterImpl{
 	acceptedKinds: sets.New(HTTPRouteKind, GRPCRouteKind),
 }
 
+// Loader will load all data Kubernetes that are pertinent to a gateway (Routes, Services, Target Group Configurations).
+// It will output the data using a map which maps listener port to the various routing rules for that port.
 type Loader interface {
 	LoadRoutesForGateway(ctx context.Context, gw gwv1.Gateway, filter LoadRouteFilter) (map[int][]RouteDescriptor, error)
 }
 
 var _ Loader = &loaderImpl{}
 
 type loaderImpl struct {
-	mapper          ListenerToRouteMapper
+	mapper          listenerToRouteMapper
 	k8sClient       client.Client
 	allRouteLoaders map[string]func(context context.Context, client client.Client) ([]preLoadRouteDescriptor, error)
 }
 
+// LoadRoutesForGateway loads all relevant data for a single Gateway.
 func (l *loaderImpl) LoadRoutesForGateway(ctx context.Context, gw gwv1.Gateway, filter LoadRouteFilter) (map[int][]RouteDescriptor, error) {
 	// 1. Load all relevant routes according to the filter
 	loadedRoutes := make([]preLoadRouteDescriptor, 0)
@@ -68,7 +73,7 @@ func (l *loaderImpl) LoadRoutesForGateway(ctx context.Context, gw gwv1.Gateway,
 
 	// 2. Remove routes that aren't granted attachment by the listener.
 	// Map any routes that are granted attachment to the listener port that allows the attachment.
-	mappedRoutes, err := l.mapper.Map(ctx, gw, loadedRoutes)
+	mappedRoutes, err := l.mapper.mapGatewayAndRoutes(ctx, gw, loadedRoutes)
 	if err != nil {
 		return nil, err
 	}
@@ -77,6 +82,7 @@ func (l *loaderImpl) LoadRoutesForGateway(ctx context.Context, gw gwv1.Gateway,
 	return l.loadChildResources(ctx, mappedRoutes)
 }
 
+// loadChildResources responsible for loading all resources that a route descriptor references.
 func (l *loaderImpl) loadChildResources(ctx context.Context, preloadedRoutes map[int][]preLoadRouteDescriptor) (map[int][]RouteDescriptor, error) {
 	// Cache to reduce duplicate route look ups.
 	// Kind -> [NamespacedName:Previously Loaded Descriptor]

pkg/gateway/routeutils/loader_test.go

@@ -16,7 +16,7 @@ type mockMapper struct {
 	mapToReturn    map[int][]preLoadRouteDescriptor
 }
 
-func (m *mockMapper) Map(context context.Context, gw gwv1.Gateway, routes []preLoadRouteDescriptor) (map[int][]preLoadRouteDescriptor, error) {
+func (m *mockMapper) mapGatewayAndRoutes(context context.Context, gw gwv1.Gateway, routes []preLoadRouteDescriptor) (map[int][]preLoadRouteDescriptor, error) {
 	assert.ElementsMatch(m.t, m.expectedRoutes, routes)
 	return m.mapToReturn, nil
 }

pkg/gateway/routeutils/namespace_selector.go

@@ -8,6 +8,9 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
+// namespaceSelector is an internal utility
+// that is responsible for transforming a label selector into the all relevant namespaces
+// that match the selector criteria.
 type namespaceSelector interface {
 	getNamespacesFromSelector(context context.Context, selector *metav1.LabelSelector) (sets.Set[string], error)
 }
@@ -18,6 +21,7 @@ type namespaceSelectorImpl struct {
 	k8sClient client.Client
 }
 
+// getNamespacesFromSelector queries the Kubernetes API for all namespaces that match a selector.
 func (n *namespaceSelectorImpl) getNamespacesFromSelector(context context.Context, selector *metav1.LabelSelector) (sets.Set[string], error) {
 	namespaceList := v1.NamespaceList{}
 

pkg/gateway/routeutils/route_attachment_helper.go

@@ -4,6 +4,7 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// routeAttachmentHelper is an internal utility that is responsible for providing functionality related to route filtering.
 type routeAttachmentHelper interface {
 	doesRouteAttachToGateway(gw gwv1.Gateway, route preLoadRouteDescriptor) bool
 	routeAllowsAttachmentToListener(listener gwv1.Listener, route preLoadRouteDescriptor) bool
@@ -14,6 +15,8 @@ var _ routeAttachmentHelper = &routeAttachmentHelperImpl{}
 type routeAttachmentHelperImpl struct {
 }
 
+// doesRouteAttachToGateway is responsible for determining if a route and gateway should be connected.
+// This function implements the Gateway API spec for determining Gateway -> Route attachment.
 func (rah *routeAttachmentHelperImpl) doesRouteAttachToGateway(gw gwv1.Gateway, route preLoadRouteDescriptor) bool {
 	for _, parentRef := range route.GetParentRefs() {
 
@@ -38,6 +41,10 @@ func (rah *routeAttachmentHelperImpl) doesRouteAttachToGateway(gw gwv1.Gateway,
 	return false
 }
 
+// routeAllowsAttachmentToListener is responsible for determining if a route and listener should be connected. This function is slightly different than
+// listenerAttachmentHelper as it handles listener -> route relationships. This utility handles route -> listener relationships.
+// In order for a relationship to be established, both listener and route must agree to the connection.
+// This function implements the Gateway API spec for route -> listener attachment.
 // This function assumes that the caller has already validated that the gateway that owns the listener allows for route
 // attachment.
 func (rah *routeAttachmentHelperImpl) routeAllowsAttachmentToListener(listener gwv1.Listener, route preLoadRouteDescriptor) bool {

pkg/gateway/routeutils/route_listener_mapper.go

@@ -5,31 +5,37 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
-type ListenerToRouteMapper interface {
-	Map(context context.Context, gw gwv1.Gateway, routes []preLoadRouteDescriptor) (map[int][]preLoadRouteDescriptor, error)
+// listenerToRouteMapper is an internal utility that will map a list of routes to the listeners of a gateway
+// if the gateway and/or route are incompatible, then route is discarded.
+type listenerToRouteMapper interface {
+	mapGatewayAndRoutes(context context.Context, gw gwv1.Gateway, routes []preLoadRouteDescriptor) (map[int][]preLoadRouteDescriptor, error)
 }
 
-var _ ListenerToRouteMapper = &listenerToRouteMapperImpl{}
+var _ listenerToRouteMapper = &listenerToRouteMapperImpl{}
 
 type listenerToRouteMapperImpl struct {
 	listenerAttachmentHelper listenerAttachmentHelper
 	routeAttachmentHelper    routeAttachmentHelper
 }
 
-func (ltr *listenerToRouteMapperImpl) Map(ctx context.Context, gw gwv1.Gateway, routes []preLoadRouteDescriptor) (map[int][]preLoadRouteDescriptor, error) {
+// mapGatewayAndRoutes will map route to the corresponding listener ports using the Gateway API spec rules.
+func (ltr *listenerToRouteMapperImpl) mapGatewayAndRoutes(ctx context.Context, gw gwv1.Gateway, routes []preLoadRouteDescriptor) (map[int][]preLoadRouteDescriptor, error) {
 	result := make(map[int][]preLoadRouteDescriptor)
 
+	// First filter out any routes that are not intended for this Gateway.
 	routesForGateway := make([]preLoadRouteDescriptor, 0)
 	for _, route := range routes {
 		if ltr.routeAttachmentHelper.doesRouteAttachToGateway(gw, route) {
 			routesForGateway = append(routesForGateway, route)
 		}
 	}
 
-	// Approach is to greedily add as many relevant routes to each listener.
+	// Next, greedily looking for the route to attach to.
 	for _, listener := range gw.Spec.Listeners {
 		for _, route := range routesForGateway {
 
+			// We need to check both paths (route -> listener) and (listener -> route)
+			// for connection viability.
 			if !ltr.routeAttachmentHelper.routeAllowsAttachmentToListener(listener, route) {
 				continue
 			}

pkg/gateway/routeutils/route_listener_mapper_test.go

@@ -43,7 +43,7 @@ func (m *mockRouteAttachmentHelper) routeAllowsAttachmentToListener(listener gwv
 	return m.routeListenerMap[k]
 }
 
-func Test_Map(t *testing.T) {
+func Test_mapGatewayAndRoutes(t *testing.T) {
 
 	route1 := convertHTTPRoute(gwv1.HTTPRoute{
 		ObjectMeta: metav1.ObjectMeta{
@@ -311,7 +311,7 @@ func Test_Map(t *testing.T) {
 				},
 			}
 
-			result, err := mapper.Map(context.Background(), tc.gw, tc.routes)
+			result, err := mapper.mapGatewayAndRoutes(context.Background(), tc.gw, tc.routes)
 
 			if tc.expectErr {
 				assert.Error(t, err)

pkg/gateway/routeutils/route_rule.go

@@ -4,6 +4,7 @@ import (
 	gwv1 "sigs.k8s.io/gateway-api/apis/v1"
 )
 
+// RouteRule is a type agnostic representation of Routing Rules.
 type RouteRule interface {
 	GetRawRouteRule() interface{}
 	GetSectionName() *gwv1.SectionName

pkg/gateway/routeutils/tcp.go

@@ -9,6 +9,12 @@ import (
 	gwalpha2 "sigs.k8s.io/gateway-api/apis/v1alpha2"
 )
 
+/*
+This class holds the representation of an TCP route.
+Generally, outside consumers will use GetRawRouteRule to inspect the
+TCP specific features of the route.
+*/
+
 /* Route Rule */
 
 var _ RouteRule = &convertedTCPRouteRule{}

pkg/gateway/routeutils/tls.go

@@ -9,6 +9,12 @@ import (
 	gwalpha2 "sigs.k8s.io/gateway-api/apis/v1alpha2"
 )
 
+/*
+This class holds the representation of an TLS route.
+Generally, outside consumers will use GetRawRouteRule to inspect the
+TLS specific features of the route.
+*/
+
 /* Route Rule */
 
 var _ RouteRule = &convertedTLSRouteRule{}

pkg/gateway/routeutils/udp.go

@@ -9,6 +9,12 @@ import (
 	gwalpha2 "sigs.k8s.io/gateway-api/apis/v1alpha2"
 )
 
+/*
+This class holds the representation of an UDP route.
+Generally, outside consumers will use GetRawRouteRule to inspect the
+UDP specific features of the route.
+*/
+
 /* Route Rule */
 
 var _ RouteRule = &convertedUDPRouteRule{}