go.temporal.io/server/common/dynamicconfig/client.go
97 LOC · 0 covered · 97 uncovered · 0 ranges · 0 concepts · 0 introducers · 0 tests
1
package dynamicconfig
2
3
import (
4
enumspb "go.temporal.io/api/enums/v1"
5
enumsspb "go.temporal.io/server/api/enums/v1"
6
)
7
8
type (
9
// Client is a source of dynamic configuration. The default Client, fileBasedClient, reads
10
// from a file in the filesystem, and refreshes it periodically. You can extend the server
11
// with an alternate Client using ServerOptions.
12
Client interface {
13
// GetValue returns a set of values and associated constraints for a key. Not all
14
// constraints are valid for all keys.
15
//
16
// The returned slice of ConstrainedValues is treated as a set, and order does not
17
// matter. The effective order of constraints is determined by server logic. See the
18
// comment on Constraints below.
19
//
20
// If none of the ConstrainedValues match the constraints being used for the key, then
21
// the server default value will be used.
22
//
23
// Note that GetValue is called very often! You should not synchronously call out to an
24
// external system. Instead you should keep a set of all configured values, refresh it
25
// periodically or when notified, and only do in-memory lookups inside of GetValue.
26
//
27
// Implementations should prefer to return the same slice in response to the same key
28
// as long as the value hasn't changed. Value conversions are cached using weak
29
// pointers into the returned slice, so new slices will result in unnecessary calls to
30
// conversion functions.
31
GetValue(key Key) []ConstrainedValue
32
}
33
34
// NotifyingClient is an optional interface that a Client can also implement, that adds
35
// support for faster notifications of dynamic config changes.
36
NotifyingClient interface {
37
// Adds a subscription to all updates from this Client. `update` will be called on any
38
// change to the current value set. The caller should call `cancel` to cancel the
39
// subscription.
40
Subscribe(update ClientUpdateFunc) (cancel func())
41
}
42
43
// Called with modified keys on any change to the current value set.
44
// Deleted keys/constraints will get a nil value.
45
ClientUpdateFunc func(map[Key][]ConstrainedValue)
46
47
// ConstrainedValue is a value plus associated constraints.
48
//
49
// The type of the Value field depends on the key. Acceptable types will be one of:
50
// int, float64, bool, string, map[string]any, time.Duration
51
//
52
// If time.Duration is expected, a string is also accepted, which will be converted using
53
// timestamp.ParseDurationDefaultDays. If float64 is expected, int is also accepted. In
54
// other cases, the exact type must be used. If a Value is returned with an unexpected
55
// type, it will be ignored.
56
ConstrainedValue struct {
57
Constraints Constraints
58
Value any
59
}
60
TypedConstrainedValue[T any] struct {
61
Constraints Constraints
62
Value T
63
}
64
65
// Constraints describe under what conditions a ConstrainedValue should be used.
66
// There are few standard "constraint precedence orders" that the server uses:
67
// global precedence:
68
// no constraints
69
// namespace precedence:
70
// Namespace
71
// no constraints
72
// task queue precedence
73
// Namespace+TaskQueueName+TaskQueueType
74
// Namespace+TaskQueueName
75
// TaskQueueName
76
// Namespace
77
// no constraints
78
// shard id precedence:
79
// ShardID
80
// no constraints
81
// In each case, the constraints that the server is checking and the constraints that apply
82
// to the value must match exactly, including the fields that are not set (zero values).
83
// That is, for keys that use namespace precedence, you must either return a
84
// ConstrainedValue with only Namespace set, or with no fields set. (Or return one of
85
// each.) If you return a ConstrainedValue with Namespace and ShardID set, for example,
86
// that value will never be used, even if the Namespace matches.
87
Constraints struct {
88
Namespace string
89
NamespaceID string
90
TaskQueueName string
91
Destination string
92
ChasmTaskType string
93
TaskQueueType enumspb.TaskQueueType
94
ShardID int32
95
TaskType enumsspb.TaskType
96
}
97
)