docs: Note that a flagValues override is not available to client-side SDKs

A flagValues entry becomes a flag without client-side availability, so
an all-flags state for client-side SDKs leaves it out even when the flag
it overrides is client-side. A full definition with clientSide is the
way to override such a flag. A test pins both.

Author: kinyoklion

ldclient/integrations/overrides.py

@@ -54,7 +54,11 @@ class FileOverrideSourceBuilder(OverrideSourceBuilder):
     as the files change. The files use the same document format as the file data source:
     each file is a JSON or YAML document with optional ``flags``, ``flagValues``, and
     ``segments`` members. ``flagValues`` entries are expanded into full flag definitions that
-    return the given value for every context. YAML requires the ``pyyaml`` package.
+    return the given value for every context. A ``flagValues`` entry is not available to
+    client-side SDKs, so :meth:`ldclient.client.LDClient.all_flags_state` with
+    ``client_side_only=True`` leaves it out, even when the flag it overrides is available to them.
+    To override such a flag, define it in ``flags`` with ``"clientSide": true``. YAML requires the
+    ``pyyaml`` package.
 
     When multiple files are configured, their entries are combined in the configured order.
     The order determines which file wins under the duplicate keys handling. A reload replaces

ldclient/testing/integrations/test_file_override_source.py

@@ -537,3 +537,22 @@ def changed() -> bool:
         # The override is removed. The not-initialized short-circuit returns.
         write_file(path, '{}')
         eventually(lambda: client.variation_detail('overridden-flag', user, False).reason.get('errorKind') == 'CLIENT_NOT_READY', "the removed override was not picked up")
+
+
+def test_client_side_all_flags_state_includes_a_full_definition_with_client_side_but_not_a_value_entry(tmp_path):
+    # A flagValues entry is not available to client-side SDKs. A full definition that sets
+    # clientSide is, so that is how an operator overrides a flag that client-side SDKs use.
+    path = os.path.join(str(tmp_path), 'overrides.json')
+    write_file(path, '{"flagValues": {"value-flag": true}, '
+                     '"flags": {"full-flag": {"key": "full-flag", "version": 1, "on": true, "variations": [true], '
+                     '"fallthrough": {"variation": 0}, "clientSide": true}}}')
+    source = FileOverrideSourceBuilder([path])
+    datasystem = custom().synchronizers(HangingSynchronizer().builder).overrides(source).build()
+    config = Config(sdk_key='SDK_KEY', datasystem_config=datasystem, event_processor_class=MockEventProcessor)
+
+    with LDClient(config, start_wait=0) as client:
+        user = Context.create('user-key')
+        assert set(client.all_flags_state(user).to_values_map().keys()) == {'value-flag', 'full-flag'}
+        state = client.all_flags_state(user, client_side_only=True)
+        assert state.valid
+        assert state.to_values_map() == {'full-flag': True}