types

type Callbacks struct {
	// 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 func(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 func(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 func(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 func(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 func(
		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 func(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 func(ctx context.Context) (*protobufs.EffectiveConfig, error)

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

	// CheckRedirect is called before following a redirect, allowing the client
	// the opportunity to observe the redirect chain, and optionally terminate
	// following redirects early.
	//
	// CheckRedirect is intended to be similar, although not exactly equivalent,
	// to net/http.Client's CheckRedirect feature. Unlike in net/http, the via
	// parameter is a slice of HTTP responses, instead of requests. This gives
	// an opportunity to users to know what the exact response headers and
	// status were. The request itself can be obtained from the response.
	//
	// The responses in the via parameter are passed with their bodies closed.
	CheckRedirect func(req *http.Request, viaReq []*http.Request, via []*http.Response) error

	// DownloadHTTPClient is called to create an HTTP client that is used to download files by the package syncer.
	// If the callback is not set, a default HTTP client will be created with the default transport settings.
	// The callback must return a non-nil HTTP client or an error.
	DownloadHTTPClient func(ctx context.Context, file *protobufs.DownloadableFile) (*http.Client, error)

	// OnConnectionSettings is called when the agent recieves any non OpAMP
	// connection settings.
	//
	// 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 OnConnectionSettings call can be active at any time.
	// See OnRemoteConfig for the behavior.
	OnConnectionSettings func(
		ctx context.Context,
		settings *protobufs.ConnectionSettingsOffers,
	) error
}

type InstanceUid [16]byte

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

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.
	OfferedConnectionsSettingsHash []byte
	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
}

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 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.
	// Depending on implementation, this method may be called concurrently if a client
	// downloads many packages at once. Implementors of this interface should take care
	// to ensure that conflicting writes do not occur.
	SetLastReportedStatuses(statuses *protobufs.PackageStatuses) error
}

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

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

	// Optional Proxy configuration
	// The ProxyURL may be http(s) or socks5; if no schema is specified http is assumed.
	ProxyURL string
	// ProxyHeaders gives the headers an HTTP client will present on a proxy CONNECT request.
	ProxyHeaders http.Header

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

	// The last offered connection settings status.
	LastConnectionSettingsStatus *protobufs.ConnectionSettingsStatus

	// 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.
	// Deprecated: Use client.SetCapabilities() instead.
	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

	// Optional HeartbeatInterval to configure the heartbeat interval for client.
	// If nil, the default heartbeat interval (30s) will be used.
	// If zero, heartbeat will be disabled for a Websocket-based client.
	//
	// Note that an HTTP-based client will use the heartbeat interval as its polling interval
	// and zero is invalid for an HTTP-based client.
	//
	// If the ReportsHeartbeat capability is disabled, this option has no effect.
	HeartbeatInterval *time.Duration

	// Optional DownloadReporterInterval to configure how often a client reports the status of a package that is being downloaded.
	// If nil, the default reporter interval (10s) will be used.
	// If specified a minimum value of 1s will be enforced.
	DownloadReporterInterval *time.Duration
}