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 @@ -929,7 +929,7 @@ d6 := types.MustDateFromString("2019-01-01") // returns types.Date and panics on

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 @@ -940,7 +940,7 @@ You can configure these options either via environment variables or SDK construc

```bash
export X_GLEAN_EXCLUDE_DEPRECATED_AFTER="2026-10-15"
export X_GLEAN_INCLUDE_EXPERIMENTAL="true"
export X_GLEAN_INCLUDE_BETA="true"
```

```go
Expand Down Expand Up @@ -995,7 +995,7 @@ func main() {
apiclientgo.WithSecurity(os.Getenv("GLEAN_API_TOKEN")),
apiclientgo.WithServerURL("https://mycompany-be.glean.com"),
apiclientgo.WithExcludeDeprecatedAfter("2026-10-15"),
apiclientgo.WithIncludeExperimental(true),
apiclientgo.WithIncludeBeta(true),
)

res, err := s.Client.Search.Query(ctx, components.SearchRequest{
Expand All @@ -1013,11 +1013,14 @@ func main() {
| Option | Environment Variable | Type | Description |
| ------ | -------------------- | ---- | ----------- |
| `WithExcludeDeprecatedAfter` | `X_GLEAN_EXCLUDE_DEPRECATED_AFTER` | `string` (date) | Exclude API endpoints that will be deprecated after this date (format: `YYYY-MM-DD`). Use this to test your integration against upcoming deprecations. |
| `WithIncludeExperimental` | `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. |
| `WithIncludeBeta` | `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. |
| `WithIncludeExperimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | Alias of `WithIncludeBeta`. Existing code that uses it keeps working. |

> **Note:** Environment variables take precedence over SDK constructor options when both are set.
> **Note:** 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 `WithIncludeBeta(true)`.
>
> `WithIncludeBeta` and `WithIncludeExperimental` 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.
> **Warning:** 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
6 changes: 5 additions & 1 deletion internal/hooks/x_glean_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@ type XGleanConfig struct {
// Format: YYYY-MM-DD (e.g., "2026-10-15")
ExcludeDeprecatedAfter string

// IncludeExperimental enables experimental API features when true.
// IncludeBeta enables beta API features when true.
IncludeBeta bool

// IncludeExperimental is an alias of IncludeBeta. Either one enables beta
// API features.
IncludeExperimental bool
}

Expand Down
31 changes: 29 additions & 2 deletions internal/hooks/x_glean_hook.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package hooks
import (
"net/http"
"os"
"strings"
)

// Header names set by XGleanHook. Kept as consts so the header names live in
Expand All @@ -12,6 +13,13 @@ const (
headerIncludeExperimental = "X-Glean-Include-Experimental"
)

// Environment variable names read by XGleanHook.
const (
envExcludeDeprecatedAfter = "X_GLEAN_EXCLUDE_DEPRECATED_AFTER"
envIncludeExperimental = "X_GLEAN_INCLUDE_EXPERIMENTAL"
envIncludeBeta = "X_GLEAN_INCLUDE_BETA"
)

// XGleanHook is a beforeRequest hook that sets X-Glean headers for
// experimental features and deprecation testing.
type XGleanHook struct{}
Expand All @@ -25,19 +33,27 @@ func (h *XGleanHook) BeforeRequest(hookCtx BeforeRequestContext, req *http.Reque

// Get deprecatedAfter value - environment variable takes precedence
deprecatedAfter := getFirstValue(
os.Getenv("X_GLEAN_EXCLUDE_DEPRECATED_AFTER"),
os.Getenv(envExcludeDeprecatedAfter),
sdkConfig.ExcludeDeprecatedAfter,
)

// Get experimental value - environment variable takes precedence
experimentalEnv := os.Getenv("X_GLEAN_INCLUDE_EXPERIMENTAL")
experimentalEnv := os.Getenv(envIncludeExperimental)
experimentalValue := ""
if experimentalEnv != "" {
experimentalValue = experimentalEnv
} else if sdkConfig.IncludeExperimental {
experimentalValue = "true"
}

// IncludeExperimental is an alias of IncludeBeta. 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 resolveBooleanOption(os.Getenv(envIncludeBeta), sdkConfig.IncludeBeta) {
experimentalValue = "true"
}

// Set headers if values are present
if deprecatedAfter != "" {
req.Header.Set(headerExcludeDeprecatedAfter, deprecatedAfter)
Expand All @@ -50,6 +66,17 @@ func (h *XGleanHook) BeforeRequest(hookCtx BeforeRequestContext, req *http.Reque
return req, nil
}

// resolveBooleanOption resolves a boolean opt-in from its environment variable
// and its 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.
func resolveBooleanOption(envValue string, optionValue bool) bool {
if v := strings.TrimSpace(envValue); v != "" {
return strings.EqualFold(v, "true")
}
return optionValue
}

// getFirstValue returns the first non-empty value from the provided arguments.
func getFirstValue(aValue, bValue string) string {
if aValue != "" {
Expand Down
50 changes: 50 additions & 0 deletions internal/hooks/x_glean_hook_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -315,3 +315,53 @@ func TestXGleanHook_EnvVarsPrecedence_BothOptions(t *testing.T) {
t.Errorf("expected X-Glean-Include-Experimental header to be 'true' (from env var), got '%s'", got)
}
}

func TestXGleanHook_IncludeBeta(t *testing.T) {
tests := []struct {
name string
betaEnv string
experimentalEnv string
config XGleanConfig
want string
}{
{name: "neither option set", want: ""},
{name: "IncludeBeta alone", config: XGleanConfig{IncludeBeta: true}, want: "true"},
{name: "IncludeBeta false", config: XGleanConfig{IncludeBeta: false}, want: ""},
{name: "IncludeExperimental alone", config: XGleanConfig{IncludeExperimental: true}, want: "true"},
{name: "both options true", config: XGleanConfig{IncludeBeta: true, IncludeExperimental: true}, want: "true"},
{name: "IncludeBeta true, IncludeExperimental false", config: XGleanConfig{IncludeBeta: true, IncludeExperimental: false}, want: "true"},
{name: "X_GLEAN_INCLUDE_BETA alone", betaEnv: "true", want: "true"},
{name: "X_GLEAN_INCLUDE_BETA is case-insensitive", betaEnv: " TRUE ", want: "true"},
{name: "both env vars true", betaEnv: "true", experimentalEnv: "true", want: "true"},
{name: "X_GLEAN_INCLUDE_BETA=false overrides IncludeBeta", betaEnv: "false", config: XGleanConfig{IncludeBeta: true}, want: ""},
{name: "X_GLEAN_INCLUDE_BETA=true overrides IncludeBeta=false", betaEnv: "true", config: XGleanConfig{IncludeBeta: false}, want: "true"},
{name: "empty X_GLEAN_INCLUDE_BETA falls back to IncludeBeta", betaEnv: " ", config: XGleanConfig{IncludeBeta: true}, want: "true"},
{name: "X_GLEAN_INCLUDE_BETA=false does not turn off IncludeExperimental", betaEnv: "false", config: XGleanConfig{IncludeExperimental: true}, want: "true"},
{name: "X_GLEAN_INCLUDE_BETA=false does not turn off X_GLEAN_INCLUDE_EXPERIMENTAL", betaEnv: "false", experimentalEnv: "true", want: "true"},
{name: "X_GLEAN_INCLUDE_EXPERIMENTAL=false does not turn off IncludeBeta", experimentalEnv: "false", config: XGleanConfig{IncludeBeta: true}, want: "true"},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Setenv("X_GLEAN_EXCLUDE_DEPRECATED_AFTER", "")
t.Setenv("X_GLEAN_INCLUDE_BETA", tt.betaEnv)
t.Setenv("X_GLEAN_INCLUDE_EXPERIMENTAL", tt.experimentalEnv)

hook := &XGleanHook{}
sdk := &mockSDK{}
SetXGleanConfig(sdk, tt.config)

result, err := hook.BeforeRequest(createMockContext(sdk), createMockRequest())
if err != nil {
t.Fatalf("expected no error, got %v", err)
}

if got := result.Header.Get(headerIncludeExperimental); got != tt.want {
t.Errorf("expected X-Glean-Include-Experimental header to be %q, got %q", tt.want, got)
}
if got := result.Header.Get("X-Glean-Beta"); got != "" {
t.Errorf("expected X-Glean-Beta header to not be set yet, got %q", got)
}
})
}
}
26 changes: 22 additions & 4 deletions x_glean.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
// xGleanOptions holds the X-Glean configuration options that will be applied after SDK initialization.
type xGleanOptions struct {
excludeDeprecatedAfter string
includeBeta bool
includeExperimental bool
}

Expand All @@ -31,11 +32,27 @@ func WithExcludeDeprecatedAfter(date string) SDKOption {
}
}

// WithIncludeExperimental configures the SDK to enable experimental API features
// that are not yet generally available. Use this to preview and test new functionality.
// WithIncludeBeta configures the SDK to enable beta API features that are not
// yet generally available. Use this to preview and test new functionality.
//
// Warning: Experimental features may change or be removed without notice.
// Do not rely on experimental features in production environments.
// Warning: Beta features may change or be removed without notice.
// Do not rely on beta features in production environments.
//
// This can also be set via the X_GLEAN_INCLUDE_BETA environment variable.
// Environment variables take precedence over SDK options.
//
// WithIncludeExperimental is an alias. If either one is enabled, the SDK
// enables beta API features.
func WithIncludeBeta(enabled bool) SDKOption {
return func(sdk *Glean) {
opts := getOrCreatePendingOptions(sdk)
opts.includeBeta = enabled
applyXGleanConfig(sdk, opts)
}
}

// WithIncludeExperimental is an alias of WithIncludeBeta. If either one is
// enabled, the SDK enables beta API features.
//
// This can also be set via the X_GLEAN_INCLUDE_EXPERIMENTAL environment variable.
// Environment variables take precedence over SDK options.
Expand All @@ -61,6 +78,7 @@ func getOrCreatePendingOptions(sdk *Glean) *xGleanOptions {
func applyXGleanConfig(sdk *Glean, opts *xGleanOptions) {
hooks.SetXGleanConfig(sdk, hooks.XGleanConfig{
ExcludeDeprecatedAfter: opts.excludeDeprecatedAfter,
IncludeBeta: opts.includeBeta,
IncludeExperimental: opts.includeExperimental,
})
}
93 changes: 93 additions & 0 deletions x_glean_test.go
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
package apiclientgo

import (
"context"
"io"
"net/http"
"os"
"strings"
"testing"

"github.com/gleanwork/api-client-go/internal/hooks"
"github.com/gleanwork/api-client-go/models/components"
)

func TestWithExcludeDeprecatedAfter(t *testing.T) {
Expand Down Expand Up @@ -44,6 +49,94 @@ func TestWithBothOptions(t *testing.T) {
}
}

func TestWithIncludeBeta(t *testing.T) {
sdk := New(
WithIncludeBeta(true),
)

config := hooks.GetXGleanConfig(sdk)
if !config.IncludeBeta {
t.Error("expected IncludeBeta to be true")
}
if config.IncludeExperimental {
t.Error("expected IncludeExperimental to be false")
}
}

func TestWithIncludeBetaAndIncludeExperimental(t *testing.T) {
sdk := New(
WithIncludeBeta(true),
WithIncludeExperimental(true),
WithExcludeDeprecatedAfter("2026-10-15"),
)

config := hooks.GetXGleanConfig(sdk)
if !config.IncludeBeta {
t.Error("expected IncludeBeta to be true")
}
if !config.IncludeExperimental {
t.Error("expected IncludeExperimental to be true")
}
if config.ExcludeDeprecatedAfter != "2026-10-15" {
t.Errorf("expected ExcludeDeprecatedAfter to be '2026-10-15', got '%s'", config.ExcludeDeprecatedAfter)
}
}

// headerCapturingClient records the headers of the last request it receives.
type headerCapturingClient struct {
header http.Header
}

func (c *headerCapturingClient) Do(req *http.Request) (*http.Response, error) {
c.header = req.Header.Clone()
return &http.Response{
StatusCode: http.StatusOK,
Header: http.Header{"Content-Type": []string{"application/json"}},
Body: io.NopCloser(strings.NewReader("{}")),
Request: req,
}, nil
}

func TestXGleanOptionsSendIncludeExperimentalHeader(t *testing.T) {
tests := []struct {
name string
opts []SDKOption
want string
}{
{name: "neither option", want: ""},
{name: "WithIncludeBeta", opts: []SDKOption{WithIncludeBeta(true)}, want: "true"},
{name: "WithIncludeExperimental", opts: []SDKOption{WithIncludeExperimental(true)}, want: "true"},
{name: "both options", opts: []SDKOption{WithIncludeBeta(true), WithIncludeExperimental(true)}, want: "true"},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Setenv("X_GLEAN_INCLUDE_BETA", "")
t.Setenv("X_GLEAN_INCLUDE_EXPERIMENTAL", "")

client := &headerCapturingClient{}
opts := append([]SDKOption{
WithClient(client),
WithSecurity("test-token"),
WithServerURL("https://example.com"),
}, tt.opts...)
sdk := New(opts...)

_, _ = sdk.Search.Query(context.Background(), components.PlatformSearchRequest{Query: "test"})

if client.header == nil {
t.Fatal("expected a request to be sent")
}
if got := client.header.Get("X-Glean-Include-Experimental"); got != tt.want {
t.Errorf("expected X-Glean-Include-Experimental header to be %q, got %q", tt.want, got)
}
if got := client.header.Get("X-Glean-Beta"); got != "" {
t.Errorf("expected X-Glean-Beta header to not be set yet, got %q", got)
}
})
}
}

func TestWithIncludeExperimentalFalse(t *testing.T) {
sdk := New(
WithIncludeExperimental(false),
Expand Down
Loading