-
Notifications
You must be signed in to change notification settings - Fork 71
/
client.go
137 lines (122 loc) · 6.75 KB
/
client.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
package client
import (
"context"
"github.com/open-telemetry/opamp-go/client/types"
"github.com/open-telemetry/opamp-go/protobufs"
)
// OpAMPClient is an interface representing the client side of the OpAMP protocol.
type OpAMPClient interface {
// Start the client and begin attempts to connect to the Server. Once connection
// is established the client will attempt to maintain it by reconnecting if
// the connection is lost. All failed connection attempts will be reported via
// OnConnectFailed callback.
//
// SetAgentDescription() MUST be called before Start().
//
// Start may immediately return an error if the settings are incorrect (e.g. the
// serverURL is not a valid URL).
//
// Start does not wait until the connection to the Server is established and will
// likely return before the connection attempts are even made.
//
// It is guaranteed that after the Start() call returns without error one of the
// following callbacks will be called eventually (unless Stop() is called earlier):
// - OnConnectFailed
// - OnError
// - OnRemoteConfig
//
// Start should be called only once. It should not be called concurrently with
// any other OpAMPClient methods.
Start(ctx context.Context, settings types.StartSettings) error
// Stop the client. May be called only after Start() returns successfully.
// May be called only once.
// After this call returns successfully it is guaranteed that no
// callbacks will be called. Stop() will cancel context of any in-fly
// callbacks, but will wait until such in-fly callbacks are returned before
// Stop returns, so make sure the callbacks don't block infinitely and react
// promptly to context cancellations.
// Once stopped OpAMPClient cannot be started again.
Stop(ctx context.Context) error
// SetAgentDescription sets attributes of the Agent. The attributes will be included
// in the next status report sent to the Server. MUST be called before Start().
// May be also called after Start(), in which case the attributes will be included
// in the next outgoing status report. This is typically used by Agents which allow
// their AgentDescription to change dynamically while the OpAMPClient is started.
// May be also called from OnMessage handler.
//
// nil values are not allowed and will return an error.
SetAgentDescription(descr *protobufs.AgentDescription) error
// AgentDescription returns the last value successfully set by SetAgentDescription().
AgentDescription() *protobufs.AgentDescription
// SetHealth sets the health status of the Agent. The health will be included
// in the next status report sent to the Server. MAY be called before or after Start().
// May be also called after Start().
// May be also called from OnMessage handler.
//
// nil health parameter is not allowed and will return an error.
SetHealth(health *protobufs.ComponentHealth) error
// UpdateEffectiveConfig fetches the current local effective config using
// GetEffectiveConfig callback and sends it to the Server.
// May be called anytime after Start(), including from OnMessage handler.
UpdateEffectiveConfig(ctx context.Context) error
// SetRemoteConfigStatus sets the current RemoteConfigStatus.
// LastRemoteConfigHash field must be non-nil.
// May be called anytime after Start(), including from OnMessage handler.
// nil values are not allowed and will return an error.
SetRemoteConfigStatus(status *protobufs.RemoteConfigStatus) error
// SetPackageStatuses sets the current PackageStatuses.
// ServerProvidedAllPackagesHash must be non-nil.
// May be called anytime after Start(), including from OnMessage handler.
// nil values are not allowed and will return an error.
SetPackageStatuses(statuses *protobufs.PackageStatuses) error
// RequestConnectionSettings sets a ConnectionSettingsRequest. The ConnectionSettingsRequest
// will be included in the next AgentToServer message sent to the Server.
// Used for client-initiated connection setting acquisition flows.
// It is the responsibility of the caller to ensure that the Server supports
// AcceptsConnectionSettingsRequest capability.
// May be called before or after Start().
// May be also called from OnMessage handler.
RequestConnectionSettings(request *protobufs.ConnectionSettingsRequest) error
// SetCustomCapabilities modifies the set of customCapabilities supported by the client.
// The new customCapabilities will be sent with the next message to the server. If
// custom capabilities are used SHOULD be called before Start(). If not called before
// Start(), the set of supported custom capabilities will be empty. May also be called
// anytime after Start(), including from OnMessage handler, to modify the set of
// supported custom capabilities. nil values are not allowed and will return an error.
//
// Each capability is a reverse FQDN with optional version information that uniquely
// identifies the custom capability and should match a capability specified in a
// supported CustomMessage. The client will automatically ignore any CustomMessage that
// contains a custom capability that is not specified in this field.
//
// See
// https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#customcapabilities
// for more details.
SetCustomCapabilities(customCapabilities *protobufs.CustomCapabilities) error
// SetFlags modifies the set of flags supported by the client.
// May be called before or after Start(), including from OnMessage handler.
// The zero value of protobufs.AgentToServerFlags corresponds to FlagsUnspecified
// and is safe to use.
//
// See
// https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agenttoserverflags
// for more details.
SetFlags(flags protobufs.AgentToServerFlags)
// SendCustomMessage sends the custom message to the Server. May be called anytime after
// Start(), including from OnMessage handler.
//
// If the CustomMessage is nil, ErrCustomMessageMissing will be returned. If the message
// specifies a capability that is not listed in the CustomCapabilities provided in the
// StartSettings for the client, ErrCustomCapabilityNotSupported will be returned.
//
// Only one message can be sent at a time. If SendCustomMessage has been already called
// and the message is still pending (in progress) then subsequent calls to
// SendCustomMessage will return ErrCustomMessagePending and a channel that will be
// closed when the pending message is sent. To ensure that the previous send is complete
// and it is safe to send another CustomMessage, the caller should wait for the returned
// channel to be closed before attempting to send another custom message.
//
// If no error is returned, the channel returned will be closed after the specified
// message is sent.
SendCustomMessage(message *protobufs.CustomMessage) (messageSendingChannel chan struct{}, err error)
}