From 62bc40ae9273f20e510d7abc41453f91987a4271 Mon Sep 17 00:00:00 2001 From: Travis Hoover Date: Mon, 16 Nov 2026 14:55:28 -0800 Subject: [PATCH] feat: add includeBeta option, keep includeExperimental as an alias --- README.md | 15 ++-- src/__tests__/x-glean.test.ts | 141 ++++++++++++++++++++++++++++++++++ src/hooks/x-glean-options.ts | 17 +++- src/hooks/x-glean.ts | 65 ++++++++++------ 4 files changed, 204 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index dc068bf63..a0d7fe5b2 100644 --- a/README.md +++ b/README.md @@ -1362,7 +1362,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 @@ -1374,7 +1374,7 @@ You can configure these options either via environment variables or SDK construc ```typescript // Set environment variables before initializing the SDK process.env.X_GLEAN_EXCLUDE_DEPRECATED_AFTER = '2026-10-15'; -process.env.X_GLEAN_INCLUDE_EXPERIMENTAL = 'true'; +process.env.X_GLEAN_INCLUDE_BETA = 'true'; import { Glean } from "@gleanwork/api-client"; @@ -1395,7 +1395,7 @@ const opts = { apiToken: process.env["GLEAN_API_TOKEN"] ?? "", serverURL: "https://mycompany-be.glean.com", excludeDeprecatedAfter: "2026-10-15", - includeExperimental: true, + includeBeta: true, } satisfies SDKOptions & XGleanOptions; const glean = new Glean(opts); @@ -1406,13 +1406,16 @@ const glean = new Glean(opts); | Option | Environment Variable | Type | Description | | ------ | -------------------- | ---- | ----------- | | `excludeDeprecatedAfter` | `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. | -| `includeExperimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `boolean` | When `true`, enables experimental API features that are not yet generally available. Use this to preview and test new functionality. | +| `includeBeta` | `X_GLEAN_INCLUDE_BETA` | `boolean` | When `true`, enables beta API features that are not yet generally available. Use this to preview and test new functionality. | +| `includeExperimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `boolean` | Alias of `includeBeta`. 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. A boolean environment variable set to `true` (case-insensitive) enables its option, and any other non-empty value disables it. +> +> `includeBeta` and `includeExperimental` 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/__tests__/x-glean.test.ts b/src/__tests__/x-glean.test.ts index 80001f538..97fdbf429 100644 --- a/src/__tests__/x-glean.test.ts +++ b/src/__tests__/x-glean.test.ts @@ -7,6 +7,8 @@ import { import { BeforeRequestContext } from "../hooks/types.js"; import { SDKOptions } from "../lib/config.js"; import { XGleanOptions } from "../hooks/x-glean-options.js"; +import { HTTPClient } from "../lib/http.js"; +import { Glean } from "../index.js"; function createMockRequest(): Request { return new Request("https://example.com/api/test"); @@ -36,6 +38,7 @@ describe("XGlean hook", () => { process.env = { ...originalEnv }; delete process.env["X_GLEAN_EXCLUDE_DEPRECATED_AFTER"]; delete process.env["X_GLEAN_INCLUDE_EXPERIMENTAL"]; + delete process.env["X_GLEAN_INCLUDE_BETA"]; }); afterEach(() => { @@ -250,6 +253,144 @@ describe("XGlean hook", () => { }); }); + describe("includeBeta and its includeExperimental alias", () => { + function headerFor( + options: SDKOptions & XGleanOptions, + ): string | null { + const hook = new XGlean(); + const result = hook.beforeRequest( + createMockContext(options), + createMockRequest(), + ); + return result.headers.get(INCLUDE_EXPERIMENTAL_HEADER); + } + + it("should set X-Glean-Include-Experimental when includeBeta is true", () => { + expect(headerFor({ includeBeta: true })).toBe("true"); + }); + + it("should not set the header when includeBeta is false", () => { + expect(headerFor({ includeBeta: false })).toBeNull(); + }); + + it("should set the header once when includeBeta and includeExperimental are both true", () => { + expect( + headerFor({ includeBeta: true, includeExperimental: true }), + ).toBe("true"); + }); + + it("should set the header when either option is true", () => { + expect( + headerFor({ includeBeta: true, includeExperimental: false }), + ).toBe("true"); + expect( + headerFor({ includeBeta: false, includeExperimental: true }), + ).toBe("true"); + }); + + it("should not set the header when both options are false", () => { + expect( + headerFor({ includeBeta: false, includeExperimental: false }), + ).toBeNull(); + }); + + it("should set the header from X_GLEAN_INCLUDE_BETA", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = "TRUE"; + expect(headerFor({})).toBe("true"); + }); + + it("should set the header when both env vars are true", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = "true"; + process.env["X_GLEAN_INCLUDE_EXPERIMENTAL"] = "true"; + expect(headerFor({})).toBe("true"); + }); + + it("should let X_GLEAN_INCLUDE_BETA=false override includeBeta", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = "false"; + expect(headerFor({ includeBeta: true })).toBeNull(); + }); + + it("should let X_GLEAN_INCLUDE_BETA=true override includeBeta=false", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = "true"; + expect(headerFor({ includeBeta: false })).toBe("true"); + }); + + it("should fall back to includeBeta when X_GLEAN_INCLUDE_BETA is empty", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = " "; + expect(headerFor({ includeBeta: true })).toBe("true"); + }); + + it("should not let X_GLEAN_INCLUDE_BETA=false turn off includeExperimental", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = "false"; + expect(headerFor({ includeExperimental: true })).toBe("true"); + }); + + it("should not let X_GLEAN_INCLUDE_EXPERIMENTAL=false turn off includeBeta", () => { + process.env["X_GLEAN_INCLUDE_EXPERIMENTAL"] = "false"; + expect(headerFor({ includeBeta: true })).toBe("true"); + }); + + it("should not set the header when both env vars are false", () => { + process.env["X_GLEAN_INCLUDE_BETA"] = "false"; + process.env["X_GLEAN_INCLUDE_EXPERIMENTAL"] = "false"; + expect( + headerFor({ includeBeta: true, includeExperimental: true }), + ).toBeNull(); + }); + + it("should not send X-Glean-Beta yet", () => { + const hook = new XGlean(); + const result = hook.beforeRequest( + createMockContext({ includeBeta: true }), + createMockRequest(), + ); + expect(result.headers.has("X-Glean-Beta")).toBe(false); + }); + }); + + describe("when passed to the Glean constructor", () => { + async function sentHeaders( + options: XGleanOptions, + ): Promise { + let captured: Headers | undefined; + const httpClient = new HTTPClient({ + fetcher: async (input) => { + captured = (input as Request).headers; + return new Response("{}", { + status: 200, + headers: { "content-type": "application/json" }, + }); + }, + }); + const glean = new Glean({ + apiToken: "test-token", + serverURL: "https://example.com", + httpClient, + ...options, + } satisfies SDKOptions & XGleanOptions); + + await glean.client.search.query({ query: "test" }).catch(() => {}); + + if (!captured) throw new Error("no request was sent"); + return captured; + } + + it("should send X-Glean-Include-Experimental for includeBeta", async () => { + const headers = await sentHeaders({ includeBeta: true }); + expect(headers.get(INCLUDE_EXPERIMENTAL_HEADER)).toBe("true"); + }); + + it("should send X-Glean-Include-Experimental for includeExperimental", async () => { + const headers = await sentHeaders({ includeExperimental: true }); + expect(headers.get(INCLUDE_EXPERIMENTAL_HEADER)).toBe("true"); + }); + + it("should not send the header when neither option is set", async () => { + const headers = await sentHeaders({}); + expect(headers.has(INCLUDE_EXPERIMENTAL_HEADER)).toBe(false); + }); + }); + describe("when options are malformed at runtime", () => { it("should not set X-Glean-Exclude-Deprecated-After when excludeDeprecatedAfter is not a string", () => { const hook = new XGlean(); diff --git a/src/hooks/x-glean-options.ts b/src/hooks/x-glean-options.ts index 04625fc8e..05c5f76dc 100644 --- a/src/hooks/x-glean-options.ts +++ b/src/hooks/x-glean-options.ts @@ -1,5 +1,5 @@ /** - * X-Glean custom options for configuring deprecation and experimental headers. + * X-Glean custom options for configuring deprecation and beta headers. * * These properties allow configuring X-Glean headers through the SDK constructor. * Since SDKOptions in lib/config.ts is generated by Speakeasy and gets overwritten @@ -10,7 +10,7 @@ /** * Custom SDK options for X-Glean header configuration. * Use these options when constructing the SDK client to configure - * experimental features and deprecation testing. + * beta features and deprecation testing. */ export interface XGleanOptions { /** @@ -22,8 +22,19 @@ export interface XGleanOptions { */ excludeDeprecatedAfter?: string; /** - * When true, enables experimental API features that are not yet generally available. + * When true, enables beta API features that are not yet generally available. * Use this to preview and test new functionality. + * + * Can also be set with the X_GLEAN_INCLUDE_BETA environment variable, which + * takes precedence over this option. + */ + includeBeta?: boolean; + /** + * Alias of {@link XGleanOptions.includeBeta}. Either option enables beta + * API features. + * + * Can also be set with the X_GLEAN_INCLUDE_EXPERIMENTAL environment variable, + * which takes precedence over this option. */ includeExperimental?: boolean; } diff --git a/src/hooks/x-glean.ts b/src/hooks/x-glean.ts index 4f44c44f3..46240f9d2 100644 --- a/src/hooks/x-glean.ts +++ b/src/hooks/x-glean.ts @@ -3,6 +3,10 @@ import { BeforeRequestContext, BeforeRequestHook } from "./types.js"; export const EXCLUDE_DEPRECATED_AFTER_HEADER = "X-Glean-Exclude-Deprecated-After"; export const INCLUDE_EXPERIMENTAL_HEADER = "X-Glean-Include-Experimental"; +export const EXCLUDE_DEPRECATED_AFTER_ENV_VAR = "X_GLEAN_EXCLUDE_DEPRECATED_AFTER"; +export const INCLUDE_EXPERIMENTAL_ENV_VAR = "X_GLEAN_INCLUDE_EXPERIMENTAL"; +export const INCLUDE_BETA_ENV_VAR = "X_GLEAN_INCLUDE_BETA"; + /** * Get the first non-empty value from the provided arguments. */ @@ -27,6 +31,24 @@ function getBooleanOption(options: Record, key: string): boolea return options[key] === true; } +/** + * Resolve a boolean opt-in from its env var and its SDK option. + * + * The env var is a boolean toggle and takes precedence over the option: + * - "true" (case-insensitive) => enabled + * - anything else (including "false") => disabled + * - unset, empty, or whitespace => fall back to the SDK option + */ +function resolveBooleanOption( + envValue: string | undefined, + options: Record, + key: string, +): boolean { + const t = envValue?.trim(); + if (t) return t.toLowerCase() === "true"; + return getBooleanOption(options, key); +} + export class XGlean implements BeforeRequestHook { beforeRequest(hookCtx: BeforeRequestContext, request: Request): Request { const opt = hookCtx.options as unknown; @@ -35,39 +57,32 @@ export class XGlean implements BeforeRequestHook { : {}; const deprecatedValue = getFirstValue( - process.env["X_GLEAN_EXCLUDE_DEPRECATED_AFTER"], + process.env[EXCLUDE_DEPRECATED_AFTER_ENV_VAR], getStringOption(options, "excludeDeprecatedAfter"), ); - const experimentalEnv = process.env["X_GLEAN_INCLUDE_EXPERIMENTAL"]; - let experimentalValue: string | false = false; - if (typeof experimentalEnv !== "undefined") { - const t = experimentalEnv.trim(); - // Env var is treated as a boolean toggle. - // - "true" (case-insensitive) => set header - // - anything else (including "false") => omit header - // - empty/whitespace => treat as unset and fall back to options - if (!t) { - experimentalValue = getBooleanOption(options, "includeExperimental") - ? "true" - : false; - } else if (t.toLowerCase() === "true") { - experimentalValue = "true"; - } else { - experimentalValue = false; - } - } else { - experimentalValue = getBooleanOption(options, "includeExperimental") - ? "true" - : false; - } + // includeExperimental is an alias of includeBeta. Each one resolves on its + // own (env var first, then SDK option), and either one enables the header. + // Disabling one never disables the other. + const includeBeta = resolveBooleanOption( + process.env[INCLUDE_BETA_ENV_VAR], + options, + "includeBeta", + ); + const includeExperimental = resolveBooleanOption( + process.env[INCLUDE_EXPERIMENTAL_ENV_VAR], + options, + "includeExperimental", + ); if (deprecatedValue) { request.headers.set(EXCLUDE_DEPRECATED_AFTER_HEADER, deprecatedValue); } - if (experimentalValue) { - request.headers.set(INCLUDE_EXPERIMENTAL_HEADER, experimentalValue); + // Keep sending X-Glean-Include-Experimental for both options. Older + // deployments do not allow X-Glean-Beta in their CORS preflight. + if (includeBeta || includeExperimental) { + request.headers.set(INCLUDE_EXPERIMENTAL_HEADER, "true"); } return request;