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.
- checksums.yaml +7 -0
- data/.yardopts +2 -0
- data/CHANGELOG.md +254 -0
- data/LICENSE +21 -0
- data/README.md +230 -0
- data/lib/configdirector/client_hooks.rb +46 -0
- data/lib/configdirector/config_director_client.rb +322 -0
- data/lib/configdirector/config_evaluated_event.rb +10 -0
- data/lib/configdirector/config_evaluation.rb +51 -0
- data/lib/configdirector/config_state.rb +39 -0
- data/lib/configdirector/configs_updated_event.rb +23 -0
- data/lib/configdirector/connection_error_event.rb +11 -0
- data/lib/configdirector/connection_options.rb +60 -0
- data/lib/configdirector/context.rb +53 -0
- data/lib/configdirector/errors.rb +29 -0
- data/lib/configdirector/internal/client/client_connection.rb +119 -0
- data/lib/configdirector/internal/client/client_factory.rb +104 -0
- data/lib/configdirector/internal/client/client_options_validation.rb +53 -0
- data/lib/configdirector/internal/client/config_read.rb +31 -0
- data/lib/configdirector/internal/client/config_reader.rb +55 -0
- data/lib/configdirector/internal/client/connection_intake.rb +59 -0
- data/lib/configdirector/internal/client/connection_options_validation.rb +94 -0
- data/lib/configdirector/internal/client/context_admission.rb +48 -0
- data/lib/configdirector/internal/client/context_attributes.rb +78 -0
- data/lib/configdirector/internal/client/context_kind.rb +24 -0
- data/lib/configdirector/internal/client/evaluated_read.rb +9 -0
- data/lib/configdirector/internal/client/event_handlers.rb +114 -0
- data/lib/configdirector/internal/client/event_tracking.rb +39 -0
- data/lib/configdirector/internal/client/live_client_connections.rb +58 -0
- data/lib/configdirector/internal/client/number_of_seconds.rb +21 -0
- data/lib/configdirector/internal/client/registrations.rb +43 -0
- data/lib/configdirector/internal/client/restart_in_forked_processes.rb +25 -0
- data/lib/configdirector/internal/client/served_configs.rb +83 -0
- data/lib/configdirector/internal/client/serving_state.rb +102 -0
- data/lib/configdirector/internal/client/watches.rb +51 -0
- data/lib/configdirector/internal/client/what_follows_a_fork.rb +24 -0
- data/lib/configdirector/internal/connection/condition_parser.rb +74 -0
- data/lib/configdirector/internal/connection/config_definition.rb +37 -0
- data/lib/configdirector/internal/connection/http_session.rb +15 -0
- data/lib/configdirector/internal/connection/in_memory_connection.rb +134 -0
- data/lib/configdirector/internal/connection/json_post_request.rb +24 -0
- data/lib/configdirector/internal/connection/not_a_server_sdk_payload.rb +9 -0
- data/lib/configdirector/internal/connection/offline_mode_connection.rb +96 -0
- data/lib/configdirector/internal/connection/offline_values_file.rb +49 -0
- data/lib/configdirector/internal/connection/payloads_delivered_in_turn.rb +46 -0
- data/lib/configdirector/internal/connection/polling_interval.rb +21 -0
- data/lib/configdirector/internal/connection/request_deadline.rb +45 -0
- data/lib/configdirector/internal/connection/retry_after_header.rb +24 -0
- data/lib/configdirector/internal/connection/server_sdk_payload.rb +37 -0
- data/lib/configdirector/internal/connection/server_sdk_payload_parser.rb +89 -0
- data/lib/configdirector/internal/connection/targeting_rules_parser.rb +70 -0
- data/lib/configdirector/internal/connection/test_client_initializations.rb +111 -0
- data/lib/configdirector/internal/connection/test_client_values.rb +53 -0
- data/lib/configdirector/internal/connection/unreadable_definition.rb +9 -0
- data/lib/configdirector/internal/connection/wire_fields.rb +59 -0
- data/lib/configdirector/internal/evaluation/array_comparison.rb +25 -0
- data/lib/configdirector/internal/evaluation/assigned_percentage.rb +21 -0
- data/lib/configdirector/internal/evaluation/attribute_condition.rb +48 -0
- data/lib/configdirector/internal/evaluation/config_evaluator.rb +29 -0
- data/lib/configdirector/internal/evaluation/datetime_comparison.rb +93 -0
- data/lib/configdirector/internal/evaluation/evaluation_context.rb +17 -0
- data/lib/configdirector/internal/evaluation/number_comparison.rb +119 -0
- data/lib/configdirector/internal/evaluation/rapidhash.rb +124 -0
- data/lib/configdirector/internal/evaluation/rollout_share.rb +9 -0
- data/lib/configdirector/internal/evaluation/rule.rb +70 -0
- data/lib/configdirector/internal/evaluation/scalar_text.rb +70 -0
- data/lib/configdirector/internal/evaluation/segment.rb +17 -0
- data/lib/configdirector/internal/evaluation/segment_condition.rb +26 -0
- data/lib/configdirector/internal/evaluation/semver_comparison.rb +49 -0
- data/lib/configdirector/internal/evaluation/served_value.rb +9 -0
- data/lib/configdirector/internal/evaluation/share.rb +9 -0
- data/lib/configdirector/internal/evaluation/targeting_rules.rb +18 -0
- data/lib/configdirector/internal/evaluation/text_comparison.rb +32 -0
- data/lib/configdirector/internal/evaluation/trait_pointer.rb +42 -0
- data/lib/configdirector/internal/evaluation.rb +21 -0
- data/lib/configdirector/internal/identity/sdk_identity.rb +39 -0
- data/lib/configdirector/internal/identity/wrapper.rb +48 -0
- data/lib/configdirector/internal/logging/client_log.rb +37 -0
- data/lib/configdirector/internal/logging/default_logger.rb +34 -0
- data/lib/configdirector/internal/polling/poll_answer.rb +111 -0
- data/lib/configdirector/internal/polling/poll_request.rb +106 -0
- data/lib/configdirector/internal/polling/poll_timing.rb +25 -0
- data/lib/configdirector/internal/polling/polling_endpoint.rb +36 -0
- data/lib/configdirector/internal/polling/polling_mode_connection.rb +53 -0
- data/lib/configdirector/internal/polling/polling_session.rb +99 -0
- data/lib/configdirector/internal/polling/polling_transport.rb +74 -0
- data/lib/configdirector/internal/polling/refusal_detail.rb +36 -0
- data/lib/configdirector/internal/server_sent_events/event_stream_limit_exceeded.rb +9 -0
- data/lib/configdirector/internal/server_sent_events/event_stream_parser.rb +95 -0
- data/lib/configdirector/internal/server_sent_events/server_sent_event.rb +9 -0
- data/lib/configdirector/internal/stoppable_thread.rb +69 -0
- data/lib/configdirector/internal/streaming/heartbeats.rb +51 -0
- data/lib/configdirector/internal/streaming/reconnecting_stream.rb +82 -0
- data/lib/configdirector/internal/streaming/reconnection_delay.rb +29 -0
- data/lib/configdirector/internal/streaming/stream_connection.rb +86 -0
- data/lib/configdirector/internal/streaming/stream_end.rb +69 -0
- data/lib/configdirector/internal/streaming/stream_endpoint.rb +43 -0
- data/lib/configdirector/internal/streaming/stream_timing.rb +33 -0
- data/lib/configdirector/internal/streaming/streaming_mode_connection.rb +60 -0
- data/lib/configdirector/internal/streaming/streaming_transport.rb +42 -0
- data/lib/configdirector/internal/telemetry/aggregated_wire_entries.rb +26 -0
- data/lib/configdirector/internal/telemetry/collected_telemetry.rb +98 -0
- data/lib/configdirector/internal/telemetry/compact_json_text.rb +64 -0
- data/lib/configdirector/internal/telemetry/discarded_telemetry.rb +31 -0
- data/lib/configdirector/internal/telemetry/event_reporter.rb +47 -0
- data/lib/configdirector/internal/telemetry/invalid_context_submissions.rb +76 -0
- data/lib/configdirector/internal/telemetry/report_answer.rb +31 -0
- data/lib/configdirector/internal/telemetry/report_schedule.rb +66 -0
- data/lib/configdirector/internal/telemetry/report_timing.rb +20 -0
- data/lib/configdirector/internal/telemetry/reported_context.rb +28 -0
- data/lib/configdirector/internal/telemetry/reported_details.rb +71 -0
- data/lib/configdirector/internal/telemetry/reported_evaluation.rb +82 -0
- data/lib/configdirector/internal/telemetry/reported_telemetry.rb +127 -0
- data/lib/configdirector/internal/telemetry/reported_text.rb +13 -0
- data/lib/configdirector/internal/telemetry/reported_time.rb +13 -0
- data/lib/configdirector/internal/telemetry/reported_value.rb +35 -0
- data/lib/configdirector/internal/telemetry/telemetry_endpoint.rb +54 -0
- data/lib/configdirector/internal/telemetry/telemetry_report.rb +50 -0
- data/lib/configdirector/internal/telemetry/test_client_telemetry.rb +37 -0
- data/lib/configdirector/internal/telemetry/tracked_event_admission.rb +72 -0
- data/lib/configdirector/internal/telemetry/tracked_event_entry.rb +27 -0
- data/lib/configdirector/internal/telemetry/tracked_event_queue.rb +47 -0
- data/lib/configdirector/internal/telemetry/tracked_event_warning.rb +28 -0
- data/lib/configdirector/internal/telemetry/value_id.rb +23 -0
- data/lib/configdirector/internal/telemetry/written_json.rb +9 -0
- data/lib/configdirector/internal/unchangeable_copy.rb +38 -0
- data/lib/configdirector/internal/value/encoded_native_value.rb +45 -0
- data/lib/configdirector/internal/value/hash_keys.rb +34 -0
- data/lib/configdirector/internal/value/in_code_default_value.rb +33 -0
- data/lib/configdirector/internal/value/json_contents.rb +81 -0
- data/lib/configdirector/internal/value/json_position.rb +27 -0
- data/lib/configdirector/internal/value/native_values.rb +41 -0
- data/lib/configdirector/internal/value/parsed_json.rb +79 -0
- data/lib/configdirector/internal/value/plain_decimal_text.rb +36 -0
- data/lib/configdirector/internal/value/served_text.rb +76 -0
- data/lib/configdirector/internal/value/typed_value.rb +9 -0
- data/lib/configdirector/internal/value/unservable_value.rb +9 -0
- data/lib/configdirector/internal/value/utf8_text.rb +19 -0
- data/lib/configdirector/internal.rb +9 -0
- data/lib/configdirector/metadata.rb +26 -0
- data/lib/configdirector/subscription.rb +34 -0
- data/lib/configdirector/telemetry_options.rb +28 -0
- data/lib/configdirector/testing/test_client.rb +122 -0
- data/lib/configdirector/testing/tracked_event.rb +46 -0
- data/lib/configdirector/testing.rb +44 -0
- data/lib/configdirector/variation.rb +21 -0
- data/lib/configdirector/version.rb +7 -0
- data/lib/configdirector-server-sdk.rb +3 -0
- data/lib/configdirector.rb +164 -0
- data/sig/configdirector/internal/client.rbs +518 -0
- data/sig/configdirector/internal/connection.rbs +389 -0
- data/sig/configdirector/internal/evaluation.rbs +364 -0
- data/sig/configdirector/internal/identity.rbs +51 -0
- data/sig/configdirector/internal/logging.rbs +33 -0
- data/sig/configdirector/internal/polling.rbs +240 -0
- data/sig/configdirector/internal/server_sent_events.rbs +51 -0
- data/sig/configdirector/internal/streaming.rbs +266 -0
- data/sig/configdirector/internal/telemetry.rbs +556 -0
- data/sig/configdirector/internal/value.rbs +159 -0
- data/sig/configdirector/testing.rbs +70 -0
- data/sig/configdirector.rbs +465 -0
- 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
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
|