types

Documentation

Index

• type Callbacks
• type CallbacksStruct
  • func (c CallbacksStruct) GetEffectiveConfig(ctx context.Context) (*protobufs.EffectiveConfig, error)
  • func (c CallbacksStruct) OnCommand(command *protobufs.ServerToAgentCommand) error
  • func (c CallbacksStruct) OnConnect()
  • func (c CallbacksStruct) OnConnectFailed(err error)
  • func (c CallbacksStruct) OnError(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) OnOpampConnectionSettingsAccepted(settings *protobufs.OpAMPConnectionSettings)
  • func (c CallbacksStruct) SaveRemoteConfigStatus(ctx context.Context, status *protobufs.RemoteConfigStatus)
• type Logger
• type MessageData
• type PackageState
• type PackagesStateProvider
• type PackagesSyncer
• type StartSettings

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()

	// 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(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(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 and 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).
	//
	// If OnOpampConnectionSettings returns nil and then the caller will
	// attempt to reconnect to the OpAMP Server using the new settings.
	// If the connection fails the settings will be rejected and an error will
	// be reported to the Server. If the connection succeeds the new settings
	// will be used by the client from that moment on.
	//
	// Only one OnOpampConnectionSettings call can be active at any time.
	// See OnRemoteConfig for the behavior.
	OnOpampConnectionSettings(
		ctx context.Context,
		settings *protobufs.OpAMPConnectionSettings,
	) error

	// OnOpampConnectionSettingsAccepted will be called after the settings are
	// verified and accepted (OnOpampConnectionSettingsOffer and connection using
	// new settings succeeds). The Agent should store the settings and use them
	// in the future. Old connection settings should be forgotten.
	OnOpampConnectionSettingsAccepted(
		settings *protobufs.OpAMPConnectionSettings,
	)

	// 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(command *protobufs.ServerToAgentCommand) error
}

type CallbacksStruct

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

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

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

	OnCommandFunc func(command *protobufs.ServerToAgentCommand) error

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

func (CallbacksStruct) GetEffectiveConfig

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

func (CallbacksStruct) OnCommand

func (c CallbacksStruct) OnCommand(command *protobufs.ServerToAgentCommand) error

func (CallbacksStruct) OnConnect

func (c CallbacksStruct) OnConnect()

func (CallbacksStruct) OnConnectFailed

func (c CallbacksStruct) OnConnectFailed(err error)

func (CallbacksStruct) OnError

func (c CallbacksStruct) OnError(err *protobufs.ServerErrorResponse)

func (CallbacksStruct) OnMessage

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

func (CallbacksStruct) OnOpampConnectionSettings

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

func (CallbacksStruct) OnOpampConnectionSettingsAccepted

func (c CallbacksStruct) OnOpampConnectionSettingsAccepted(settings *protobufs.OpAMPConnectionSettings)

func (CallbacksStruct) SaveRemoteConfigStatus

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

type Logger

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

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
}

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
}

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 []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 TLS config for HTTP connection.
	TLSConfig *tls.Config

	// Agent information.
	InstanceUid string

	// 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
}