From 347b60cb74333e4cd71ffdf2627f576ba229f76e Mon Sep 17 00:00:00 2001 From: Travis Hoover Date: Mon, 16 Nov 2026 14:55:39 -0800 Subject: [PATCH] feat: add include_beta option, keep include_experimental as an alias --- README.md | 15 ++- src/glean/api_client/_hooks/x_glean.py | 30 ++++- tests/test_x_glean_hook.py | 147 +++++++++++++++++++++++++ 3 files changed, 183 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 65307840..b016afc2 100644 --- a/README.md +++ b/README.md @@ -1042,7 +1042,7 @@ You can also enable a default debug logger by setting an environment variable `G The SDK provides options to test upcoming API changes before they become the default behavior. This is useful for: -- **Testing experimental features** before they are generally available +- **Testing beta features** before they are generally available - **Preparing for deprecations** by excluding deprecated endpoints ahead of their removal ### Configuration Options @@ -1056,7 +1056,7 @@ import os # Set environment variables before initializing the SDK os.environ["X_GLEAN_EXCLUDE_DEPRECATED_AFTER"] = "2026-10-15" -os.environ["X_GLEAN_INCLUDE_EXPERIMENTAL"] = "true" +os.environ["X_GLEAN_INCLUDE_BETA"] = "true" from glean.api_client import Glean @@ -1077,7 +1077,7 @@ glean = Glean( api_token=os.environ.get("GLEAN_API_TOKEN", ""), server_url="https://mycompany-be.glean.com", exclude_deprecated_after="2026-10-15", - include_experimental=True, + include_beta=True, ) ``` @@ -1086,13 +1086,16 @@ glean = Glean( | Option | Environment Variable | Type | Description | | ------ | -------------------- | ---- | ----------- | | `exclude_deprecated_after` | `X_GLEAN_EXCLUDE_DEPRECATED_AFTER` | `str` (date) | Exclude API endpoints that will be deprecated after this date (format: `YYYY-MM-DD`). Use this to test your integration against upcoming deprecations. | -| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | When `True`, enables experimental API features that are not yet generally available. Use this to preview and test new functionality. | +| `include_beta` | `X_GLEAN_INCLUDE_BETA` | `bool` | When `True`, enables beta API features that are not yet generally available. Use this to preview and test new functionality. | +| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | Alias of `include_beta`. Existing code that uses it keeps working. | > [!NOTE] -> Environment variables take precedence over SDK constructor options when both are set. +> Environment variables take precedence over SDK constructor options when both are set. `X_GLEAN_INCLUDE_BETA=true` (case-insensitive) enables beta features, and any other non-empty value overrides `include_beta=True`. +> +> `include_beta` and `include_experimental` are resolved separately, and either one enables beta features. Disabling one does not disable the other. Both send the `X-Glean-Include-Experimental: true` header. > [!WARNING] -> Experimental features may change or be removed without notice. Do not rely on experimental features in production environments. +> Beta features may change or be removed without notice. Do not rely on beta features in production environments. diff --git a/src/glean/api_client/_hooks/x_glean.py b/src/glean/api_client/_hooks/x_glean.py index 8976e7fc..f860eca9 100644 --- a/src/glean/api_client/_hooks/x_glean.py +++ b/src/glean/api_client/_hooks/x_glean.py @@ -1,4 +1,4 @@ -"""Hook to set X-Glean headers for experimental features and deprecation testing.""" +"""Hook to set X-Glean headers for beta features and deprecation testing.""" import os from typing import Optional, Union @@ -12,6 +12,7 @@ # Environment variable names EXCLUDE_DEPRECATED_AFTER_ENV_VAR = "X_GLEAN_EXCLUDE_DEPRECATED_AFTER" INCLUDE_EXPERIMENTAL_ENV_VAR = "X_GLEAN_INCLUDE_EXPERIMENTAL" +INCLUDE_BETA_ENV_VAR = "X_GLEAN_INCLUDE_BETA" def _get_first_value( @@ -29,13 +30,26 @@ def _get_first_value( return None +def _resolve_boolean_option(env_value: Optional[str], config_value: object) -> bool: + """Resolve a boolean opt-in from its environment variable and SDK option. + + The environment variable takes precedence: "true" (case-insensitive) + enables it, any other non-empty value disables it, and an unset or blank + value falls back to the SDK option. + """ + if env_value is not None and env_value.strip(): + return env_value.strip().lower() == "true" + return config_value is True + + class XGlean(BeforeRequestHook): """ - Hook that sets X-Glean headers for experimental features and deprecation testing. + Hook that sets X-Glean headers for beta features and deprecation testing. This hook adds the following headers when configured: - X-Glean-Exclude-Deprecated-After: Excludes API endpoints deprecated after this date - - X-Glean-Include-Experimental: Enables experimental API features + - X-Glean-Include-Experimental: Enables beta API features. Set by either + include_beta or its include_experimental alias. Configuration can be done via environment variables or SDK constructor options. Environment variables take precedence over SDK constructor options. @@ -69,6 +83,16 @@ def before_request( config_experimental, ) + # include_experimental is an alias of include_beta. Each one resolves on + # its own, and either one enables the header. Disabling one never + # disables the other. Keep sending X-Glean-Include-Experimental for both: + # older deployments do not allow X-Glean-Beta in their CORS preflight. + if _resolve_boolean_option( + os.environ.get(INCLUDE_BETA_ENV_VAR), + getattr(hook_ctx.config, "include_beta", None), + ): + experimental_value = "true" + if deprecated_value: request.headers[EXCLUDE_DEPRECATED_AFTER_HEADER] = deprecated_value diff --git a/tests/test_x_glean_hook.py b/tests/test_x_glean_hook.py index dff8c99d..3e838ddb 100644 --- a/tests/test_x_glean_hook.py +++ b/tests/test_x_glean_hook.py @@ -12,7 +12,9 @@ INCLUDE_EXPERIMENTAL_HEADER, EXCLUDE_DEPRECATED_AFTER_ENV_VAR, INCLUDE_EXPERIMENTAL_ENV_VAR, + INCLUDE_BETA_ENV_VAR, ) +from src.glean.api_client import Glean from src.glean.api_client._hooks.types import BeforeRequestContext, HookContext from src.glean.api_client.sdkconfiguration import SDKConfiguration @@ -25,11 +27,13 @@ def create_mock_request() -> httpx.Request: def create_mock_context( exclude_deprecated_after: str = None, include_experimental: bool = None, + include_beta: bool = None, ) -> BeforeRequestContext: """Create a mock BeforeRequestContext with the given SDK configuration options.""" config = Mock(spec=SDKConfiguration) config.exclude_deprecated_after = exclude_deprecated_after config.include_experimental = include_experimental + config.include_beta = include_beta hook_ctx = Mock(spec=HookContext) hook_ctx.config = config @@ -51,13 +55,20 @@ def clear_env_vars(self): # Store original values original_deprecated = os.environ.get(EXCLUDE_DEPRECATED_AFTER_ENV_VAR) original_experimental = os.environ.get(INCLUDE_EXPERIMENTAL_ENV_VAR) + original_beta = os.environ.get(INCLUDE_BETA_ENV_VAR) # Clear for test os.environ.pop(EXCLUDE_DEPRECATED_AFTER_ENV_VAR, None) os.environ.pop(INCLUDE_EXPERIMENTAL_ENV_VAR, None) + os.environ.pop(INCLUDE_BETA_ENV_VAR, None) yield + if original_beta is not None: + os.environ[INCLUDE_BETA_ENV_VAR] = original_beta + else: + os.environ.pop(INCLUDE_BETA_ENV_VAR, None) + # Restore original values if original_deprecated is not None: os.environ[EXCLUDE_DEPRECATED_AFTER_ENV_VAR] = original_deprecated @@ -267,5 +278,141 @@ def test_handles_multipart_streaming_request(self): assert result.method == "POST" +@pytest.fixture(name="clean_x_glean_env") +def fixture_clean_x_glean_env(monkeypatch): + """Unset every X-Glean environment variable for the test.""" + for name in ( + EXCLUDE_DEPRECATED_AFTER_ENV_VAR, + INCLUDE_EXPERIMENTAL_ENV_VAR, + INCLUDE_BETA_ENV_VAR, + ): + monkeypatch.delenv(name, raising=False) + return monkeypatch + + +@pytest.mark.parametrize( + "beta_env, experimental_env, config, expected", + [ + pytest.param(None, None, {}, None, id="neither option set"), + pytest.param(None, None, {"include_beta": True}, "true", id="include_beta alone"), + pytest.param(None, None, {"include_beta": False}, None, id="include_beta false"), + pytest.param( + None, None, {"include_experimental": True}, "true", id="include_experimental alone" + ), + pytest.param( + None, + None, + {"include_beta": True, "include_experimental": True}, + "true", + id="both options true", + ), + pytest.param( + None, + None, + {"include_beta": True, "include_experimental": False}, + "true", + id="include_beta true, include_experimental false", + ), + pytest.param("true", None, {}, "true", id="X_GLEAN_INCLUDE_BETA alone"), + pytest.param(" TRUE ", None, {}, "true", id="X_GLEAN_INCLUDE_BETA is case-insensitive"), + pytest.param("true", "true", {}, "true", id="both env vars true"), + pytest.param( + "false", + None, + {"include_beta": True}, + None, + id="X_GLEAN_INCLUDE_BETA=false overrides include_beta", + ), + pytest.param( + "true", + None, + {"include_beta": False}, + "true", + id="X_GLEAN_INCLUDE_BETA=true overrides include_beta=False", + ), + pytest.param( + " ", + None, + {"include_beta": True}, + "true", + id="empty X_GLEAN_INCLUDE_BETA falls back to include_beta", + ), + pytest.param( + "false", + None, + {"include_experimental": True}, + "true", + id="X_GLEAN_INCLUDE_BETA=false does not turn off include_experimental", + ), + pytest.param( + "false", + "true", + {}, + "true", + id="X_GLEAN_INCLUDE_BETA=false does not turn off X_GLEAN_INCLUDE_EXPERIMENTAL", + ), + pytest.param( + None, + "false", + {"include_beta": True}, + "true", + id="X_GLEAN_INCLUDE_EXPERIMENTAL=false does not turn off include_beta", + ), + ], +) +def test_include_beta(clean_x_glean_env, beta_env, experimental_env, config, expected): + """include_beta and its include_experimental alias both set X-Glean-Include-Experimental.""" + if beta_env is not None: + clean_x_glean_env.setenv(INCLUDE_BETA_ENV_VAR, beta_env) + if experimental_env is not None: + clean_x_glean_env.setenv(INCLUDE_EXPERIMENTAL_ENV_VAR, experimental_env) + + result = XGlean().before_request(create_mock_context(**config), create_mock_request()) + + assert result.headers.get(INCLUDE_EXPERIMENTAL_HEADER) == expected + assert "X-Glean-Beta" not in result.headers + + +@pytest.mark.parametrize( + "env, expected", + [ + pytest.param({}, None, id="neither env var"), + pytest.param({INCLUDE_BETA_ENV_VAR: "true"}, "true", id="X_GLEAN_INCLUDE_BETA"), + pytest.param( + {INCLUDE_EXPERIMENTAL_ENV_VAR: "true"}, "true", id="X_GLEAN_INCLUDE_EXPERIMENTAL" + ), + pytest.param( + {INCLUDE_BETA_ENV_VAR: "true", INCLUDE_EXPERIMENTAL_ENV_VAR: "true"}, + "true", + id="both env vars", + ), + ], +) +def test_sdk_sends_include_experimental_header(clean_x_glean_env, env, expected): + """A real Glean client sends the header that the env vars ask for.""" + for name, value in env.items(): + clean_x_glean_env.setenv(name, value) + + captured = [] + + def handler(request: httpx.Request) -> httpx.Response: + captured.append(request) + return httpx.Response(200, json={}) + + glean = Glean( + api_token="test-token", + server_url="https://example.com", + client=httpx.Client(transport=httpx.MockTransport(handler)), + ) + try: + glean.search.query(query="test") + except Exception: # pylint: disable=broad-exception-caught + pass # The empty response body may not validate; only the request matters. + + assert captured, "expected a request to be sent" + assert captured[0].headers.get(INCLUDE_EXPERIMENTAL_HEADER) == expected + assert "X-Glean-Beta" not in captured[0].headers + + if __name__ == "__main__": pytest.main([__file__])