configdirector-server-sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. checksums.yaml +7 -0
  2. data/.yardopts +2 -0
  3. data/CHANGELOG.md +254 -0
  4. data/LICENSE +21 -0
  5. data/README.md +230 -0
  6. data/lib/configdirector/client_hooks.rb +46 -0
  7. data/lib/configdirector/config_director_client.rb +322 -0
  8. data/lib/configdirector/config_evaluated_event.rb +10 -0
  9. data/lib/configdirector/config_evaluation.rb +51 -0
  10. data/lib/configdirector/config_state.rb +39 -0
  11. data/lib/configdirector/configs_updated_event.rb +23 -0
  12. data/lib/configdirector/connection_error_event.rb +11 -0
  13. data/lib/configdirector/connection_options.rb +60 -0
  14. data/lib/configdirector/context.rb +53 -0
  15. data/lib/configdirector/errors.rb +29 -0
  16. data/lib/configdirector/internal/client/client_connection.rb +119 -0
  17. data/lib/configdirector/internal/client/client_factory.rb +104 -0
  18. data/lib/configdirector/internal/client/client_options_validation.rb +53 -0
  19. data/lib/configdirector/internal/client/config_read.rb +31 -0
  20. data/lib/configdirector/internal/client/config_reader.rb +55 -0
  21. data/lib/configdirector/internal/client/connection_intake.rb +59 -0
  22. data/lib/configdirector/internal/client/connection_options_validation.rb +94 -0
  23. data/lib/configdirector/internal/client/context_admission.rb +48 -0
  24. data/lib/configdirector/internal/client/context_attributes.rb +78 -0
  25. data/lib/configdirector/internal/client/context_kind.rb +24 -0
  26. data/lib/configdirector/internal/client/evaluated_read.rb +9 -0
  27. data/lib/configdirector/internal/client/event_handlers.rb +114 -0
  28. data/lib/configdirector/internal/client/event_tracking.rb +39 -0
  29. data/lib/configdirector/internal/client/live_client_connections.rb +58 -0
  30. data/lib/configdirector/internal/client/number_of_seconds.rb +21 -0
  31. data/lib/configdirector/internal/client/registrations.rb +43 -0
  32. data/lib/configdirector/internal/client/restart_in_forked_processes.rb +25 -0
  33. data/lib/configdirector/internal/client/served_configs.rb +83 -0
  34. data/lib/configdirector/internal/client/serving_state.rb +102 -0
  35. data/lib/configdirector/internal/client/watches.rb +51 -0
  36. data/lib/configdirector/internal/client/what_follows_a_fork.rb +24 -0
  37. data/lib/configdirector/internal/connection/condition_parser.rb +74 -0
  38. data/lib/configdirector/internal/connection/config_definition.rb +37 -0
  39. data/lib/configdirector/internal/connection/http_session.rb +15 -0
  40. data/lib/configdirector/internal/connection/in_memory_connection.rb +134 -0
  41. data/lib/configdirector/internal/connection/json_post_request.rb +24 -0
  42. data/lib/configdirector/internal/connection/not_a_server_sdk_payload.rb +9 -0
  43. data/lib/configdirector/internal/connection/offline_mode_connection.rb +96 -0
  44. data/lib/configdirector/internal/connection/offline_values_file.rb +49 -0
  45. data/lib/configdirector/internal/connection/payloads_delivered_in_turn.rb +46 -0
  46. data/lib/configdirector/internal/connection/polling_interval.rb +21 -0
  47. data/lib/configdirector/internal/connection/request_deadline.rb +45 -0
  48. data/lib/configdirector/internal/connection/retry_after_header.rb +24 -0
  49. data/lib/configdirector/internal/connection/server_sdk_payload.rb +37 -0
  50. data/lib/configdirector/internal/connection/server_sdk_payload_parser.rb +89 -0
  51. data/lib/configdirector/internal/connection/targeting_rules_parser.rb +70 -0
  52. data/lib/configdirector/internal/connection/test_client_initializations.rb +111 -0
  53. data/lib/configdirector/internal/connection/test_client_values.rb +53 -0
  54. data/lib/configdirector/internal/connection/unreadable_definition.rb +9 -0
  55. data/lib/configdirector/internal/connection/wire_fields.rb +59 -0
  56. data/lib/configdirector/internal/evaluation/array_comparison.rb +25 -0
  57. data/lib/configdirector/internal/evaluation/assigned_percentage.rb +21 -0
  58. data/lib/configdirector/internal/evaluation/attribute_condition.rb +48 -0
  59. data/lib/configdirector/internal/evaluation/config_evaluator.rb +29 -0
  60. data/lib/configdirector/internal/evaluation/datetime_comparison.rb +93 -0
  61. data/lib/configdirector/internal/evaluation/evaluation_context.rb +17 -0
  62. data/lib/configdirector/internal/evaluation/number_comparison.rb +119 -0
  63. data/lib/configdirector/internal/evaluation/rapidhash.rb +124 -0
  64. data/lib/configdirector/internal/evaluation/rollout_share.rb +9 -0
  65. data/lib/configdirector/internal/evaluation/rule.rb +70 -0
  66. data/lib/configdirector/internal/evaluation/scalar_text.rb +70 -0
  67. data/lib/configdirector/internal/evaluation/segment.rb +17 -0
  68. data/lib/configdirector/internal/evaluation/segment_condition.rb +26 -0
  69. data/lib/configdirector/internal/evaluation/semver_comparison.rb +49 -0
  70. data/lib/configdirector/internal/evaluation/served_value.rb +9 -0
  71. data/lib/configdirector/internal/evaluation/share.rb +9 -0
  72. data/lib/configdirector/internal/evaluation/targeting_rules.rb +18 -0
  73. data/lib/configdirector/internal/evaluation/text_comparison.rb +32 -0
  74. data/lib/configdirector/internal/evaluation/trait_pointer.rb +42 -0
  75. data/lib/configdirector/internal/evaluation.rb +21 -0
  76. data/lib/configdirector/internal/identity/sdk_identity.rb +39 -0
  77. data/lib/configdirector/internal/identity/wrapper.rb +48 -0
  78. data/lib/configdirector/internal/logging/client_log.rb +37 -0
  79. data/lib/configdirector/internal/logging/default_logger.rb +34 -0
  80. data/lib/configdirector/internal/polling/poll_answer.rb +111 -0
  81. data/lib/configdirector/internal/polling/poll_request.rb +106 -0
  82. data/lib/configdirector/internal/polling/poll_timing.rb +25 -0
  83. data/lib/configdirector/internal/polling/polling_endpoint.rb +36 -0
  84. data/lib/configdirector/internal/polling/polling_mode_connection.rb +53 -0
  85. data/lib/configdirector/internal/polling/polling_session.rb +99 -0
  86. data/lib/configdirector/internal/polling/polling_transport.rb +74 -0
  87. data/lib/configdirector/internal/polling/refusal_detail.rb +36 -0
  88. data/lib/configdirector/internal/server_sent_events/event_stream_limit_exceeded.rb +9 -0
  89. data/lib/configdirector/internal/server_sent_events/event_stream_parser.rb +95 -0
  90. data/lib/configdirector/internal/server_sent_events/server_sent_event.rb +9 -0
  91. data/lib/configdirector/internal/stoppable_thread.rb +69 -0
  92. data/lib/configdirector/internal/streaming/heartbeats.rb +51 -0
  93. data/lib/configdirector/internal/streaming/reconnecting_stream.rb +82 -0
  94. data/lib/configdirector/internal/streaming/reconnection_delay.rb +29 -0
  95. data/lib/configdirector/internal/streaming/stream_connection.rb +86 -0
  96. data/lib/configdirector/internal/streaming/stream_end.rb +69 -0
  97. data/lib/configdirector/internal/streaming/stream_endpoint.rb +43 -0
  98. data/lib/configdirector/internal/streaming/stream_timing.rb +33 -0
  99. data/lib/configdirector/internal/streaming/streaming_mode_connection.rb +60 -0
  100. data/lib/configdirector/internal/streaming/streaming_transport.rb +42 -0
  101. data/lib/configdirector/internal/telemetry/aggregated_wire_entries.rb +26 -0
  102. data/lib/configdirector/internal/telemetry/collected_telemetry.rb +98 -0
  103. data/lib/configdirector/internal/telemetry/compact_json_text.rb +64 -0
  104. data/lib/configdirector/internal/telemetry/discarded_telemetry.rb +31 -0
  105. data/lib/configdirector/internal/telemetry/event_reporter.rb +47 -0
  106. data/lib/configdirector/internal/telemetry/invalid_context_submissions.rb +76 -0
  107. data/lib/configdirector/internal/telemetry/report_answer.rb +31 -0
  108. data/lib/configdirector/internal/telemetry/report_schedule.rb +66 -0
  109. data/lib/configdirector/internal/telemetry/report_timing.rb +20 -0
  110. data/lib/configdirector/internal/telemetry/reported_context.rb +28 -0
  111. data/lib/configdirector/internal/telemetry/reported_details.rb +71 -0
  112. data/lib/configdirector/internal/telemetry/reported_evaluation.rb +82 -0
  113. data/lib/configdirector/internal/telemetry/reported_telemetry.rb +127 -0
  114. data/lib/configdirector/internal/telemetry/reported_text.rb +13 -0
  115. data/lib/configdirector/internal/telemetry/reported_time.rb +13 -0
  116. data/lib/configdirector/internal/telemetry/reported_value.rb +35 -0
  117. data/lib/configdirector/internal/telemetry/telemetry_endpoint.rb +54 -0
  118. data/lib/configdirector/internal/telemetry/telemetry_report.rb +50 -0
  119. data/lib/configdirector/internal/telemetry/test_client_telemetry.rb +37 -0
  120. data/lib/configdirector/internal/telemetry/tracked_event_admission.rb +72 -0
  121. data/lib/configdirector/internal/telemetry/tracked_event_entry.rb +27 -0
  122. data/lib/configdirector/internal/telemetry/tracked_event_queue.rb +47 -0
  123. data/lib/configdirector/internal/telemetry/tracked_event_warning.rb +28 -0
  124. data/lib/configdirector/internal/telemetry/value_id.rb +23 -0
  125. data/lib/configdirector/internal/telemetry/written_json.rb +9 -0
  126. data/lib/configdirector/internal/unchangeable_copy.rb +38 -0
  127. data/lib/configdirector/internal/value/encoded_native_value.rb +45 -0
  128. data/lib/configdirector/internal/value/hash_keys.rb +34 -0
  129. data/lib/configdirector/internal/value/in_code_default_value.rb +33 -0
  130. data/lib/configdirector/internal/value/json_contents.rb +81 -0
  131. data/lib/configdirector/internal/value/json_position.rb +27 -0
  132. data/lib/configdirector/internal/value/native_values.rb +41 -0
  133. data/lib/configdirector/internal/value/parsed_json.rb +79 -0
  134. data/lib/configdirector/internal/value/plain_decimal_text.rb +36 -0
  135. data/lib/configdirector/internal/value/served_text.rb +76 -0
  136. data/lib/configdirector/internal/value/typed_value.rb +9 -0
  137. data/lib/configdirector/internal/value/unservable_value.rb +9 -0
  138. data/lib/configdirector/internal/value/utf8_text.rb +19 -0
  139. data/lib/configdirector/internal.rb +9 -0
  140. data/lib/configdirector/metadata.rb +26 -0
  141. data/lib/configdirector/subscription.rb +34 -0
  142. data/lib/configdirector/telemetry_options.rb +28 -0
  143. data/lib/configdirector/testing/test_client.rb +122 -0
  144. data/lib/configdirector/testing/tracked_event.rb +46 -0
  145. data/lib/configdirector/testing.rb +44 -0
  146. data/lib/configdirector/variation.rb +21 -0
  147. data/lib/configdirector/version.rb +7 -0
  148. data/lib/configdirector-server-sdk.rb +3 -0
  149. data/lib/configdirector.rb +164 -0
  150. data/sig/configdirector/internal/client.rbs +518 -0
  151. data/sig/configdirector/internal/connection.rbs +389 -0
  152. data/sig/configdirector/internal/evaluation.rbs +364 -0
  153. data/sig/configdirector/internal/identity.rbs +51 -0
  154. data/sig/configdirector/internal/logging.rbs +33 -0
  155. data/sig/configdirector/internal/polling.rbs +240 -0
  156. data/sig/configdirector/internal/server_sent_events.rbs +51 -0
  157. data/sig/configdirector/internal/streaming.rbs +266 -0
  158. data/sig/configdirector/internal/telemetry.rbs +556 -0
  159. data/sig/configdirector/internal/value.rbs +159 -0
  160. data/sig/configdirector/testing.rbs +70 -0
  161. data/sig/configdirector.rbs +465 -0
  162. metadata +231 -0
@@ -0,0 +1,322 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "monitor"
4
+
5
+ module ConfigDirector
6
+ # The ConfigDirector SDK client. Create one with {ConfigDirector.create_client}, call {#init} when your
7
+ # application starts and {#close} when it shuts down. A client can be shared between threads.
8
+ #
9
+ # The client reports what it evaluates and the events it {#track}s to ConfigDirector, on a thread of the SDK that
10
+ # {#init} starts: the first report 5 seconds after {#init}, then one every {TelemetryOptions#flush_interval}.
11
+ # {#close} sends the last one, so a process that exits without calling it does not report its last reads and
12
+ # events. An offline client reports nothing.
13
+ #
14
+ # When the process forks after {#init}, as Puma does for its workers in cluster mode, the client starts its
15
+ # own connection in the forked process by itself. There it serves the values it had at the fork at once, and
16
+ # its handlers and watches keep being called, on a thread of the SDK. It reports what the forked process
17
+ # evaluates and tracks from there, and what was evaluated and tracked before the fork from the parent.
18
+ class ConfigDirectorClient
19
+ # @api private
20
+ def initialize(connection:, telemetry:, mode:, timeout:, metadata:, logger:, hooks:)
21
+ @mode = mode
22
+ @timeout = timeout.to_f
23
+ @log = Internal::Logging::ClientLog.new(logger)
24
+ @connection_lifecycle = Monitor.new
25
+ @serving_state = Internal::Client::ServingState.new(metadata)
26
+ @event_handlers = Internal::Client::EventHandlers.new(hooks, @log)
27
+ @watches = Internal::Client::Watches.new(@log)
28
+ @config_reader = config_reader_over(telemetry)
29
+ @event_tracking = Internal::Client::EventTracking.new(mode: mode, telemetry: telemetry, log: @log)
30
+ @client_connection = client_connection_over(connection, telemetry)
31
+ end
32
+
33
+ # Connects to ConfigDirector and makes the client ready. It waits, up to the connection timeout, for the
34
+ # first values and for their +configs_updated+ handlers, watches and +client_ready+ handlers to finish.
35
+ # Calling it again waits again and never opens a second connection.
36
+ #
37
+ # It never raises because the connection failed, and every read returns its in-code default value until
38
+ # values arrive:
39
+ #
40
+ # - When no values arrive in time it logs a warning and returns, and the client keeps trying.
41
+ # - When ConfigDirector refuses the connection, for example because it does not know the server SDK key,
42
+ # it logs an error, calls the +connection_error+ handlers and returns at once. The client does not try
43
+ # again, and a later call returns at once.
44
+ # - In polling mode, when the first request for values fails for another reason, it logs an error and
45
+ # returns at once, and the client asks again after the polling interval.
46
+ #
47
+ # In offline mode it makes no network call. It reads the offline values file again each time it is called,
48
+ # and the client is ready when it returns. It calls the +configs_updated+ handlers with every key the values
49
+ # hold and the watches each time, as it does when values arrive from ConfigDirector.
50
+ #
51
+ # @return [void]
52
+ # @raise [ConfigDirectorValidationError] when the client is closed
53
+ # @raise [ConfigDirectorInitializationError] in offline mode, when the offline values file cannot be read,
54
+ # is not UTF-8 text, is not valid JSON, is not a JSON object, or holds a value the SDK cannot serve. A
55
+ # client that was not ready stays not ready, and one that was ready keeps serving the values it had.
56
+ def init
57
+ give_up_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
58
+ connection_opening = @connection_lifecycle.synchronize do
59
+ raise_if_closed
60
+ @client_connection.open
61
+ end
62
+
63
+ case connection_opening
64
+ when :first_attempt_failed then nil
65
+ when :values_awaited, :opened_before then warn_unless_the_first_values_arrive_by(give_up_at)
66
+ end
67
+ end
68
+
69
+ # @return [Boolean] whether the client has values to serve
70
+ def ready?
71
+ !@serving_state.served_configs.nil?
72
+ end
73
+
74
+ # Evaluates a config and returns its value for the given context.
75
+ #
76
+ # @example
77
+ # client.get_value("new-checkout", false, ConfigDirector::Context.new(id: "user-123"))
78
+ #
79
+ # @param config_key [String] the config key to evaluate
80
+ # @param default_value [Boolean, String, Integer, Float, Hash, Array] the in-code default value, returned
81
+ # when no value from ConfigDirector can be served: for example before the client is ready, when no
82
+ # config has the key, or when the config's value cannot be read as the class of this value. Its class
83
+ # decides the class of the value returned: +true+ or +false+ reads a boolean, a String reads the text
84
+ # of any config that is not a boolean, an integer or a float, an Integer reads a whole number, a Float
85
+ # reads a number, a Hash reads a JSON object and an Array reads a JSON array.
86
+ # @param context [Context, nil] the context to evaluate the targeting rules for
87
+ # @return [Boolean, String, Integer, Float, Hash, Array] the config's value, or the in-code default value
88
+ # @raise [ConfigDirectorValidationError] when the in-code default value is +nil+ or of any other class,
89
+ # or when the context is not a {Context}
90
+ def get_value(config_key, default_value, context = nil)
91
+ @config_reader.evaluation_of(config_key, default_value, context).value
92
+ end
93
+
94
+ # Evaluates a config as {#get_value} does and returns the evaluation: the value, the reason it was
95
+ # served, its value ID and its variation. Like every read, it calls the +config_evaluated+ handlers
96
+ # before it returns.
97
+ #
98
+ # @param config_key [String] the config key to evaluate
99
+ # @param default_value [Boolean, String, Integer, Float, Hash, Array] the in-code default value, returned
100
+ # when no value from ConfigDirector can be served. Its class decides the class of the value returned.
101
+ # @param context [Context, nil] the context to evaluate the targeting rules for
102
+ # @return [ConfigEvaluation] the evaluation, whose +value+ is what {#get_value} returns
103
+ # @raise [ConfigDirectorValidationError] when the in-code default value is +nil+ or of any other class,
104
+ # or when the context is not a {Context}
105
+ def evaluate(config_key, default_value, context = nil)
106
+ @config_reader.evaluation_of(config_key, default_value, context)
107
+ end
108
+
109
+ # Returns what every config serves to the given context, keyed by config key, or only the configs listed
110
+ # in +config_keys+. It reports no evaluation, calls no +config_evaluated+ handler, and returns an empty
111
+ # Hash when the client is not ready.
112
+ #
113
+ # @param context [Context, nil] the context to evaluate the targeting rules for
114
+ # @param config_keys [Array<String>, nil] the config keys to return. Every config is returned when left
115
+ # out.
116
+ # @return [Hash{String => ConfigState}] what each config serves, keyed by config key
117
+ # @raise [ConfigDirectorValidationError] when the context is not a {Context} or +config_keys+ is not an
118
+ # Array
119
+ def get_all_configs(context: nil, config_keys: nil)
120
+ @config_reader.states(context, config_keys)
121
+ end
122
+
123
+ # Calls the block with the config's value each time the client receives values that include the config
124
+ # or leave it out, even when its value is the same. The block is not called when the watch is
125
+ # registered, so a watch registered before {#init} receives the first value during it. When the values
126
+ # received leave the config out, the block receives the in-code default value. The block is also called
127
+ # each time the client receives a segment that one of the config's targeting rules uses. The block runs
128
+ # on the thread that received the values, as {#on} describes, after the +configs_updated+ handlers, and
129
+ # an error it raises is logged and ignored.
130
+ #
131
+ # @example
132
+ # subscription = client.watch("new-checkout", false, ConfigDirector::Context.new(id: "user-123")) do |enabled|
133
+ # puts "new-checkout is now #{enabled}"
134
+ # end
135
+ # subscription.close
136
+ #
137
+ # @param config_key [String] the config key to watch
138
+ # @param default_value [Boolean, String, Integer, Float, Hash, Array] the in-code default value, as
139
+ # {#get_value} takes it. Its class decides the class of the value the block receives.
140
+ # @param context [Context, nil] the context to evaluate the targeting rules for
141
+ # @yieldparam value [Boolean, String, Integer, Float, Hash, Array] the config's value, or the in-code
142
+ # default value
143
+ # @return [Subscription] the watch, which {Subscription#close} removes
144
+ # @raise [ConfigDirectorValidationError] when no block is given, when the in-code default value is +nil+
145
+ # or of any other class, or when the context is not a {Context}
146
+ def watch(config_key, default_value, context = nil, &callback)
147
+ config_read = @config_reader.config_read_of(config_key, default_value, context)
148
+ raise ConfigDirectorValidationError, "A watch needs a block to call with the value." if callback.nil?
149
+
150
+ @watches.add(config_read, callback)
151
+ end
152
+
153
+ # Removes the first watch on the config key whose block is +callback+, or every watch on the config key
154
+ # when +callback+ is left out. A block is found when it is the same Proc or lambda, such as one given
155
+ # to {#watch} as +&on_change+. To remove one watch whatever its block, close the {Subscription}
156
+ # {#watch} returned.
157
+ #
158
+ # @param config_key [String] the config key the watch is on
159
+ # @param callback [Proc, nil] the block of the watch to remove
160
+ # @return [void]
161
+ def unwatch(config_key, callback = nil)
162
+ @watches.remove(config_key, callback)
163
+ end
164
+
165
+ # Removes every watch on every config key.
166
+ #
167
+ # @return [void]
168
+ def unwatch_all
169
+ @watches.remove_all
170
+ end
171
+
172
+ # Reports to ConfigDirector that something happened, such as a completed checkout, so it can be counted. The
173
+ # event is sent with the next telemetry report, with the time of the call, and {#close} sends the events tracked
174
+ # since the last report. It returns +nil+, never raises, and does nothing in offline mode or once the client is
175
+ # closed.
176
+ #
177
+ # An event counts for an experiment only when it is tracked for a context with an +id+, the one the experiment's
178
+ # config was evaluated for. Without a context, or for a context without an +id+, the event is still reported. The
179
+ # +id+ of an anonymous context is not sent. When the context's kind is invalid, the error is logged as it is for a
180
+ # read and the event is reported without the context. When the context is not a {Context}, the event is not
181
+ # reported and a warning is logged.
182
+ #
183
+ # A report holds at most 1,000 tracked events, and events beyond that are not reported. An event whose name does
184
+ # not have 1 to 150 characters is not reported. A value that is not a finite number, and details that are not a
185
+ # Hash, have more than 20 top-level keys, are larger than 1,024 bytes as JSON, are nested deeper than 100 levels
186
+ # or hold anything but what +details+ lists, are left out, and the event is still reported. Each of these logs
187
+ # one warning per report.
188
+ #
189
+ # @example
190
+ # client.track(
191
+ # "checkout-completed", ConfigDirector::Context.new(id: "user-123"), value: 49.9, details: { plan: "pro" }
192
+ # )
193
+ #
194
+ # @param event_name [String, Symbol] the event's name, 1 to 150 characters. A Symbol is read as its name.
195
+ # @param context [Context, nil] the context the event happened for
196
+ # @param value [Integer, Float, nil] a number the event measures, such as an amount of money, a count or a
197
+ # duration
198
+ # @param details [Hash{String, Symbol => Object}, nil] details of the event, such as the plan a customer chose:
199
+ # Strings, numbers, +true+, +false+, +nil+, Symbols, Times, and Arrays and Hashes of them, with String or Symbol
200
+ # keys. A Symbol is sent as its name, a Time as its ISO 8601 text in UTC and a Float that is not finite as
201
+ # +null+.
202
+ # @return [void]
203
+ def track(event_name, context = nil, value: nil, details: nil)
204
+ @event_tracking.track(event_name, context, value: value, details: details) unless closed?
205
+ end
206
+
207
+ # Registers a handler for one of the events the client emits. A handler registered twice runs twice.
208
+ #
209
+ # - +:client_ready+ handlers are called with no argument once, when the client first receives values
210
+ # and becomes ready, after the +configs_updated+ handlers and the watches.
211
+ # - +:configs_updated+ handlers are called with a {ConfigsUpdatedEvent} each time the client receives
212
+ # values, the first time included.
213
+ # - +:config_evaluated+ handlers are called with a {ConfigEvaluatedEvent} each time {#get_value},
214
+ # {#evaluate} or a watch evaluates a config, on the thread that read, before the read returns.
215
+ # - +:connection_error+ handlers are called with a {ConnectionErrorEvent} when ConfigDirector refuses the
216
+ # connection, for example because it does not know the server SDK key, and the client will not try
217
+ # again. They are called at most once for a client, except for the client of a {Testing::TestClient},
218
+ # whose every failed +init+ calls them.
219
+ #
220
+ # +client_ready+, +configs_updated+ and +connection_error+ handlers run on the thread that received
221
+ # from ConfigDirector. In streaming mode that is a thread of the SDK. In polling mode it is the thread
222
+ # that called {#init} for the first request, and a thread of the SDK for every later one. In offline
223
+ # mode it is the thread that called {#init}. For the client of a {Testing::TestClient}, it is the thread
224
+ # that called {#init} or the method of the test client that delivered the values. Handlers may read from
225
+ # the client, and an error a handler raises is logged and ignored.
226
+ #
227
+ # @example
228
+ # client.on(:configs_updated) { |event| puts "Updated: #{event.keys.join(", ")}" }
229
+ #
230
+ # @param event_name [Symbol] +:client_ready+, +:configs_updated+, +:config_evaluated+ or
231
+ # +:connection_error+
232
+ # @param handler [#call, nil] the handler, when no block is given: any object that responds to +call+,
233
+ # such as a lambda or +method(:name)+
234
+ # @yield the event, as +handler+ would receive it
235
+ # @return [Subscription] the registration, which {Subscription#close} removes
236
+ # @raise [ConfigDirectorValidationError] when the event name is not one of the four Symbols, when both a
237
+ # handler and a block are given or neither is, or when the handler does not respond to +call+
238
+ def on(event_name, handler = nil, &block)
239
+ @event_handlers.add(event_name, Internal::Client::EventHandlers.one_handler_of(handler, block))
240
+ end
241
+
242
+ # Removes the first registration of +handler+ for the event, or every handler of the event, hooks
243
+ # included, when +handler+ is left out. A handler is found when it is equal to +handler+, so
244
+ # +method(:name)+ finds a handler registered as +method(:name)+, while a block or lambda is found only
245
+ # as the same object.
246
+ #
247
+ # @param event_name [Symbol] +:client_ready+, +:configs_updated+, +:config_evaluated+ or
248
+ # +:connection_error+
249
+ # @param handler [#call, nil] the handler to remove
250
+ # @return [void]
251
+ # @raise [ConfigDirectorValidationError] when the event name is not one of the four Symbols
252
+ def off(event_name, handler = nil)
253
+ @event_handlers.remove(event_name, handler)
254
+ end
255
+
256
+ # Closes the client and removes every handler, hook and watch. Afterwards the client is not ready, every
257
+ # read returns its in-code default value and {#get_all_configs} is empty. It is safe to call more than
258
+ # once.
259
+ #
260
+ # Before it returns, it sends what the client evaluated and tracked since its last report. It waits up to 5
261
+ # seconds for ConfigDirector to answer, and up to 5 more when a report was already being sent.
262
+ #
263
+ # @return [void]
264
+ def close
265
+ @connection_lifecycle.synchronize do
266
+ return if closed?
267
+
268
+ @serving_state.close
269
+ @event_handlers.remove_all
270
+ @watches.remove_all
271
+ @client_connection.close
272
+ end
273
+
274
+ @log.debug { "close has been called, the client is now closed" }
275
+ end
276
+
277
+ # @return [Boolean] whether {#close} has been called
278
+ def closed?
279
+ @serving_state.closed?
280
+ end
281
+
282
+ # @return [String] the client's connection mode and whether it is ready and closed, such as
283
+ # <tt>#<ConfigDirector::ConfigDirectorClient mode="streaming" ready=true closed=false></tt>. The mode of the
284
+ # client of a {Testing::TestClient} is +"test"+. It never shows the server SDK key.
285
+ def inspect
286
+ "#<#{self.class.name} mode=#{@mode.inspect} ready=#{ready?} closed=#{closed?}>"
287
+ end
288
+
289
+ private
290
+
291
+ def raise_if_closed
292
+ return unless closed?
293
+
294
+ raise ConfigDirectorValidationError,
295
+ "This client has been closed and can no longer be used. Create a new one instead."
296
+ end
297
+
298
+ def warn_unless_the_first_values_arrive_by(give_up_at)
299
+ return unless @serving_state.timed_out_waiting_for_the_first_values?(give_up_at)
300
+
301
+ @client_connection.warn_that_no_values_arrived_within(@timeout)
302
+ end
303
+
304
+ def config_reader_over(telemetry)
305
+ Internal::Client::ConfigReader.new(
306
+ serving_state: @serving_state, event_handlers: @event_handlers, telemetry: telemetry, log: @log
307
+ )
308
+ end
309
+
310
+ def client_connection_over(connection, telemetry)
311
+ intake = Internal::Client::ConnectionIntake.new(
312
+ serving_state: @serving_state, event_handlers: @event_handlers, watches: @watches,
313
+ config_reader: @config_reader, log: @log
314
+ )
315
+
316
+ Internal::Client::ClientConnection.new(
317
+ connection: connection, telemetry: telemetry, mode: @mode, serving_state: @serving_state, intake: intake,
318
+ log: @log, lifecycle: @connection_lifecycle
319
+ )
320
+ end
321
+ end
322
+ end
@@ -0,0 +1,10 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ # What the +config_evaluated+ handlers receive each time a config is evaluated, before the read returns.
5
+ # Two events with the same evaluation are equal.
6
+ #
7
+ # @!attribute [r] evaluation
8
+ # @return [ConfigEvaluation] the evaluation the read returned
9
+ ConfigEvaluatedEvent = Data.define(:evaluation)
10
+ end
@@ -0,0 +1,51 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ ConfigEvaluation = Data.define(:key, :value, :default_value, :reason, :value_id, :variation, :context)
5
+
6
+ # One evaluation of a config: the value it returned, why, and the context it was evaluated for. Two
7
+ # evaluations with the same values are equal.
8
+ #
9
+ # @!attribute [r] key
10
+ # @return [String] the config key that was evaluated
11
+ # @!attribute [r] value
12
+ # @return [Boolean, String, Integer, Float, Hash, Array] the value returned, which is the in-code
13
+ # default value when {#default_value?} is +true+
14
+ # @!attribute [r] reason
15
+ # @return [String] why the evaluation returned this value. +"found-match"+ returns a value from
16
+ # ConfigDirector. +"rollout-skipped-no-identifier"+ returns the default targeting rule value: a
17
+ # percentage rollout was skipped because the context has no +id+ to place it in a share, and no rule
18
+ # after the rollout applied. Every other reason returns the in-code default value: the config has no
19
+ # value (+"value-missing"+), no config has the key (+"config-state-missing"+), no values have arrived
20
+ # yet or the client is closed (+"client-not-ready"+), or the value cannot be read as the class of the
21
+ # in-code default value (+"type-mismatch"+, +"invalid-number"+, +"invalid-json"+,
22
+ # +"invalid-boolean"+).
23
+ # @!attribute [r] value_id
24
+ # @return [String, nil] the ID ConfigDirector assigned to the value returned, when it sent one. It is
25
+ # +nil+ when the in-code default value is returned.
26
+ # @!attribute [r] variation
27
+ # @return [Variation, nil] the variation served, or +nil+ when the config has no variations or the
28
+ # in-code default value is returned
29
+ # @!attribute [r] context
30
+ # @return [Context, nil] the context the config was evaluated for, or +nil+ when none was given or it
31
+ # was ignored for an invalid kind
32
+ class ConfigEvaluation
33
+ # @param key [String] the config key that was evaluated
34
+ # @param value [Boolean, String, Integer, Float, Hash, Array] the value returned
35
+ # @param default_value [Boolean] whether the value returned is the in-code default value
36
+ # @param reason [String] why the evaluation returned this value
37
+ # @param value_id [String, nil] the ID ConfigDirector assigned to the value returned
38
+ # @param variation [Variation, nil] the variation served
39
+ # @param context [Context, nil] the context the config was evaluated for
40
+ def initialize(key:, value:, default_value:, reason:, value_id: nil, variation: nil, context: nil)
41
+ super
42
+ end
43
+
44
+ # @return [Boolean] whether the evaluation returned the in-code default value
45
+ def default_value?
46
+ default_value
47
+ end
48
+
49
+ private :default_value
50
+ end
51
+ end
@@ -0,0 +1,39 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ ConfigState = Data.define(:id, :key, :type, :value, :value_id, :variation, :rule_id, :share_id)
5
+
6
+ # What a config serves to a context, before its value is read as a Ruby value. Two states with the same
7
+ # values are equal.
8
+ #
9
+ # @!attribute [r] id
10
+ # @return [String] the config's ID
11
+ # @!attribute [r] key
12
+ # @return [String] the config key
13
+ # @!attribute [r] type
14
+ # @return [String] the config's type, such as +"boolean"+, +"string"+, +"integer"+, +"float"+,
15
+ # +"enum"+, +"url"+ or +"json"+
16
+ # @!attribute [r] value
17
+ # @return [String, nil] the value served, as text
18
+ # @!attribute [r] value_id
19
+ # @return [String, nil] the ID ConfigDirector assigned to the value served, when it sent one
20
+ # @!attribute [r] variation
21
+ # @return [Variation, nil] the variation served, or +nil+ when the config has no variations
22
+ # @!attribute [r] rule_id
23
+ # @return [String, nil] the ID of the percentage rollout's targeting rule, when a rollout served the value
24
+ # @!attribute [r] share_id
25
+ # @return [String, nil] the ID of the percentage rollout's share, when a rollout served the value
26
+ class ConfigState
27
+ # @param id [String] the config's ID
28
+ # @param key [String] the config key
29
+ # @param type [String] the config's type
30
+ # @param value [String, nil] the value served, as text
31
+ # @param value_id [String, nil] the ID ConfigDirector assigned to the value served
32
+ # @param variation [Variation, nil] the variation served
33
+ # @param rule_id [String, nil] the ID of the percentage rollout's targeting rule
34
+ # @param share_id [String, nil] the ID of the percentage rollout's share
35
+ def initialize(id:, key:, type:, value:, value_id: nil, variation: nil, rule_id: nil, share_id: nil)
36
+ super
37
+ end
38
+ end
39
+ end
@@ -0,0 +1,23 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ ConfigsUpdatedEvent = Data.define(:keys, :removed_keys)
5
+
6
+ # What the +configs_updated+ handlers receive each time the client receives values from ConfigDirector,
7
+ # the first time included. Two events with the same keys are equal.
8
+ #
9
+ # @!attribute [r] keys
10
+ # @return [Array<String>] the keys of the configs the client received, in the order ConfigDirector sent
11
+ # them, followed by the configs whose targeting rules use a segment the client received
12
+ # @!attribute [r] removed_keys
13
+ # @return [Array<String>] the keys of the configs the client no longer serves, because the values it
14
+ # received left them out or because it could not read their new definition, in the order the client
15
+ # had them. It is empty when nothing was removed.
16
+ class ConfigsUpdatedEvent
17
+ # @param keys [Array<String>] the keys of the configs the client received
18
+ # @param removed_keys [Array<String>] the keys of the configs the client no longer serves
19
+ def initialize(keys:, removed_keys:)
20
+ super(keys: Internal::UnchangeableCopy.of(keys), removed_keys: Internal::UnchangeableCopy.of(removed_keys))
21
+ end
22
+ end
23
+ end
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ # What the +connection_error+ handlers receive when ConfigDirector refuses the connection and the client
5
+ # will not try again. Two events with the same error are equal.
6
+ #
7
+ # @!attribute [r] error
8
+ # @return [ConfigDirectorConnectionError] why the connection failed. Its +status+ is the HTTP status
9
+ # ConfigDirector answered with.
10
+ ConnectionErrorEvent = Data.define(:error)
11
+ end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ ConnectionOptions = Data.define(:mode, :polling_interval, :timeout, :url, :file, :values)
5
+
6
+ # How a client connects to ConfigDirector. Connection options cannot be changed once built, compare by value,
7
+ # and +with+ builds a copy with other values.
8
+ #
9
+ # @!attribute [r] mode
10
+ # @return [String] the connection mode: +"streaming"+, +"polling"+ or +"offline"+
11
+ # @!attribute [r] polling_interval
12
+ # @return [Integer, Float] how often a polling client asks for new values, in seconds
13
+ # @!attribute [r] timeout
14
+ # @return [Integer, Float] how long {ConfigDirectorClient#init} waits for the first values, in seconds. In
15
+ # polling mode it is also how long each request for values may take. It has no effect in offline mode.
16
+ # @!attribute [r] url
17
+ # @return [String] the base URL of the ConfigDirector SDK server
18
+ # @!attribute [r] file
19
+ # @return [String, Pathname, nil] the path of a JSON file holding the values an offline client serves
20
+ # @!attribute [r] values
21
+ # @return [Hash, nil] the values an offline client serves, keyed by config key, as they were given
22
+ class ConnectionOptions
23
+ # @param mode [String] the connection mode. With +"streaming"+, the default, the connection stays open
24
+ # and receives a new value as soon as it changes in ConfigDirector. With +"polling"+, the client asks
25
+ # for new values every +polling_interval+. With +"offline"+, the client never connects to
26
+ # ConfigDirector, needs no server SDK key, and serves the values of +file+ or +values+ to every context,
27
+ # without applying targeting rules.
28
+ # @param polling_interval [Integer, Float] how often a polling client asks for new values, in seconds. Defaults
29
+ # to 300 seconds. The minimum is 60 seconds: in polling mode a lower value is raised to 60 and a warning
30
+ # is logged.
31
+ # @param timeout [Integer, Float] how long {ConfigDirectorClient#init} waits for the first values, in seconds.
32
+ # Defaults to 3 seconds. In polling mode it is also how long each request for values may take. It has no
33
+ # effect in offline mode.
34
+ # @param url [String] the base URL of the ConfigDirector SDK server. Change it only to connect through
35
+ # a proxy.
36
+ # @param file [String, Pathname, nil] the path of a JSON file holding the values to serve in offline mode,
37
+ # one value per config key, such as <tt>{"new-checkout": true, "max-items": 20}</tt>. A relative path is
38
+ # resolved against the working directory. {ConfigDirectorClient#init} reads the file each time it is
39
+ # called, and reads never read it. Only one of +file+ and +values+ can be given, and only in offline mode.
40
+ # @param values [Hash, nil] the values to serve in offline mode, keyed by config key, such as
41
+ # <tt>{ "new-checkout": true, "max-items": 20 }</tt>. A key is a String or a Symbol, and a Symbol is read
42
+ # as its name. The config type of each value follows from its class: +true+ or +false+ is a boolean, an
43
+ # Integer an integer, a Float a float, a String a string, and a Hash or an Array a JSON config, which can
44
+ # hold +nil+. Only one of +file+ and +values+ can be given, and only in offline mode.
45
+ def initialize(
46
+ mode: "streaming",
47
+ polling_interval: 300,
48
+ timeout: 3,
49
+ url: "https://server-sdk-api.configdirector.com",
50
+ file: nil,
51
+ values: nil
52
+ )
53
+ super(
54
+ mode: Internal::UnchangeableCopy.of(mode), polling_interval: polling_interval, timeout: timeout,
55
+ url: Internal::UnchangeableCopy.of(url), file: Internal::UnchangeableCopy.of(file),
56
+ values: Internal::UnchangeableCopy.of(values)
57
+ )
58
+ end
59
+ end
60
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ Context = Data.define(:id, :kind, :name, :traits, :anonymous)
5
+
6
+ # The user or other entity, such as a device or an organization, that a config is evaluated for. A context
7
+ # cannot be changed once built, two contexts built with the same values are equal, and +with+ builds a copy
8
+ # with other values, read and checked as +new+ reads and checks them.
9
+ #
10
+ # @!attribute [r] id
11
+ # @return [String, nil] the context's identifier
12
+ # @!attribute [r] kind
13
+ # @return [String, nil] the kind of entity the context represents, or +nil+ for +"user"+
14
+ # @!attribute [r] name
15
+ # @return [String, nil] the context's display name
16
+ # @!attribute [r] traits
17
+ # @return [Hash, nil] the context's traits, with every Symbol key and value read as its text
18
+ class Context
19
+ # @param id [String, Integer, nil] the context's identifier, which should identify the user or other
20
+ # entity among contexts of the same kind. An Integer, such as the ID of a database record, is read as
21
+ # its digits. A percentage rollout places a context in a share by its +id+, so a context without one
22
+ # skips percentage rollouts.
23
+ # @param kind [String, nil] the kind of entity the context represents, such as +"device"+,
24
+ # +"organization"+ or +"tenant"+. Leaving it out means +"user"+. A kind has 1 to 64 characters, using
25
+ # only lowercase letters (+a+ to +z+), digits, +-+ and +_+. Building a context never fails because of
26
+ # its kind: when the kind is invalid, the SDK ignores the whole context, evaluates as if no context
27
+ # was given and logs an error.
28
+ # @param name [String, nil] the context's display name, shown in the ConfigDirector dashboard
29
+ # @param traits [Hash, nil] any traits of the context, shown in the ConfigDirector dashboard. Targeting
30
+ # rules can use them. A Symbol key or value is read as its text, so +{ plan: :pro }+ is the trait
31
+ # +"plan"+ with the value +"pro"+.
32
+ # @param anonymous [Boolean] whether the context is anonymous. An anonymous context is used to evaluate
33
+ # targeting rules, is not kept and does not appear in the dashboard.
34
+ # @raise [ConfigDirectorValidationError] when +id+ is not a String or an Integer, +name+ is not a
35
+ # String, +traits+ is not a Hash or is nested deeper than 100 levels, as a Hash or an Array that holds
36
+ # itself is, or +anonymous+ is neither +true+ nor +false+
37
+ def initialize(id: nil, kind: nil, name: nil, traits: nil, anonymous: false)
38
+ super(
39
+ id: Internal::Client::ContextAttributes.identifier_text(id), kind: Internal::UnchangeableCopy.of(kind),
40
+ name: Internal::Client::ContextAttributes.name_text(name),
41
+ traits: Internal::Client::ContextAttributes.traits_with_symbols_as_text(traits),
42
+ anonymous: Internal::Client::ContextAttributes.anonymous_flag(anonymous)
43
+ )
44
+ end
45
+
46
+ # @return [Boolean] whether the context is anonymous
47
+ def anonymous?
48
+ anonymous
49
+ end
50
+
51
+ private :anonymous
52
+ end
53
+ end
@@ -0,0 +1,29 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ # The base class of every error the ConfigDirector SDK raises.
5
+ class ConfigDirectorError < StandardError; end
6
+
7
+ # Raised when the SDK is given something it cannot use, such as a missing server SDK key or a +nil+
8
+ # in-code default value.
9
+ class ConfigDirectorValidationError < ConfigDirectorError; end
10
+
11
+ # Raised by {ConfigDirectorClient#init} in offline mode when the offline values file cannot be read, is not
12
+ # UTF-8 text, is not valid JSON, is not a JSON object, or holds a value the SDK cannot serve.
13
+ class ConfigDirectorInitializationError < ConfigDirectorError; end
14
+
15
+ # Describes a failure to get values from ConfigDirector. A +connection_error+ handler receives it in a
16
+ # {ConnectionErrorEvent}.
17
+ class ConfigDirectorConnectionError < ConfigDirectorError
18
+ # @return [Integer, nil] the HTTP status ConfigDirector answered with, or +nil+ when there was no answer
19
+ attr_reader :status
20
+
21
+ # @param message [String, nil] what failed
22
+ # @param status [Integer, nil] the HTTP status ConfigDirector answered with, or +nil+ when there was no
23
+ # answer
24
+ def initialize(message = nil, status: nil)
25
+ super(message)
26
+ @status = status
27
+ end
28
+ end
29
+ end