[opampextension]: Move custom message interface to separate module (o…

…pen-telemetry#32951)

**Description:** <Describe what has changed.>
* Breaks our the custom message interface to a separate module, so other
components can use the interface without needing to import the
`opampextension` module in its entirety.

We could temporarily alias the old methods if we'd like, but I think
that the CustomMessage stuff has been so short lived that, in addition
to the alpha status of the opampextension component, it feels justified
to just skip the deprecation process and move it to a new module.

**Link to tracking Issue:** Closes open-telemetry#32950

**Testing:**
* Covered by existing unit tests

**Documentation:**
* Added more documentation on usage in the new module.
* Modified opampextension docs to point to the new module.

.chloggen/chore_move-custom-messages.yaml

@@ -0,0 +1,29 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: breaking
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: opampextension
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Move custom message interfaces to separate package
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [32950]
+
+# (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: |
+  Moves `CustomCapabilityRegistry`, `CustomCapabilityHandler`, and `CustomCapabilityRegisterOption` to a new module.
+  These types can now be found in the new `github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages` module.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# 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: [api]

.github/CODEOWNERS

@@ -109,6 +109,7 @@ extension/observer/ecstaskobserver/                      @open-telemetry/collect
 extension/observer/hostobserver/                         @open-telemetry/collector-contrib-approvers @MovieStoreGuy
 extension/observer/k8sobserver/                          @open-telemetry/collector-contrib-approvers @rmfitzpatrick @dmitryax
 extension/oidcauthextension/                             @open-telemetry/collector-contrib-approvers @jpkrohling
+extension/opampcustommessages/                           @open-telemetry/collector-contrib-approvers @BinaryFissionGames @evan-bradley
 extension/opampextension/                                @open-telemetry/collector-contrib-approvers @portertech @evan-bradley @tigrannajaryan
 extension/pprofextension/                                @open-telemetry/collector-contrib-approvers @MovieStoreGuy
 extension/remotetapextension/                            @open-telemetry/collector-contrib-approvers @atoulme

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -109,6 +109,7 @@ body:
       - extension/observer/k8sobserver
       - extension/oidcauth
       - extension/opamp
+      - extension/opampcustommessages
       - extension/pprof
       - extension/remotetap
       - extension/sigv4auth

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -103,6 +103,7 @@ body:
       - extension/observer/k8sobserver
       - extension/oidcauth
       - extension/opamp
+      - extension/opampcustommessages
       - extension/pprof
       - extension/remotetap
       - extension/sigv4auth

.github/ISSUE_TEMPLATE/other.yaml

@@ -103,6 +103,7 @@ body:
       - extension/observer/k8sobserver
       - extension/oidcauth
       - extension/opamp
+      - extension/opampcustommessages
       - extension/pprof
       - extension/remotetap
       - extension/sigv4auth

.github/ISSUE_TEMPLATE/unmaintained.yaml

@@ -108,6 +108,7 @@ body:
       - extension/observer/k8sobserver
       - extension/oidcauth
       - extension/opamp
+      - extension/opampcustommessages
       - extension/pprof
       - extension/remotetap
       - extension/sigv4auth

cmd/checkapi/allowlist.txt

@@ -1 +1,2 @@
-extension/observer
+extension/observer
+extension/opampcustommessages

cmd/otelcontribcol/builder-config.yaml

@@ -460,3 +460,4 @@ replaces:
   - github.com/open-telemetry/opentelemetry-collector-contrib/extension/ackextension => ../../extension/ackextension
   - github.com/open-telemetry/opentelemetry-collector-contrib/extension/googleclientauthextension => ../../extension/googleclientauthextension
   - github.com/open-telemetry/opentelemetry-collector-contrib/receiver/splunkenterprisereceiver => ../../receiver/splunkenterprisereceiver
+  - github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages => ../../extension/opampcustommessages

cmd/otelcontribcol/go.mod

@@ -601,6 +601,7 @@ require (
 	github.com/open-telemetry/opamp-go v0.14.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding v0.100.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer v0.100.0 // indirect
+	github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages v0.0.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/aws/awsutil v0.100.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/aws/containerinsight v0.100.0 // indirect
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/aws/cwlogs v0.100.0 // indirect
@@ -1284,3 +1285,5 @@ replace github.com/open-telemetry/opentelemetry-collector-contrib/extension/acke
 replace github.com/open-telemetry/opentelemetry-collector-contrib/extension/googleclientauthextension => ../../extension/googleclientauthextension
 
 replace github.com/open-telemetry/opentelemetry-collector-contrib/receiver/splunkenterprisereceiver => ../../receiver/splunkenterprisereceiver
+
+replace github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages => ../../extension/opampcustommessages

extension/opampcustommessages/Makefile

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

extension/opampcustommessages/README.md

@@ -0,0 +1,81 @@
+# extension/opampcustommessages
+
+## Overview
+
+This modules contains interfaces and shared code for sending and receiving [custom messages](https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#custom-messages) via OpAMP.
+
+## Usage
+
+An extension may implement the `opampcustommessages.CustomCapabilityRegistry` interface, which allows other components to register capabilities to send and receive messages to/from an OpAMP server. For an example of a component implementing this interface, see the [OpAMP extension](../opampextension/README.md).
+
+
+### Registering a custom capability
+
+Other components may use a configured OpAMP extension to send and receive custom messages to and from an OpAMP server. Components may use the provided `components.Host` from the Start method in order to get a handle to the registry:
+
+```go
+func Start(_ context.Context, host component.Host) error {
+	ext, ok := host.GetExtensions()[opampExtensionID]
+	if !ok {
+		return fmt.Errorf("extension %q does not exist", opampExtensionID)
+	}
+
+	registry, ok := ext.(opampcustommessages.CustomCapabilityRegistry)
+	if !ok {
+		return fmt.Errorf("extension %q is not a custom message registry", opampExtensionID)
+	}
+
+	handler, err := registry.Register("io.opentelemetry.custom-capability")
+	if err != nil {
+		return fmt.Errorf("failed to register custom capability: %w", err)
+	}
+
+	// ... send/receive messages using the given handler
+
+	return nil
+}
+```
+
+### Using a CustomCapabilityHandler to send/receive messages
+
+After obtaining a handler for the custom capability, you can send and receive messages for the custom capability by using the SendMessage and Message methods, respectively:
+
+#### Sending a message
+
+To send a message, you can use the SendMessage method. Since only one custom message can be scheduled to send at a time, the error returned should be checked if it's [ErrCustomMessagePending](https://pkg.go.dev/github.com/open-telemetry/[email protected]/client/types#pkg-variables), and wait on the returned channel to attempt sending the message again.
+
+```go
+for {
+	sendingChan, err := handler.SendMessage("messageType", []byte("message-data"))
+	switch {
+	case err == nil:
+		break
+	case errors.Is(err, types.ErrCustomMessagePending):
+		<-sendingChan
+		continue
+	default:
+		return fmt.Errorf("failed to send message: %w", err)
+	}
+}
+```
+
+#### Receiving a message
+
+Messages can be received through the channel returned by the `Message` method on the handler:
+
+```go
+msg := <-handler.Message()
+// process the message...
+```
+
+Components receiving messages should take care not to modify the received message, as the message may be shared between multiple components.
+
+### Unregistering a capability
+
+After a component is done processing messages for a given capability, or shuts down, it should unregister its handler. You can do this by calling the `Unregister` method:
+
+```go
+handler.Unregister()
+```
+
+After a handler has been unregistered, it will no longer receive any messages from the OpAMP server, and any further calls to SendMessage will reject the message and return an error.

extension/opampextension/custom_messages.go → extension/opampcustommessages/custom_messages.go

@@ -1,29 +1,30 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-package opampextension // import "github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampextension"
+// Package opampcustommessages contains interfaces and shared code for sending and receiving custom messages via OpAMP.
+package opampcustommessages // import "github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages"
 
 import "github.com/open-telemetry/opamp-go/protobufs"
 
-// customCapabilityRegisterOptions represents extra options that can be use in CustomCapabilityRegistry.Register
-type customCapabilityRegisterOptions struct {
+// CustomCapabilityRegisterOptions represents extra options that can be use in CustomCapabilityRegistry.Register
+type CustomCapabilityRegisterOptions struct {
 	MaxQueuedMessages int
 }
 
-// defaultCustomCapabilityRegisterOptions returns the default options for CustomCapabilityRegisterOptions
-func defaultCustomCapabilityRegisterOptions() *customCapabilityRegisterOptions {
-	return &customCapabilityRegisterOptions{
+// DefaultCustomCapabilityRegisterOptions returns the default options for CustomCapabilityRegisterOptions
+func DefaultCustomCapabilityRegisterOptions() *CustomCapabilityRegisterOptions {
+	return &CustomCapabilityRegisterOptions{
 		MaxQueuedMessages: 10,
 	}
 }
 
 // CustomCapabilityRegisterOption represent a single option for CustomCapabilityRegistry.Register
-type CustomCapabilityRegisterOption func(*customCapabilityRegisterOptions)
+type CustomCapabilityRegisterOption func(*CustomCapabilityRegisterOptions)
 
-// withMaxQueuedMessages overrides the maximum number of queued messages. If a message is received while
+// WithMaxQueuedMessages overrides the maximum number of queued messages. If a message is received while
 // MaxQueuedMessages messages are already queued to be processed, the message is dropped.
-func withMaxQueuedMessages(maxQueuedMessages int) CustomCapabilityRegisterOption {
-	return func(c *customCapabilityRegisterOptions) {
+func WithMaxQueuedMessages(maxQueuedMessages int) CustomCapabilityRegisterOption {
+	return func(c *CustomCapabilityRegisterOptions) {
 		c.MaxQueuedMessages = maxQueuedMessages
 	}
 }

extension/opampcustommessages/go.mod

@@ -0,0 +1,7 @@
+module github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages
+
+go 1.21.0
+
+require github.com/open-telemetry/opamp-go v0.14.0
+
+require google.golang.org/protobuf v1.33.0 // indirect

extension/opampcustommessages/metadata.yaml

@@ -0,0 +1,3 @@
+status:
+  codeowners:
+    active: [BinaryFissionGames, evan-bradley]

extension/opampextension/README.md

@@ -47,27 +47,9 @@ extensions:
 
 ## Custom Messages
 
-Other components may use a configured OpAMP extension to send and receive custom messages to and from an OpAMP server. Components may use the provided `components.Host` from the Start method in order to get a handle to the registry:
+Other components may use a configured OpAMP extension to send and receive custom messages to and from an OpAMP server.
 
-```go
-func Start(_ context.Context, host component.Host) error {
-	ext, ok := host.GetExtensions()[opampExtensionID]
-	if !ok {
-		return fmt.Errorf("opamp extension %q does not exist", opampExtensionID)
-	}
-
-	registry, ok := ext.(opampextension.CustomCapabilityRegistry)
-	if !ok {
-		return fmt.Errorf("extension %q is not a custom message registry", opampExtensionID)
-	}
-
-	// You can now use registry.Register to register a custom capability
-
-	return nil
-}
-```
-
-See the [custom_messages.go](./custom_messages.go) for more information on the custom message API.
+See the [opampcustommessages](../opampcustommessages/README.md) module for more information on the custom message API.
 
 ## Status
 

extension/opampextension/go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/oklog/ulid/v2 v2.1.0
 	github.com/open-telemetry/opamp-go v0.14.0
+	github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages v0.0.0
 	github.com/shirou/gopsutil/v3 v3.24.4
 	github.com/stretchr/testify v1.9.0
 	go.opentelemetry.io/collector/component v0.100.0
@@ -65,3 +66,5 @@ require (
 	google.golang.org/grpc v1.63.2 // indirect
 	google.golang.org/protobuf v1.34.0 // indirect
 )
+
+replace github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages => ../opampcustommessages

extension/opampextension/opamp_agent.go

@@ -24,6 +24,8 @@ import (
 	"go.uber.org/zap"
 	"golang.org/x/exp/maps"
 	"gopkg.in/yaml.v3"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages"
 )
 
 type opampAgent struct {
@@ -53,7 +55,7 @@ type opampAgent struct {
 	customCapabilityRegistry *customCapabilityRegistry
 }
 
-var _ CustomCapabilityRegistry = (*opampAgent)(nil)
+var _ opampcustommessages.CustomCapabilityRegistry = (*opampAgent)(nil)
 
 func (o *opampAgent) Start(ctx context.Context, _ component.Host) error {
 	header := http.Header{}
@@ -141,7 +143,7 @@ func (o *opampAgent) NotifyConfig(ctx context.Context, conf *confmap.Conf) error
 	return nil
 }
 
-func (o *opampAgent) Register(capability string, opts ...CustomCapabilityRegisterOption) (CustomCapabilityHandler, error) {
+func (o *opampAgent) Register(capability string, opts ...opampcustommessages.CustomCapabilityRegisterOption) (opampcustommessages.CustomCapabilityHandler, error) {
 	return o.customCapabilityRegistry.Register(capability, opts...)
 }
 

extension/opampextension/registry.go

@@ -13,6 +13,8 @@ import (
 	"github.com/open-telemetry/opamp-go/protobufs"
 	"go.uber.org/zap"
 	"golang.org/x/exp/maps"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages"
 )
 
 // customCapabilityClient is a subset of OpAMP client containing only the methods needed for the customCapabilityRegistry.
@@ -28,7 +30,7 @@ type customCapabilityRegistry struct {
 	logger                  *zap.Logger
 }
 
-var _ CustomCapabilityRegistry = (*customCapabilityRegistry)(nil)
+var _ opampcustommessages.CustomCapabilityRegistry = (*customCapabilityRegistry)(nil)
 
 func newCustomCapabilityRegistry(logger *zap.Logger, client customCapabilityClient) *customCapabilityRegistry {
 	return &customCapabilityRegistry{
@@ -40,8 +42,8 @@ func newCustomCapabilityRegistry(logger *zap.Logger, client customCapabilityClie
 }
 
 // Register implements CustomCapabilityRegistry.Register
-func (cr *customCapabilityRegistry) Register(capability string, opts ...CustomCapabilityRegisterOption) (CustomCapabilityHandler, error) {
-	optsStruct := defaultCustomCapabilityRegisterOptions()
+func (cr *customCapabilityRegistry) Register(capability string, opts ...opampcustommessages.CustomCapabilityRegisterOption) (opampcustommessages.CustomCapabilityHandler, error) {
+	optsStruct := opampcustommessages.DefaultCustomCapabilityRegisterOptions()
 	for _, opt := range opts {
 		opt(optsStruct)
 	}
@@ -151,7 +153,7 @@ type customMessageHandler struct {
 	unregistered bool
 }
 
-var _ CustomCapabilityHandler = (*customMessageHandler)(nil)
+var _ opampcustommessages.CustomCapabilityHandler = (*customMessageHandler)(nil)
 
 func newCustomMessageHandler(
 	registry *customCapabilityRegistry,

extension/opampextension/registry_test.go

@@ -11,6 +11,8 @@ import (
 	"github.com/open-telemetry/opamp-go/protobufs"
 	"github.com/stretchr/testify/require"
 	"go.uber.org/zap"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages"
 )
 
 func TestRegistry_Register(t *testing.T) {
@@ -92,7 +94,7 @@ func TestRegistry_ProcessMessage(t *testing.T) {
 
 		registry := newCustomCapabilityRegistry(zap.NewNop(), client)
 
-		sender, err := registry.Register(capabilityString, withMaxQueuedMessages(0))
+		sender, err := registry.Register(capabilityString, opampcustommessages.WithMaxQueuedMessages(0))
 		require.NotNil(t, sender)
 		require.NoError(t, err)
 

versions.yaml

@@ -97,6 +97,7 @@ module-sets:
       - github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/hostobserver
       - github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/k8sobserver
       - github.com/open-telemetry/opentelemetry-collector-contrib/extension/oidcauthextension
+      - github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampcustommessages
       - github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampextension
       - github.com/open-telemetry/opentelemetry-collector-contrib/extension/pprofextension
       - github.com/open-telemetry/opentelemetry-collector-contrib/extension/remotetapextension