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 @@ -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
Expand All @@ -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";

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

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

Expand Down
141 changes: 141 additions & 0 deletions src/__tests__/x-glean.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down Expand Up @@ -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(() => {
Expand Down Expand Up @@ -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<Headers> {
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();
Expand Down
17 changes: 14 additions & 3 deletions src/hooks/x-glean-options.ts
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 {
/**
Expand All @@ -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;
}
65 changes: 40 additions & 25 deletions src/hooks/x-glean.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -27,6 +31,24 @@ function getBooleanOption(options: Record<string, unknown>, 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<string, unknown>,
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;
Expand All @@ -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;
Expand Down
Loading