Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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,
)
```

Expand All @@ -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.

<!-- Placeholder for Future Speakeasy SDK Sections -->

Expand Down
30 changes: 27 additions & 3 deletions src/glean/api_client/_hooks/x_glean.py
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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(
Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down
147 changes: 147 additions & 0 deletions tests/test_x_glean_hook.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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__])
Loading