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
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: c5edd716741436fa09a7f0763042d713b98655459fb41e01e12b2ddc9b7196dd
4
+ data.tar.gz: 7478b8dc66b1343cdff1e6ed65b5596bfaaaba033bfca598425e58b1d6395bf8
5
+ SHA512:
6
+ metadata.gz: 55057626d4e36643351c61aea913c3c318ff233692c0615899f9765099f6a5b10d00cd9a7c1706a61bde14fe50f303968ea5121256d0403c067969339f386229
7
+ data.tar.gz: 8985a44e056da83dca9e792804f0bc8868b518ce79b170bddd858e1582329a658933884427c6221bfbb1150c160fb00aba8216fbdac34e10c1ff2b871769cab1
data/.yardopts ADDED
@@ -0,0 +1,2 @@
1
+ --hide-api private
2
+ lib/**/*.rb
data/CHANGELOG.md ADDED
@@ -0,0 +1,254 @@
1
+ # Changelog
2
+
3
+ All notable changes to `configdirector-server-sdk` are recorded here.
4
+
5
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the gem uses
6
+ [semantic versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] - 2026-11-16
11
+
12
+ ### Added
13
+
14
+ - `ConfigDirector.create_client(server_sdk_key, metadata:, connection:, logger:, log_level:, telemetry:, hooks:)`
15
+ creates a `ConfigDirector::ConfigDirectorClient` without making a network call. It raises
16
+ `ConfigDirectorValidationError` when the server SDK key is missing or blank, `connection.url` is not an
17
+ http or https URL, `connection.timeout` is not a positive number, or `connection.file` or `connection.values`
18
+ is given, all outside offline mode only; when `connection.mode` is not `"streaming"`, `"polling"` or
19
+ `"offline"`; when `telemetry.flush_interval` is not a positive number; when `connection.timeout` or
20
+ `connection.polling_interval` is not a number; when `telemetry.event_queue_limit` is not a whole number from
21
+ 100 to 100,000; when an option is not an object of its option class; when the `logger` lacks `debug`, `info`,
22
+ `warn` or `error`; or when `log_level` is not a level of Ruby's `Logger` and no `logger` is given.
23
+ - The option objects `Metadata` (`app_name`, `app_version`), `ConnectionOptions` (`mode`, `polling_interval`,
24
+ `timeout`, `url`, `file`, `values`), `TelemetryOptions` (`event_queue_limit`, `flush_interval`) and
25
+ `ClientHooks` (`client_ready`, `configs_updated`, `config_evaluated`, `connection_error`). Every duration is in
26
+ seconds. In polling mode a `polling_interval` below 60 seconds is
27
+ raised to 60 and a warning is logged. An `app_name` or `app_version` that is not a String, such as the build
28
+ number `2`, is read as its text, `"2"`. An option object cannot be changed once built.
29
+ - The client connects to ConfigDirector at `connection.url`. In `"streaming"` mode, the default, it keeps a
30
+ connection open and receives a new value as soon as it changes in ConfigDirector, and it reconnects by itself
31
+ when the connection drops. In `"polling"` mode it asks for new values every `polling_interval`, and
32
+ `connection.timeout` is also how long each of those requests may take.
33
+ - In `"offline"` mode the client needs no server SDK key, never connects to ConfigDirector and sends nothing,
34
+ and serves one value per config key to every context, without applying targeting rules. The values are given
35
+ inline as `connection.values`, such as `{ "new-checkout": true, "max-items": 20 }`, or as `connection.file`, the
36
+ path of a JSON object of config key to value, given as a String or a Pathname and resolved against the working
37
+ directory. With neither, every read returns its in-code default value with the reason
38
+ `"config-state-missing"`. `connection.timeout` has no effect, and zero or less is accepted.
39
+ - The config type of an offline value follows from its class: `true` or `false` is a boolean, an Integer an
40
+ integer, a Float a float written as plain decimal text (`25.0` as `25`, `1.0e-7` as `0.0000001`), a String a
41
+ string, and a Hash or an Array a JSON config in compact JSON, which can hold `nil`. A key is a String or a
42
+ Symbol, and a Symbol, in the values or in a Hash inside a JSON value, is read as its name. A String in another
43
+ encoding is converted to UTF-8, and a binary String whose bytes are UTF-8 text is read as that text. A served
44
+ offline value has the reason `"found-match"`, no value ID and no variation, and its config ID is `offline:`
45
+ followed by the key.
46
+ - `create_client` raises `ConfigDirectorValidationError` when `connection.file` and `connection.values` are both
47
+ given, when `connection.values` is not a Hash, or when `connection.file` is neither a String nor a Pathname. It
48
+ raises it too when the values hold a key that is blank, of another class, not UTF-8 text, or given twice, such
49
+ as a String and a Symbol with the same name, or a value the SDK cannot serve: `nil`, a Float that is not finite,
50
+ a String that is not UTF-8 text, or an object of another class, such as a Symbol or a Time. A JSON value can
51
+ hold `nil`, and the same rules apply to every value and Hash key inside it. A JSON value nested deeper than 100
52
+ levels is rejected, and so is one that holds itself.
53
+ - In offline mode `init` reads the file again each time it is called, and reads never read it. Each `init` calls
54
+ the `configs_updated` handlers with every key the values hold and, in `removed_keys`, the keys the file no
55
+ longer holds, then their watches, and the `client_ready` handlers the first time the client becomes ready. An
56
+ `init` that a handler calls during an `init` returns at once. An offline client starts no thread, and in a
57
+ forked process it serves its values with nothing to restart.
58
+ - `ConfigDirectorInitializationError` extends `ConfigDirectorError`. In offline mode `init` raises it, and logs
59
+ nothing, when the file cannot be read, is not UTF-8 text, is not valid JSON, is not a JSON object, or holds a
60
+ value the SDK cannot serve. A client that was not ready stays not ready, and one that was ready keeps serving
61
+ the values it had and stays ready.
62
+ - `init` connects and makes the client ready. It waits, up to `connection.timeout`, for the first values and for
63
+ their handlers and watches to finish. When no values arrive in time it logs a warning and returns, and the
64
+ client keeps trying. It never raises because the connection failed. `ready?` says whether the client has
65
+ values to serve. Calling `init` again waits again and never opens a second connection.
66
+ - When ConfigDirector refuses the connection, for example because it does not know the server SDK key, the client
67
+ logs an error, calls the `connection_error` handlers once and does not try again. An `init` that is waiting
68
+ returns at once, without the warning, and so does a later `init`. A client that was ready keeps serving the
69
+ values it has.
70
+ - In polling mode, `init` returns as soon as the first request for values has failed, with the failure logged as
71
+ an error, and the client asks again after the polling interval.
72
+ - A config or segment whose definition the SDK cannot read is skipped with a warning, and every other config is
73
+ served. A read of a skipped config returns its in-code default value with the reason `"config-state-missing"`,
74
+ and a client that served the config before names it in the `removed_keys` of `configs_updated`. Fields the SDK
75
+ does not know are ignored.
76
+ - `get_value(config_key, default_value, context)` returns a config's value as the class of the in-code
77
+ default value: `true` or `false`, a String, an Integer, a Float, a Hash for a JSON object or an Array for a
78
+ JSON array. An Integer read accepts a whole number written as `26.0` or `1e3`. A `nil` in-code default
79
+ value, or one of any other class, raises `ConfigDirectorValidationError`. A config key that is blank or
80
+ not a String reads as a config that does not exist.
81
+ - `evaluate(...)` takes the same arguments and returns a `ConfigEvaluation` with `key`, `value`, `value_id`,
82
+ `variation` (a `Variation` with `id` and `name`), `default_value?`, `reason` and `context`.
83
+ - The evaluation reasons, with the text every ConfigDirector SDK uses: `"found-match"`,
84
+ `"rollout-skipped-no-identifier"`, `"config-state-missing"`, `"client-not-ready"`, `"type-mismatch"`,
85
+ `"value-missing"`, `"invalid-number"`, `"invalid-json"` and `"invalid-boolean"`. Every reason but the first
86
+ two returns the in-code default value.
87
+ - `Context.new(id:, kind:, name:, traits:, anonymous:)` is the user or other entity a config is evaluated
88
+ for, and cannot be changed once built. An Integer `id` is read as its digits, and a Symbol key or value in
89
+ `traits` is read as its text, so `{ plan: :pro }` is the trait `"plan"` with the value `"pro"`. Any other
90
+ class for `id` or `name`, `traits` that are not a Hash, or an `anonymous` that is neither `true` nor
91
+ `false` raises `ConfigDirectorValidationError`. So do `traits` nested deeper than 100 levels, which a Hash or
92
+ an Array that holds itself is. A read given a context that is not a `Context`, such as a Hash, raises it too.
93
+ - A context whose `kind` is not 1 to 64 characters of lowercase letters, digits, `-` and `_` is ignored
94
+ whole: the config is evaluated as if no context was given, the evaluation's `context` is `nil`, and an
95
+ error is logged once for each invalid kind until the client next sends its telemetry. A client that reports
96
+ every `telemetry.flush_interval` logs a kind that keeps being given about once per interval. After 20
97
+ different invalid kinds a client logs one more error and then no longer logs them until that report is sent.
98
+ An offline client and the client of a test client, which send no telemetry, log the error on every read.
99
+ - `get_all_configs(context:, config_keys:)` returns a `ConfigState` for every config, or for the listed
100
+ config keys, keyed by config key. It is empty until the client is ready. A `ConfigState` has `id`, `key`,
101
+ `type`, `value` (the served text), `value_id`, `variation`, `rule_id` and `share_id`. `config_keys` that
102
+ are not an Array raise `ConfigDirectorValidationError`.
103
+ - The client reports what it evaluates to ConfigDirector, which shows it as activity in the dashboard and counts
104
+ the exposures of experiments from it. Each `get_value`, `evaluate` and watch delivery is one evaluation, reads
105
+ that return the in-code default value included, and identical evaluations are sent once with their count.
106
+ `get_all_configs` and reads after `close` are not reported. A context that has an `id` and is not anonymous is
107
+ sent with its `name` and `traits`, once per report. A context with an invalid kind is only counted, with a
108
+ sample of its kind and nothing else of it.
109
+ - The first `init` starts a thread of the SDK that sends the first report 5 seconds later and then one every
110
+ `telemetry.flush_interval`, 30 seconds unless given. A client that was created and never initialized starts no
111
+ thread and keeps what it evaluated until `init` or `close`. Between two reports the client holds at most
112
+ `telemetry.event_queue_limit` events, 5,000 unless given: evaluations up to 70% of it and contexts up to 30%.
113
+ Beyond that it drops the oldest and reports how many it dropped. An offline client reports nothing.
114
+ - `close` sends what the client evaluated since its last report before it returns. It waits up to 5 seconds for
115
+ ConfigDirector to answer, and up to 5 more when a report was already being sent. The SDK registers no exit hook,
116
+ so a process that exits without calling `close` does not report its last reads.
117
+ - When ConfigDirector refuses a report with a status from 400 to 499 other than 413 and 429, for example because
118
+ it does not know the server SDK key, the client logs a warning and collects and sends no more telemetry. A report
119
+ that fails any other way is logged as a warning and discarded, and the next one is sent on time. No report is
120
+ sent twice.
121
+ - In a forked process, a client that starts its own connection there also reports from there what that process
122
+ evaluates, with its first report 5 seconds after the fork. What was evaluated before the fork is reported once,
123
+ by the parent. After `Process.daemon`, where the original process ends at once, such a client reports what was
124
+ evaluated before it from the process `Process.daemon` leaves.
125
+ - `track(event_name, context = nil, value: nil, details: nil)` reports to ConfigDirector that something happened,
126
+ such as a completed checkout, so experiments can count it. The event is sent with the next report, with the time
127
+ of the call, and `close` sends the events tracked since the last one. `track` returns `nil`, never raises, and
128
+ does nothing in offline mode or once the client is closed. A Symbol name is read as its name. The context's kind
129
+ and `id` are sent when it has an `id` and is not anonymous, and it is not added to the reported contexts. A
130
+ context with an invalid kind is logged and counted as for a read, and the event is sent without it; a context
131
+ that is not a `Context` drops the event with a warning.
132
+ - An event whose name does not have 1 to 150 characters is dropped, and so are the events beyond the first 1,000
133
+ of a report. A `value` is sent when it is a finite Float or an Integer no larger than the largest Float, and
134
+ left out otherwise. `details` are left out when they are not a Hash, have more than 20 top-level keys, are
135
+ larger than 1,024 bytes as JSON, are nested deeper than 100 levels, or hold anything but Strings, numbers,
136
+ `true`, `false`, `nil`, Symbols, Times and Arrays and Hashes of them with String or Symbol keys. A Symbol is
137
+ sent as its name, a Time as its ISO 8601 text in UTC, and a Float that is not finite as `null`. The event is
138
+ still sent without what was left out. Each of these logs one warning per report.
139
+ - `close` can be called more than once, and `closed?` says whether it was. Afterwards the client is not
140
+ ready, every read returns its in-code default value with the reason `"client-not-ready"`,
141
+ `get_all_configs` is empty, and `init` raises `ConfigDirectorValidationError`.
142
+ - `logger:` takes any object with the `debug`, `info`, `warn` and `error` methods of Ruby's `Logger`, such as
143
+ `Rails.logger`, and calls each with one String. It writes no debug line through a logger whose `debug?`
144
+ is false. Without a logger the SDK writes warnings and errors to standard error, and `log_level:` takes a
145
+ level as Ruby's `Logger` does, such as `:debug`, to write more or less. `log_level:` has no effect when a
146
+ `logger:` is given.
147
+ - `ConfigDirectorError` is the base class of every error the SDK raises, and `ConfigDirectorValidationError`
148
+ extends it.
149
+ - `ConfigDirectorConnectionError` extends `ConfigDirectorError` and describes a failure to get values from
150
+ ConfigDirector. Its `status` is the HTTP status ConfigDirector answered with, or `nil` when there was no
151
+ answer, and it is built as `ConfigDirectorConnectionError.new(message, status: 401)`. It is the `error` of the
152
+ `ConnectionErrorEvent` a `connection_error` handler receives.
153
+ - `on(event_name, handler)` registers a handler for one of four events, `:client_ready`, `:configs_updated`,
154
+ `:config_evaluated` and `:connection_error`, and returns a `Subscription`. The handler is a block or any object
155
+ that responds to `call`, such as a lambda or `method(:name)`, and a handler registered twice runs twice. Any
156
+ other event name, a String such as `"configs_updated"` included, raises `ConfigDirectorValidationError`, as do a
157
+ handler and a block given together, neither of them, or a handler that does not respond to `call`.
158
+ - `off(event_name, handler)` removes the first registration of a handler equal to `handler`, so `method(:name)`
159
+ finds a handler registered as `method(:name)`, or every handler of the event, hooks included, when `handler` is
160
+ left out.
161
+ - `client_ready` handlers are called with no argument once, when the client first receives values and becomes
162
+ ready. `configs_updated` handlers receive a `ConfigsUpdatedEvent` each time the client receives values: its
163
+ `keys` are the configs received, in the order ConfigDirector sent them, followed by the configs whose targeting
164
+ rules use a segment that was received, and its `removed_keys` the configs the client no longer serves because
165
+ the values received left them out. `config_evaluated` handlers receive a `ConfigEvaluatedEvent` with the
166
+ `evaluation` of every `get_value`, `evaluate` and watch, before the read returns; `get_all_configs` calls none
167
+ of them. `connection_error` handlers receive a `ConnectionErrorEvent` with the `error`.
168
+ - `ClientHooks.new(client_ready:, configs_updated:, config_evaluated:, connection_error:)` takes one handler or an
169
+ Array of handlers per event. `create_client` registers them in the order given, before any handler registered
170
+ with `on`. An entry that does not respond to `call` is ignored and a warning is logged.
171
+ - `watch(config_key, default_value, context) { |value| ... }` calls the block with the config's value each time
172
+ the client receives values that include the config or a segment its targeting rules use, even when its value
173
+ is the same, and with the in-code default value when they leave it out. It never calls the block when the
174
+ watch is registered, so a watch registered before `init` receives the first value during it. It returns a
175
+ `Subscription`. A missing block, an in-code default value `get_value` would reject, or a context that is not
176
+ a `Context` raises `ConfigDirectorValidationError`.
177
+ - `unwatch(config_key, callback)` removes the first watch on the key whose block is `callback`, the same Proc or
178
+ lambda, or every watch on the key when `callback` is left out. `unwatch_all` removes every watch.
179
+ - `Subscription#close` removes the handler or watch it registered, and only that one, even when the same handler
180
+ or block was registered again. It can be called more than once, and `closed?` says whether it was.
181
+ - Each time the client receives values, the `configs_updated` handlers run first, then the watches on the keys
182
+ received and then on the keys removed, then the `client_ready` handlers when the client has just become ready.
183
+ They run on the thread that received the values: a thread of the SDK in streaming mode, and in polling mode
184
+ the thread that called `init` for the first request and a thread of the SDK for every later one. In offline
185
+ mode it is the thread that called `init`.
186
+ `connection_error` handlers run on those threads too, and `config_evaluated` handlers on the thread that read.
187
+ A handler or watch can read from the client.
188
+ - A handler or watch that raises a `StandardError` is logged at error level and ignored: the other handlers and
189
+ watches still run and the read still returns its value.
190
+ - `close` also removes every handler, hook and watch.
191
+ - `Context`, `Variation`, `ConfigState`, `ConfigEvaluation`, `ConfigsUpdatedEvent`, `ConfigEvaluatedEvent`,
192
+ `ConnectionErrorEvent`, `Testing::TrackedEvent` and the option objects are Ruby `Data` objects: they compare by
193
+ value with `==`, cannot be changed once built, and offer `with`, which checks the new values as `new` does,
194
+ `to_h` and pattern matching, such as `case evaluation in { reason: "found-match" }`.
195
+ Whether a context is anonymous is read with `anonymous?`, and whether an evaluation returned the in-code default
196
+ value with `default_value?`.
197
+ - `ConfigDirectorClient#inspect` shows the connection mode and whether the client is ready and closed, such as
198
+ `#<ConfigDirector::ConfigDirectorClient mode="streaming" ready=true closed=false>`, with the mode `"test"` for the
199
+ client of a test client, and never the server SDK key; `pp` and the Rails console show the same.
200
+ - The RBS signatures in the gem type `get_value`, `evaluate` and the block of `watch` by the class of the in-code
201
+ default value, so a type checker such as Steep sees `get_value("new-checkout", false)` as a boolean and
202
+ `get_value("checkout-settings", {})` as a Hash with String keys. A Hash in-code default value with Symbol keys is
203
+ typed as a Hash with String or Symbol keys, since the read returns it as given when it falls back to it.
204
+ - A client on which `init` was called before the process forked, as under Puma in cluster mode, Unicorn or
205
+ Passenger, starts its own connection in the forked process by itself. It serves the values it was copied with at
206
+ once, and handlers and watches registered before the fork keep firing there. The parent's connection is not
207
+ affected. A client that was never initialized, was closed, was refused by ConfigDirector, or is offline does
208
+ nothing at a fork.
209
+ - A fork is safe at any moment: while values arrive, while a telemetry report is being sent, while another thread
210
+ is in `init`, and from a signal handler that interrupted a call into the client. The forked process starts its
211
+ connection on a thread of the SDK right after the fork, and `fork` does not wait for it.
212
+ - A process that a `configs_updated`, `client_ready` or `connection_error` handler or a watch forked without a
213
+ block, on a thread of the SDK, can read from the client inside that handler. It ends when the handler returns
214
+ in it, with exit status 0 and its `at_exit` hooks, as it would after the block of `fork { }`, and the parent
215
+ keeps receiving every update.
216
+ - A request for values in polling mode ends when `connection.timeout` has passed, and a telemetry report after 5
217
+ seconds, counted from before the connection opens, even while ConfigDirector keeps sending an answer that never
218
+ completes.
219
+ - The gem depends on `net-http` 0.10.0 or later, the first release that limits the head of an HTTP answer and
220
+ each chunk size line to 1 MiB, so an application's lock gains `net-http`, `net-protocol`, `timeout` and `uri`.
221
+ When an answer passes that limit, a stream reconnects, and a request for values in polling mode or a telemetry
222
+ report counts as one that failed.
223
+ - Values that hold a number of more than 16,384 digits are not read, and ConfigDirector stores no value that
224
+ long. Such a message of the stream is skipped with an error and the client keeps the values it has, such an
225
+ answer to a request for values in polling mode is a failed request, a JSON config with such a value returns
226
+ the in-code default value with the reason `"invalid-json"`, and an integer config with such a value returns it
227
+ with `"invalid-number"`.
228
+ - The error the client logs for a message of the stream that is not JSON says `it is not valid JSON` and never
229
+ repeats the message, so a message that repeats the server SDK key does not put it in the log.
230
+ - `require "configdirector/testing"` loads `ConfigDirector::Testing.create_test_client(values, timeout:, logger:)`,
231
+ which returns a `ConfigDirector::Testing::TestClient` for testing code that reads configs. Its `client` is the
232
+ SDK's real client over an in-memory connection the test controls: it needs no server SDK key, opens no network
233
+ connection, starts no thread and sends nothing. The values follow the offline typing rule, and every context
234
+ receives the same value as a `"found-match"` with no value ID and no variation, from a config whose ID is
235
+ `test-config:` followed by the key. `timeout` is how long a held `init` waits, 3 seconds unless given.
236
+ `create_test_client`, `set_value` and `replace_values` raise `ConfigDirectorValidationError` for values the SDK
237
+ cannot serve, changing nothing, and `create_test_client` raises it too for a timeout that is not a positive
238
+ number or a logger without the four methods.
239
+ - `TestClient#set_value(key, value)` delivers an update that carries only that key, and `remove_value(key)` and
240
+ `replace_values(values)` deliver a full update, before they return, with the handlers and watches run on the
241
+ calling thread; a change made while the client is not connected reaches it with the next `init`. A change made
242
+ from inside a handler or a watch is delivered right after the one being handled. `replace_values` also cancels a
243
+ hold or a failure that no `init` has used.
244
+ - `TestClient#hold_initialization` makes the next `init` wait until another thread calls `complete_initialization`,
245
+ which delivers the stored values on its own thread, or `fail_initialization`, or until the timeout, when `init`
246
+ logs the timeout warning and returns. `fail_initialization` fails a held `init`, or makes the next one fail: one
247
+ error is logged and the `connection_error` handlers receive a `ConfigDirectorConnectionError` of status 401, each
248
+ time, and then the failed `init` returns, at once when nothing held it. A client that was ready keeps serving its
249
+ values through a held or failed `init`.
250
+ - `TestClient#tracked_events` returns every event the code under test tracked through the client, in call order, as
251
+ `ConfigDirector::Testing::TrackedEvent` (`name`, `context`, `value`, `details`), which compares by value. It
252
+ follows the rules of a real report and logs each warning every time; the limit of 1,000 per report does not apply,
253
+ and nothing is recorded once the client is closed. The details are recorded as the SDK sends them, with String
254
+ keys. It is the same Array on every call and grows as events are tracked, so a test can empty it with `clear`.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ConfigDirector
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is furnished
10
+ to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,230 @@
1
+ # ConfigDirector Ruby SDK
2
+
3
+ [![CI][ci-badge]][ci] [![Gem Version][gem-badge]][gem]
4
+
5
+ Ruby server SDK for [ConfigDirector](https://www.configdirector.com), remote config and feature flags with JSON Schema validation and safe renames of live flags. Start free, no card required.
6
+
7
+ The SDK requires Ruby 3.3 or later.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ bundle add configdirector-server-sdk
13
+ ```
14
+
15
+ ## Retrieve a value
16
+
17
+ ```ruby
18
+ require "configdirector"
19
+
20
+ # The server SDK key is a secret. Do not commit it to your source code.
21
+ client = ConfigDirector.create_client(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY"))
22
+ client.init
23
+
24
+ new_checkout = client.get_value("new-checkout", false)
25
+ ```
26
+
27
+ Full details are in the [official documentation](https://docs.configdirector.com/sdks/server/ruby).
28
+
29
+ ## Servers that fork
30
+
31
+ Each Ruby process holds its own connection to ConfigDirector, on a thread of the SDK, so an application on 2 hosts with
32
+ 4 Puma workers each holds 8 connections. Puma in cluster mode, Passenger's smart spawning and Unicorn with `preload_app
33
+ true` load the application once and then fork their workers from that process. A client that was initialized before the
34
+ fork restarts by itself in each worker: it serves the values it had at the fork at once, opens its own connection and
35
+ keeps calling its handlers and watches, with nothing for your application to call.
36
+
37
+ Create the client the first time a process uses it rather than while the application boots, as the [Rails
38
+ sample](https://github.com/ConfigDirector/ruby-sdks/tree/main/samples/configdirector-server-sdk/rails) does. Then only a
39
+ process that reads a config connects: the Puma master and an image build that has no server SDK key never do, and
40
+ neither does a `bin/rails console` session or a Rake task until it reads one. The first request in each worker waits for
41
+ the first values, up to the connection timeout. The [documentation](https://docs.configdirector.com/sdks/server/ruby)
42
+ also says what an application that forks for each background job should do.
43
+
44
+ ## Test your code
45
+
46
+ `configdirector/testing` creates a **test client**: the SDK's real client over an in-memory connection that your test
47
+ controls. It opens no network connection, starts no thread and sends nothing. Set values, change them in the middle
48
+ of a test so watches and `configs_updated` handlers run, and hold or fail initialization to test what your code does
49
+ before values arrive. It ships in the gem, so there is nothing else to install.
50
+
51
+ ```ruby
52
+ require "configdirector/testing"
53
+
54
+ test_client = ConfigDirector::Testing.create_test_client({ "new-checkout" => true })
55
+ service = CheckoutService.new(test_client.client)
56
+ test_client.client.init
57
+
58
+ expect(service.new_checkout_enabled?("user-123")).to be(true)
59
+
60
+ test_client.set_value("new-checkout", false)
61
+ expect(service.new_checkout_enabled?("user-123")).to be(false)
62
+
63
+ test_client.client.close
64
+ ```
65
+
66
+ `test_client.client` is a `ConfigDirector::ConfigDirectorClient`, so it goes anywhere your code takes one. It starts
67
+ not ready, like a production client, because the code under test usually owns the call to `init`. Unless
68
+ initialization is held or set to fail, `init` serves the stored values at once. The test client has no `close` of its
69
+ own: close its client when the test ends.
70
+
71
+ ### Values
72
+
73
+ `create_test_client`, `set_value` and `replace_values` take Ruby values, and the config type follows from the class of
74
+ each value: `true` or `false` is a boolean config, an Integer an integer config, a Float a float config, a String a
75
+ string config, and a Hash or an Array a JSON config, which can hold `nil`. A key is a String or a Symbol, and a Symbol
76
+ is read as its name. A String is always a string config, so JSON text meant as a JSON config is given as
77
+ `JSON.parse(text)`. Every context receives the same value, as a match with no value ID and no variation, so a test that
78
+ needs different values for different contexts is written as one test per value. A value the SDK cannot serve, such as
79
+ `nil`, a Symbol or a Float that is not finite, raises `ConfigDirector::ConfigDirectorValidationError`, and so does a
80
+ blank key or a key of another class. Nothing changes then.
81
+
82
+ Reads behave as they do in production: `set_value("new-checkout", true)` read with a String in-code default value
83
+ returns that in-code default value with the reason `type-mismatch`, `set_value("max-items", 2.5)` read with an Integer
84
+ returns it with `invalid-number`, and `set_value("banner-text", "")` returns it with `value-missing`. The reason is on
85
+ the evaluation that `evaluate` returns and that `config_evaluated` handlers receive. A Hash keeps its order.
86
+
87
+ ### Controls
88
+
89
+ | Control | What it does |
90
+ | --- | --- |
91
+ | `set_value(key, value)` | Stores the value and, while the client is connected, delivers an update that carries only `key`. Reads, the watches of `key` and the `configs_updated` handlers see it before the call returns. |
92
+ | `remove_value(key)` | Removes the value and delivers a full update without it. Reads return the in-code default value with the reason `config-state-missing`, the watches of `key` receive that in-code default value, and `configs_updated` handlers find `key` in `removed_keys`. |
93
+ | `replace_values(values)` | Replaces every stored value, cancels a hold or a failure that no `init` has used yet, and delivers a full update. Use it to reset a test client shared between tests. |
94
+ | `hold_initialization` | The next `init` waits until another thread calls `complete_initialization` or `fail_initialization`, or until the timeout. `init` blocks, so a test calls it on another thread. |
95
+ | `complete_initialization` | Delivers the stored values to the held `init`, on the calling thread, so the client is ready when the call returns. The held `init` returns once the handlers and watches of those values have run. Called before `init` while a hold is set, it cancels the hold. |
96
+ | `fail_initialization` | Fails the held `init` the way a refused server SDK key does: the client is not ready, an error is logged and the `connection_error` handlers receive a `ConfigDirectorConnectionError` with the status 401, on the calling thread, and then the held `init` returns. Called while no `init` is held, it makes the next `init` fail, which then returns at once. |
97
+
98
+ The `init` after a failed one serves the stored values, the ones set in the meantime included. A change made while the
99
+ client is not connected, before `init` or after a held or failed one, is stored and reaches the client with the next
100
+ `init` that serves the values.
101
+
102
+ ### Tracked events
103
+
104
+ `test_client.tracked_events` holds every event the code under test tracked, in call order, as
105
+ `ConfigDirector::Testing::TrackedEvent` (`name`, `context`, `value`, `details`), so a test can assert on them:
106
+
107
+ ```ruby
108
+ require "configdirector/testing"
109
+
110
+ test_client = ConfigDirector::Testing.create_test_client
111
+ test_client.client.track("checkout-completed", ConfigDirector::Context.new(id: "user-123"), value: 49.9)
112
+
113
+ expect(test_client.tracked_events).to eq(
114
+ [
115
+ ConfigDirector::Testing::TrackedEvent.new(
116
+ name: "checkout-completed", context: ConfigDirector::Context.new(id: "user-123"), value: 49.9
117
+ )
118
+ ]
119
+ )
120
+ ```
121
+
122
+ The record follows the rules of a real report: an event whose name does not have 1 to 150 characters is not
123
+ recorded, and a value or details the SDK would leave out are missing from the record, with a warning logged each time.
124
+ The details are recorded as the SDK sends them, so their keys are Strings and a Time is its ISO 8601 text in UTC. The
125
+ limit of 1,000 events per report does not apply, and nothing is recorded once the client is closed. It is the same
126
+ Array on every call, so `test_client.tracked_events.clear` empties it.
127
+
128
+ ### Options
129
+
130
+ `create_test_client(values, timeout: nil, logger: nil)` takes `timeout`, in seconds, which is how long a held `init`
131
+ waits, 3 seconds unless given, as for a production client; and `logger`, any object with the methods of Ruby's
132
+ `Logger`, as `ConfigDirector.create_client` takes it. Without a logger the SDK writes warnings and errors to standard
133
+ error.
134
+
135
+ ### Module-level clients
136
+
137
+ An application that creates and initializes its client while it loads, in a Rails initializer for example, runs the
138
+ real client before any test can step in: the client opens a connection and starts a thread. Create the client the
139
+ first time a process uses it instead, as the
140
+ [Rails sample](https://github.com/ConfigDirector/ruby-sdks/tree/main/samples/configdirector-server-sdk/rails) does:
141
+
142
+ ```ruby
143
+ module ConfigDirectorClientPerProcess
144
+ @lock = Mutex.new
145
+ @client = nil
146
+
147
+ def self.client
148
+ @lock.synchronize do
149
+ @client ||= ConfigDirector.create_client(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY")).tap(&:init)
150
+ end
151
+ end
152
+ end
153
+ ```
154
+
155
+ The lock matters on a threaded server such as Puma: without it, two first requests arriving together each create and
156
+ initialize a client.
157
+
158
+ In your tests, make `ConfigDirector.create_client` return the test client's client before the application first uses
159
+ one, and forget the client after each example, so the next example creates its own:
160
+
161
+ ```ruby
162
+ RSpec.shared_context "with a test client" do
163
+ let(:test_client) { ConfigDirector::Testing.create_test_client({ "new-checkout" => true }) }
164
+
165
+ before { allow(ConfigDirector).to receive(:create_client).and_return(test_client.client) }
166
+
167
+ after do
168
+ test_client.client.close
169
+ ConfigDirectorClientPerProcess.instance_variable_set(:@client, nil)
170
+ end
171
+ end
172
+ ```
173
+
174
+ ### What to expect
175
+
176
+ - The first values are delivered while `init` runs, so watches registered before `init` run before it returns, and the
177
+ `configs_updated` handlers run before the `client_ready` handlers.
178
+ - Watches and handlers run on the thread that calls `set_value`, `remove_value`, `replace_values`,
179
+ `complete_initialization` or `init`, never on a thread of the SDK. A change made from inside a handler or a watch is
180
+ delivered right after the one being handled.
181
+ - A held `init` that reaches the timeout logs the SDK's timeout warning, and a client that was not ready stays not ready
182
+ until the next `init`. A client that was ready keeps serving its values through a later held or failed `init`, and
183
+ completing such an `init` calls no `client_ready` handler.
184
+ - Each failed `init` calls the `connection_error` handlers, where a client connected to ConfigDirector calls them at most
185
+ once.
186
+ - A `close` or an `init` called while an `init` is held, from another thread or from a handler that
187
+ `complete_initialization` or `fail_initialization` runs, returns once the held `init` returns.
188
+ - Watches run for every update that carries their key, whether or not the value changed, as in production.
189
+ `remove_value` and `replace_values` deliver a full update, so they also run the watches of every key left.
190
+ - A `StandardError` a watch or a handler raises is logged and does not reach the caller, as in production. An exception
191
+ that is not a `StandardError`, such as a failed RSpec expectation, reaches the call that delivered the change.
192
+ - After `close`, `ready?` is false, every read returns its in-code default value, `get_all_configs` returns an empty
193
+ Hash, `init` raises `ConfigDirectorValidationError`, every handler and watch has been removed, and the closed client
194
+ takes none of the values the test client's controls store.
195
+ - The SDK keeps no reference to a test client's client, so one that is never closed can be garbage collected. In a
196
+ forked process it keeps serving its values, with nothing to restart.
197
+
198
+ ## Documentation
199
+
200
+ Refer to the [official documentation for the Ruby SDK](https://docs.configdirector.com/sdks/server/ruby).
201
+
202
+ There is also [a quickstart guide for ConfigDirector and any of our SDKs](https://docs.configdirector.com/getting-started/quickstart).
203
+
204
+ ## Sample apps
205
+
206
+ [`samples/configdirector-server-sdk/`](https://github.com/ConfigDirector/ruby-sdks/tree/main/samples/configdirector-server-sdk)
207
+ holds small, runnable applications built on this SDK. Start with
208
+ [`rails`](https://github.com/ConfigDirector/ruby-sdks/tree/main/samples/configdirector-server-sdk/rails), a Rails
209
+ application served by Puma in cluster mode:
210
+
211
+ ```bash
212
+ cd samples/configdirector-server-sdk/rails
213
+ bundle install
214
+ bundle exec puma
215
+ ```
216
+
217
+ ## OpenFeature
218
+
219
+ To read flags through the [OpenFeature](https://openfeature.dev) API, use the [`configdirector-openfeature-server-provider`](https://github.com/ConfigDirector/ruby-sdks/tree/main/configdirector-openfeature-server-provider) gem, which is built on this SDK.
220
+
221
+ ## Getting Help
222
+
223
+ - [Ask a question in Discussions](https://github.com/orgs/ConfigDirector/discussions)
224
+ - [Contact support](https://www.configdirector.com/support)
225
+
226
+ [//]: # "links"
227
+ [ci-badge]: https://github.com/ConfigDirector/ruby-sdks/actions/workflows/ci.yml/badge.svg
228
+ [ci]: https://github.com/ConfigDirector/ruby-sdks/actions/workflows/ci.yml
229
+ [gem-badge]: https://img.shields.io/gem/v/configdirector-server-sdk
230
+ [gem]: https://rubygems.org/gems/configdirector-server-sdk
@@ -0,0 +1,46 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConfigDirector
4
+ ClientHooks = Data.define(:client_ready, :configs_updated, :config_evaluated, :connection_error)
5
+
6
+ # Handlers for the events a client emits, given to {ConfigDirector.create_client}. The client registers
7
+ # them as {ConfigDirectorClient#on} would, in the order given and before any handler registered with
8
+ # {ConfigDirectorClient#on}. Each event takes one handler or an Array of handlers, and a handler is any
9
+ # object that responds to +call+, such as a lambda or +method(:name)+. An entry that does not respond to
10
+ # +call+ is ignored and a warning is logged. Two hooks with the same handlers are equal, and +with+ builds a
11
+ # copy with other handlers.
12
+ #
13
+ # @example
14
+ # hooks = ConfigDirector::ClientHooks.new(
15
+ # client_ready: -> { puts "ConfigDirector is ready" },
16
+ # config_evaluated: ->(event) { puts "Evaluated #{event.evaluation.key}" }
17
+ # )
18
+ # client = ConfigDirector.create_client(ENV.fetch("CONFIGDIRECTOR_SERVER_KEY"), hooks: hooks)
19
+ #
20
+ # @!attribute [r] client_ready
21
+ # @return [#call, Array<#call>, nil] the +client_ready+ handlers, as given
22
+ # @!attribute [r] configs_updated
23
+ # @return [#call, Array<#call>, nil] the +configs_updated+ handlers, as given
24
+ # @!attribute [r] config_evaluated
25
+ # @return [#call, Array<#call>, nil] the +config_evaluated+ handlers, as given
26
+ # @!attribute [r] connection_error
27
+ # @return [#call, Array<#call>, nil] the +connection_error+ handlers, as given
28
+ class ClientHooks
29
+ # @param client_ready [#call, Array<#call>, nil] called with no argument once, when the client first
30
+ # receives values and becomes ready
31
+ # @param configs_updated [#call, Array<#call>, nil] called with a {ConfigsUpdatedEvent} each time the
32
+ # client receives values, the first time included
33
+ # @param config_evaluated [#call, Array<#call>, nil] called with a {ConfigEvaluatedEvent} each time a
34
+ # config is evaluated, before the read returns
35
+ # @param connection_error [#call, Array<#call>, nil] called with a {ConnectionErrorEvent} when
36
+ # ConfigDirector refuses the connection and the client will not try again
37
+ def initialize(client_ready: nil, configs_updated: nil, config_evaluated: nil, connection_error: nil)
38
+ super(
39
+ client_ready: Internal::UnchangeableCopy.of(client_ready),
40
+ configs_updated: Internal::UnchangeableCopy.of(configs_updated),
41
+ config_evaluated: Internal::UnchangeableCopy.of(config_evaluated),
42
+ connection_error: Internal::UnchangeableCopy.of(connection_error)
43
+ )
44
+ end
45
+ end
46
+ end