From 2cab7d2fd3c59c2c0e4c0622447970fab74be8a6 Mon Sep 17 00:00:00 2001 From: Travis Hoover Date: Mon, 16 Nov 2026 14:55:34 -0800 Subject: [PATCH] feat: add WithIncludeBeta option, keep WithIncludeExperimental as an alias --- README.md | 15 +++-- internal/hooks/x_glean_config.go | 6 +- internal/hooks/x_glean_hook.go | 31 +++++++++- internal/hooks/x_glean_hook_test.go | 50 ++++++++++++++++ x_glean.go | 26 ++++++-- x_glean_test.go | 93 +++++++++++++++++++++++++++++ 6 files changed, 208 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e94de045..448afae4 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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{ @@ -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. diff --git a/internal/hooks/x_glean_config.go b/internal/hooks/x_glean_config.go index 458d4876..acf296b7 100644 --- a/internal/hooks/x_glean_config.go +++ b/internal/hooks/x_glean_config.go @@ -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 } diff --git a/internal/hooks/x_glean_hook.go b/internal/hooks/x_glean_hook.go index 06aadd3c..fbabf96f 100644 --- a/internal/hooks/x_glean_hook.go +++ b/internal/hooks/x_glean_hook.go @@ -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 @@ -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{} @@ -25,12 +33,12 @@ 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 @@ -38,6 +46,14 @@ func (h *XGleanHook) BeforeRequest(hookCtx BeforeRequestContext, req *http.Reque 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) @@ -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 != "" { diff --git a/internal/hooks/x_glean_hook_test.go b/internal/hooks/x_glean_hook_test.go index d4375875..521a7bed 100644 --- a/internal/hooks/x_glean_hook_test.go +++ b/internal/hooks/x_glean_hook_test.go @@ -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) + } + }) + } +} diff --git a/x_glean.go b/x_glean.go index 33c0e2d4..c8585aef 100644 --- a/x_glean.go +++ b/x_glean.go @@ -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 } @@ -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. @@ -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, }) } diff --git a/x_glean_test.go b/x_glean_test.go index a1538574..78667bd4 100644 --- a/x_glean_test.go +++ b/x_glean_test.go @@ -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) { @@ -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),