go.temporal.io/server@v1.23.0/common/dynamicconfig/client.go (about) 1 // The MIT License 2 // 3 // Copyright (c) 2020 Temporal Technologies Inc. All rights reserved. 4 // 5 // Copyright (c) 2020 Uber Technologies, Inc. 6 // 7 // Permission is hereby granted, free of charge, to any person obtaining a copy 8 // of this software and associated documentation files (the "Software"), to deal 9 // in the Software without restriction, including without limitation the rights 10 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 // copies of the Software, and to permit persons to whom the Software is 12 // furnished to do so, subject to the following conditions: 13 // 14 // The above copyright notice and this permission notice shall be included in 15 // all copies or substantial portions of the Software. 16 // 17 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 // THE SOFTWARE. 24 25 package dynamicconfig 26 27 import ( 28 enumspb "go.temporal.io/api/enums/v1" 29 30 enumsspb "go.temporal.io/server/api/enums/v1" 31 ) 32 33 type ( 34 // Client is a source of dynamic configuration. The default Client, fileBasedClient, reads 35 // from a file in the filesystem, and refreshes it periodically. You can extend the server 36 // with an alternate Client using ServerOptions. 37 Client interface { 38 // GetValue returns a set of values and associated constraints for a key. Not all 39 // constraints are valid for all keys. 40 // 41 // The returned slice of ConstrainedValues is treated as a set, and order does not 42 // matter. The effective order of constraints is determined by server logic. See the 43 // comment on Constraints below. 44 // 45 // If none of the ConstrainedValues match the constraints being used for the key, then 46 // the server default value will be used. 47 // 48 // Note that GetValue is called very often! You should not synchronously call out to an 49 // external system. Instead you should keep a set of all configured values, refresh it 50 // periodically or when notified, and only do in-memory lookups inside of GetValue. 51 GetValue(key Key) []ConstrainedValue 52 } 53 54 // Key is a key/property stored in dynamic config. For convenience, it is recommended that 55 // you treat keys as case-insensitive. 56 Key string 57 58 // ConstrainedValue is a value plus associated constraints. 59 // 60 // The type of the Value field depends on the key. Acceptable types will be one of: 61 // int, float64, bool, string, map[string]any, time.Duration 62 // 63 // If time.Duration is expected, a string is also accepted, which will be converted using 64 // timestamp.ParseDurationDefaultDays. If float64 is expected, int is also accepted. In 65 // other cases, the exact type must be used. If a Value is returned with an unexpected 66 // type, it will be ignored. 67 ConstrainedValue struct { 68 Constraints Constraints 69 Value any 70 } 71 72 // Constraints describe under what conditions a ConstrainedValue should be used. 73 // There are few standard "constraint precedence orders" that the server uses: 74 // global precedence: 75 // no constraints 76 // namespace precedence: 77 // Namespace 78 // no constraints 79 // task queue precedence 80 // Namespace+TaskQueueName+TaskQueueType 81 // Namespace+TaskQueueName 82 // TaskQueueName 83 // Namespace 84 // no constraints 85 // shard id precedence: 86 // ShardID 87 // no constraints 88 // In each case, the constraints that the server is checking and the constraints that apply 89 // to the value must match exactly, including the fields that are not set (zero values). 90 // That is, for keys that use namespace precedence, you must either return a 91 // ConstrainedValue with only Namespace set, or with no fields set. (Or return one of 92 // each.) If you return a ConstrainedValue with Namespace and ShardID set, for example, 93 // that value will never be used, even if the Namespace matches. 94 Constraints struct { 95 Namespace string 96 NamespaceID string 97 TaskQueueName string 98 TaskQueueType enumspb.TaskQueueType 99 ShardID int32 100 TaskType enumsspb.TaskType 101 } 102 )