types

Documentation

Index

• Variables
• type Callbacks
• type CallbacksStruct
  • func (c CallbacksStruct) GetEffectiveConfig(ctx context.Context) (*protobufs.EffectiveConfig, error)
  • func (c CallbacksStruct) OnCommand(ctx context.Context, command *protobufs.ServerToAgentCommand) error
  • func (c CallbacksStruct) OnConnect(ctx context.Context)
  • func (c CallbacksStruct) OnConnectFailed(ctx context.Context, err error)
  • func (c CallbacksStruct) OnError(ctx context.Context, err *protobufs.ServerErrorResponse)
  • func (c CallbacksStruct) OnMessage(ctx context.Context, msg *MessageData)
  • func (c CallbacksStruct) OnOpampConnectionSettings(ctx context.Context, settings *protobufs.OpAMPConnectionSettings) error
  • func (c CallbacksStruct) SaveRemoteConfigStatus(ctx context.Context, status *protobufs.RemoteConfigStatus)
• type InstanceUid
• type Logger
• type MessageData
• type PackageState
• type PackagesStateProvider
• type PackagesSyncer
• type StartSettings

Variables

var (
	// ErrCustomMessageMissing is returned by SendCustomMessage when called with a nil message.
	ErrCustomMessageMissing = errors.New("CustomMessage is nil")

	// ErrCustomCapabilityNotSupported is returned by SendCustomMessage when called with
	// message that has a capability that is not specified as supported by the client.
	ErrCustomCapabilityNotSupported = errors.New("CustomCapability of CustomMessage is not supported")

	// ErrCustomMessagePending is returned by SendCustomMessage when called before the previous
	// message has been sent.
	ErrCustomMessagePending = errors.New("custom message already set")
)

Types

type Callbacks

type Callbacks interface {
	// OnConnect is called when the connection is successfully established to the Server.
	// May be called after Start() is called and every time a connection is established to the Server.
	// For WebSocket clients this is called after the handshake is completed without any error.
	// For HTTP clients this is called for any request if the response status is OK.
	OnConnect(ctx context.Context)

	// OnConnectFailed is called when the connection to the Server cannot be established.
	// May be called after Start() is called and tries to connect to the Server.
	// May also be called if the connection is lost and reconnection attempt fails.
	OnConnectFailed(ctx context.Context, err error)

	// OnError is called when the Server reports an error in response to some previously
	// sent request. Useful for logging purposes. The Agent should not attempt to process
	// the error by reconnecting or retrying previous operations. The client handles the
	// ErrorResponse_UNAVAILABLE case internally by performing retries as necessary.
	OnError(ctx context.Context, err *protobufs.ServerErrorResponse)

	// OnMessage is called when the Agent receives a message that needs processing.
	// See MessageData definition for the data that may be available for processing.
	// During OnMessage execution the OpAMPClient functions that change the status
	// of the client may be called, e.g. if RemoteConfig is processed then
	// SetRemoteConfigStatus should be called to reflect the processing result.
	// These functions may also be called after OnMessage returns. This is advisable
	// if processing can take a long time. In that case returning quickly is preferable
	// to avoid blocking the OpAMPClient.
	OnMessage(ctx context.Context, msg *MessageData)

	// OnOpampConnectionSettings is called when the Agent receives an OpAMP
	// connection settings offer from the Server. Typically, the settings can specify
	// authorization headers or TLS certificate, potentially also a different
	// OpAMP destination to work with.
	//
	// The Agent should process the offer by reconnecting the client using the new
	// settings or return an error if the Agent does not want to accept the settings
	// (e.g. if the TSL certificate in the settings cannot be verified).
	//
	// Only one OnOpampConnectionSettings call can be active at any time.
	// See OnRemoteConfig for the behavior.
	OnOpampConnectionSettings(
		ctx context.Context,
		settings *protobufs.OpAMPConnectionSettings,
	) error

	// SaveRemoteConfigStatus is called after OnRemoteConfig returns. The status
	// will be set either as APPLIED or FAILED depending on whether OnRemoteConfig
	// returned a success or error.
	// The Agent must remember this RemoteConfigStatus and supply in the future
	// calls to Start() in StartSettings.RemoteConfigStatus.
	SaveRemoteConfigStatus(ctx context.Context, status *protobufs.RemoteConfigStatus)

	// GetEffectiveConfig returns the current effective config. Only one
	// GetEffectiveConfig call can be active at any time. Until GetEffectiveConfig
	// returns it will not be called again.
	GetEffectiveConfig(ctx context.Context) (*protobufs.EffectiveConfig, error)

	// OnCommand is called when the Server requests that the connected Agent perform a command.
	OnCommand(ctx context.Context, command *protobufs.ServerToAgentCommand) error
}

Callbacks is an interface for the Client to handle messages from the Server. Callbacks are expected to honour the context passed to them, meaning they should be aware of cancellations.

type CallbacksStruct

type CallbacksStruct struct {
	OnConnectFunc       func(ctx context.Context)
	OnConnectFailedFunc func(ctx context.Context, err error)
	OnErrorFunc         func(ctx context.Context, err *protobufs.ServerErrorResponse)

	OnMessageFunc func(ctx context.Context, msg *MessageData)

	OnOpampConnectionSettingsFunc func(
		ctx context.Context,
		settings *protobufs.OpAMPConnectionSettings,
	) error

	OnCommandFunc func(ctx context.Context, command *protobufs.ServerToAgentCommand) error

	SaveRemoteConfigStatusFunc func(ctx context.Context, status *protobufs.RemoteConfigStatus)
	GetEffectiveConfigFunc     func(ctx context.Context) (*protobufs.EffectiveConfig, error)
}

CallbacksStruct is a struct that implements Callbacks interface and allows to override only the methods that are needed. If a method is not overridden then it is a no-op.

func (CallbacksStruct) GetEffectiveConfig

func (c CallbacksStruct) GetEffectiveConfig(ctx context.Context) (*protobufs.EffectiveConfig, error)

GetEffectiveConfig implements Callbacks.GetEffectiveConfig.

func (CallbacksStruct) OnCommand

func (c CallbacksStruct) OnCommand(ctx context.Context, command *protobufs.ServerToAgentCommand) error

OnCommand implements Callbacks.OnCommand.

func (CallbacksStruct) OnConnect

func (c CallbacksStruct) OnConnect(ctx context.Context)

OnConnect implements Callbacks.OnConnect.

func (CallbacksStruct) OnConnectFailed

func (c CallbacksStruct) OnConnectFailed(ctx context.Context, err error)

OnConnectFailed implements Callbacks.OnConnectFailed.

func (CallbacksStruct) OnError

func (c CallbacksStruct) OnError(ctx context.Context, err *protobufs.ServerErrorResponse)

OnError implements Callbacks.OnError.

func (CallbacksStruct) OnMessage

func (c CallbacksStruct) OnMessage(ctx context.Context, msg *MessageData)

OnMessage implements Callbacks.OnMessage.

func (CallbacksStruct) OnOpampConnectionSettings

func (c CallbacksStruct) OnOpampConnectionSettings(
	ctx context.Context, settings *protobufs.OpAMPConnectionSettings,
) error

OnOpampConnectionSettings implements Callbacks.OnOpampConnectionSettings.

func (CallbacksStruct) SaveRemoteConfigStatus

func (c CallbacksStruct) SaveRemoteConfigStatus(ctx context.Context, status *protobufs.RemoteConfigStatus)

SaveRemoteConfigStatus implements Callbacks.SaveRemoteConfigStatus.

type InstanceUid

type InstanceUid [16]byte

type Logger

type Logger interface {
	Debugf(ctx context.Context, format string, v ...interface{})
	Errorf(ctx context.Context, format string, v ...interface{})
}

Logger is the logging interface used by the OpAMP Client.

type MessageData

type MessageData struct {
	// RemoteConfig is offered by the Server. The Agent must process it and call
	// OpAMPClient.SetRemoteConfigStatus to indicate success or failure. If the
	// effective config has changed as a result of processing the Agent must also call
	// OpAMPClient.UpdateEffectiveConfig. SetRemoteConfigStatus and UpdateEffectiveConfig
	// may be called from OnMessage handler or after OnMessage returns.
	RemoteConfig *protobufs.AgentRemoteConfig

	// Connection settings are offered by the Server. These fields should be processed
	// as described in the ConnectionSettingsOffers message.
	OwnMetricsConnSettings *protobufs.TelemetryConnectionSettings
	OwnTracesConnSettings  *protobufs.TelemetryConnectionSettings
	OwnLogsConnSettings    *protobufs.TelemetryConnectionSettings
	OtherConnSettings      map[string]*protobufs.OtherConnectionSettings

	// PackagesAvailable offered by the Server. The Agent must process the offer.
	// The typical way to process is to call PackageSyncer.Sync() function, which will
	// take care of reporting the status to the Server as processing happens.
	//
	// If PackageSyncer.Sync() function is not called then it is the responsibility of
	// OnMessage handler to do the processing and call OpAMPClient.SetPackageStatuses to
	// reflect the processing status. SetPackageStatuses may be called from OnMessage
	// handler or after OnMessage returns.
	PackagesAvailable *protobufs.PackagesAvailable
	PackageSyncer     PackagesSyncer

	// AgentIdentification indicates a new identification received from the Server.
	// The Agent must save this identification and use it in the future instantiations
	// of OpAMPClient.
	AgentIdentification *protobufs.AgentIdentification

	// CustomCapabilities contains a list of custom capabilities that are supported by the
	// server.
	CustomCapabilities *protobufs.CustomCapabilities

	// CustomMessage contains a custom message sent by the server.
	CustomMessage *protobufs.CustomMessage
}

MessageData represents a message received from the server and handled by Callbacks.

type PackageState

type PackageState struct {
	// Exists indicates that the package exists locally. The rest of the fields
	// must be ignored if this field is false.
	Exists bool

	Type    protobufs.PackageType
	Hash    []byte
	Version string
}

PackageState represents the state of a package in the Agent's local storage.

type PackagesStateProvider

type PackagesStateProvider interface {
	// AllPackagesHash returns the hash of all packages previously set via SetAllPackagesHash().
	AllPackagesHash() ([]byte, error)

	// SetAllPackagesHash must remember the AllPackagesHash. Must be returned
	// later when AllPackagesHash is called. SetAllPackagesHash is called after all
	// package updates complete successfully.
	SetAllPackagesHash(hash []byte) error

	// Packages returns the names of all packages that exist in the Agent's local storage.
	Packages() ([]string, error)

	// PackageState returns the state of a local package. packageName is one of the names
	// that were returned by Packages().
	// Returns (PackageState{Exists:false},nil) if package does not exist locally.
	PackageState(packageName string) (state PackageState, err error)

	// SetPackageState must remember the state for the specified package. Must be returned
	// later when PackageState is called. SetPackageState is called after UpdateContent
	// call completes successfully.
	// The state.Type must be equal to the current Type of the package otherwise
	// the call may fail with an error.
	SetPackageState(packageName string, state PackageState) error

	// CreatePackage creates the package locally. If the package existed must return an error.
	// If the package did not exist its hash should be set to nil.
	CreatePackage(packageName string, typ protobufs.PackageType) error

	// FileContentHash returns the content hash of the package file that exists locally.
	// Returns (nil,nil) if package or package file is not found.
	FileContentHash(packageName string) ([]byte, error)

	// UpdateContent must create or update the package content file. The entire content
	// of the file must be replaced by the data. The data must be read until
	// it returns an EOF. If reading from data fails UpdateContent must abort and return
	// an error.
	// Content hash must be updated if the data is updated without failure.
	// The function must cancel and return an error if the context is cancelled.
	UpdateContent(ctx context.Context, packageName string, data io.Reader, contentHash, signature []byte) error

	// DeletePackage deletes the package from the Agent's local storage.
	DeletePackage(packageName string) error

	// LastReportedStatuses returns the value previously set via SetLastReportedStatuses.
	LastReportedStatuses() (*protobufs.PackageStatuses, error)

	// SetLastReportedStatuses saves the statuses in the local state. This is called
	// periodically during syncing process to save the most recent statuses.
	SetLastReportedStatuses(statuses *protobufs.PackageStatuses) error
}

PackagesStateProvider is an interface that is used by PackagesSyncer.Sync() to query and update the Agent's local state of packages. It is recommended that the local state is stored persistently so that after Agent restarts full state syncing is not required.

type PackagesSyncer

type PackagesSyncer interface {
	// Sync the available package from the Server to the Agent.
	// The Agent must supply an PackagesStateProvider in StartSettings to let the Sync
	// function know what is available locally, what data needs to be synced and how the
	// data can be stored locally.
	// Sync typically returns immediately and continues working in the background,
	// downloading the packages and applying the changes to the local state.
	// Sync should be called once only.
	Sync(ctx context.Context) error

	// Done returns a channel which is readable when the Sync is complete.
	Done() <-chan struct{}
}

PackagesSyncer can be used by the Agent to initiate syncing a package from the Server. The PackagesSyncer instance knows the right context: the particular OpAMPClient and the particular PackageAvailable message the OnPackageAvailable callback was called for.

type StartSettings

type StartSettings struct {

	// Server URL. MUST be set.
	OpAMPServerURL string

	// Optional additional HTTP headers to send with all HTTP requests.
	Header http.Header

	// Optional function that can be used to modify the HTTP headers
	// before each HTTP request.
	// Can modify and return the argument or return the argument without modifying.
	HeaderFunc func(http.Header) http.Header

	// Optional TLS config for HTTP connection.
	TLSConfig *tls.Config

	// Agent information.
	InstanceUid InstanceUid

	// Callbacks that the client will call after Start() returns nil.
	Callbacks Callbacks

	// The remote config status. If nil is passed it will force
	// the Server to send a remote config back.
	RemoteConfigStatus *protobufs.RemoteConfigStatus

	LastConnectionSettingsHash []byte

	// PackagesStateProvider provides access to the local state of packages.
	// If nil then ReportsPackageStatuses and AcceptsPackages capabilities will be disabled,
	// i.e. package status reporting and syncing from the Server will be disabled.
	PackagesStateProvider PackagesStateProvider

	// Defines the capabilities of the Agent. AgentCapabilities_ReportsStatus bit does not need to
	// be set in this field, it will be set automatically since it is required by OpAMP protocol.
	Capabilities protobufs.AgentCapabilities

	// EnableCompression can be set to true to enable the compression. Note that for WebSocket transport
	// the compression is only effectively enabled if the Server also supports compression.
	// The data will be compressed in both directions.
	EnableCompression bool
}

StartSettings defines the parameters for starting the OpAMP Client.