Middleware: config struct (part 2/4) (#12844)

**Description**

Adds the config struct from
#12842.

**Link to tracking issue**

Part of
#12603.

**Testing**

Yes. This PR introduces `extensionmiddlewaretest` helpers.

**Documentation**

Added.

---------

Co-authored-by: Bogdan Drutu <[email protected]>

Author: jmacd

.chloggen/middleware-struct.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: configmiddleware
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add configmiddleware struct.
+
+# One or more tracking issues or pull requests related to the change
+issues: [12603, 9591]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

.github/workflows/utils/cspell.json

@@ -192,6 +192,7 @@
       "extensionauthtest",
       "extensioncapabilities",
       "extensionmiddleware",
+      "extensionmiddlewaretest",
       "extensionhelper",
       "extensiontest",
       "extensionz",
@@ -269,6 +270,7 @@
       "lables",
       "lastest",
       "ldflags",
+      "limitermiddleware",
       "localhostgate",
       "loggingexporter",
       "logstest",

config/configmiddleware/Makefile

@@ -0,0 +1 @@
+include ../../Makefile.Common

config/configmiddleware/README.md

@@ -0,0 +1,37 @@
+# OpenTelemetry Collector Middleware Configuration
+
+This package implements a configuration struct for referring to
+[middleware extensions](../../extension/extensionmiddleware/README.md).
+
+## Overview
+
+The `configmiddleware` package defines a `Config` type that
+allows components to configure middleware extensions, typically as
+an ordered list.
+This support is built in for push-based receivers configured through
+`confighttp` and `configgrpc`, as for example in the OTLP receiver:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+	  http:
+	    middlewares:
+		- id: limitermiddleware
+```
+
+## Methods
+
+The package provides four key methods to retrieve appropriate middleware handlers:
+
+1. **GetHTTPClientRoundTripper**: Obtains a function to wrap an HTTP client with a middleware extension via a `http.RoundTripper`.
+
+2. **GetHTTPServerHandler**: Obtains a function to wrap an HTTP server with a middleware extension via a `http.Handler`.
+
+3. **GetGRPCClientOptions**: Obtains a `[]grpc.DialOption` that configure a middleware extension for gRPC clients.
+
+4. **GetGRPCServerOptions**: Obtains a `[]grpc.ServerOption` that configure a middleware extension for gRPC servers.
+
+These functions are typically called during Start() by a component,
+passing the `component.Host` extensions.
+An error is returned if the named extension cannot be found.

config/configmiddleware/configmiddleware.go

@@ -0,0 +1,92 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package configmiddleware implements a configuration struct to
+// name middleware extensions.
+package configmiddleware // import "go.opentelemetry.io/collector/config/configmiddleware"
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+
+	"google.golang.org/grpc"
+
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/extension/extensionmiddleware"
+)
+
+var (
+	errMiddlewareNotFound = errors.New("middleware not found")
+	errNotHTTPServer      = errors.New("requested extension is not an HTTP server middleware")
+	errNotGRPCServer      = errors.New("requested extension is not a gRPC server middleware")
+	errNotHTTPClient      = errors.New("requested extension is not an HTTP client middleware")
+	errNotGRPCClient      = errors.New("requested extension is not a gRPC client middleware")
+)
+
+// Middleware defines the extension ID for a middleware component.
+type Config struct {
+	// ID specifies the name of the extension to use.
+	ID component.ID `mapstructure:"id,omitempty"`
+}
+
+// GetHTTPClientRoundTripper attempts to select the appropriate
+// extensionmiddleware.HTTPClient from the map of extensions, and
+// returns the HTTP client wrapper function. If a middleware is not
+// found, an error is returned.  This should only be used by HTTP
+// clients.
+func (m Config) GetHTTPClientRoundTripper(_ context.Context, extensions map[component.ID]component.Component) (func(http.RoundTripper) (http.RoundTripper, error), error) {
+	if ext, found := extensions[m.ID]; found {
+		if client, ok := ext.(extensionmiddleware.HTTPClient); ok {
+			return client.GetHTTPRoundTripper, nil
+		}
+		return nil, errNotHTTPClient
+	}
+	return nil, fmt.Errorf("failed to resolve middleware %q: %w", m.ID, errMiddlewareNotFound)
+}
+
+// GetHTTPServerHandler attempts to select the appropriate
+// extensionmiddleware.HTTPServer from the map of extensions, and
+// returns the http.Handler wrapper function. If a middleware is not
+// found, an error is returned.  This should only be used by HTTP
+// servers.
+func (m Config) GetHTTPServerHandler(_ context.Context, extensions map[component.ID]component.Component) (func(http.Handler) (http.Handler, error), error) {
+	if ext, found := extensions[m.ID]; found {
+		if server, ok := ext.(extensionmiddleware.HTTPServer); ok {
+			return server.GetHTTPHandler, nil
+		}
+		return nil, errNotHTTPServer
+	}
+
+	return nil, fmt.Errorf("failed to resolve middleware %q: %w", m.ID, errMiddlewareNotFound)
+}
+
+// GetGRPCClientOptions attempts to select the appropriate
+// extensionmiddleware.GRPCClient from the map of extensions, and
+// returns the gRPC dial options. If a middleware is not found, an
+// error is returned.  This should only be used by gRPC clients.
+func (m Config) GetGRPCClientOptions(_ context.Context, extensions map[component.ID]component.Component) ([]grpc.DialOption, error) {
+	if ext, found := extensions[m.ID]; found {
+		if client, ok := ext.(extensionmiddleware.GRPCClient); ok {
+			return client.GetGRPCClientOptions()
+		}
+		return nil, errNotGRPCClient
+	}
+	return nil, fmt.Errorf("failed to resolve middleware %q: %w", m.ID, errMiddlewareNotFound)
+}
+
+// GetGRPCServerOptions attempts to select the appropriate
+// extensionmiddleware.GRPCServer from the map of extensions, and
+// returns the gRPC server options. If a middleware is not found, an
+// error is returned.  This should only be used by gRPC servers.
+func (m Config) GetGRPCServerOptions(_ context.Context, extensions map[component.ID]component.Component) ([]grpc.ServerOption, error) {
+	if ext, found := extensions[m.ID]; found {
+		if server, ok := ext.(extensionmiddleware.GRPCServer); ok {
+			return server.GetGRPCServerOptions()
+		}
+		return nil, errNotGRPCServer
+	}
+
+	return nil, fmt.Errorf("failed to resolve middleware %q: %w", m.ID, errMiddlewareNotFound)
+}