Skip to content

(WIP) NODE-7666(feat): environment variables in the handshake metadata - #5052

Draft
johnmtll wants to merge 16 commits into
mainfrom
NODE-7666/environment-variables-in-the-handshake-metadata
Draft

johnmtll wants to merge 16 commits into
mainfrom
NODE-7666/environment-variables-in-the-handshake-metadata

Conversation

@johnmtll

@johnmtll johnmtll commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Description

Summary of Changes

Adds an AI agent identifier, env.agent, to the client metadata handshake, and refactors how the env sub-document is built and truncated.

env.agent

env.agent is populated using first-match, order-bound logic over the agent-related environment variables defined in the spec. Depending on which variable matches, the value is either a generic marker (AI_AGENT / AGENT) or the variable's literal value.

Per the spec, "a variable is considered populated if it is present in the environment with a non-empty value." We treat any value that is empty after trim() as unpopulated and skip it. Populated values are used as-is (e.g. ' claude' is kept verbatim).

env construction and truncation

The spec's truncation order is:

  1. Omit fields from env except env.name and env.agent.
  2. Omit fields from os except os.type.
  3. Omit the env document entirely.
  4. Truncate platform.

Previously, env was built by progressively appending members to the live metadata document, and the spec was partially-satisfied somewhat incidentally: env.name happened to be the last FaaS member added, so it was deleted last — but env.container iss appended after that, making it theoretically possible to end up with an env containing only container.

env is now constructed as a standalone document, truncated independently. This prepare us for a future spec alignment effort tracked in https://jira.mongodb.org/browse/NODE-7851

Refer to: mongodb/specifications#1967 for the incoming changes.

Notes for Reviewers

What is the motivation for this change?

For bug fixes

Current (incorrect) behavior:

Expected behavior:

How to reproduce:

Affected versions:

Release Highlight

Release notes highlight

Double check the following

  • Lint is passing (npm run check:lint)
  • Self-review completed using the steps outlined here
  • PR title follows the correct format: type(NODE-xxxx)[!]: description
    • Example: feat(NODE-1234)!: rewriting everything in coffeescript
  • Changes are covered by tests
  • New TODOs have a related JIRA ticket

@johnmtll
johnmtll force-pushed the NODE-7666/environment-variables-in-the-handshake-metadata branch 4 times, most recently from 50be426 to cb1f4c9 Compare September 14, 2026 21:46
});
});

// Ref: https://github.com/aclark4life/specifications/blob/feaec8d0ca332a80f457f75c6ef1600267e61d64/source/mongodb-handshake/tests/README.md#test-3-test-that-agent-metadata-is-properly-captured

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new spec and unit tests need to clean up the env vars before starting, so the developer's local variables do not impact the tests.

Comment thread src/cmap/handshake/client_metadata.ts Outdated
const agentEnv = getAgentEnv();

const fullEnv = new Map<string, unknown>();
if (containerMetadata.size > 0) fullEnv.set('container', containerMetadata);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this insertion order, container data is dropped before faas. Current (main) implementation tries to re-add container after faas gets booted, so this is a change in behavior.

* Resolves `env.agent` from the environment, or an empty string when no agent variable is
* populated. Returns the value of the first populated variable in `AGENT_ENV_VARIABLES`.
*/
export function getAgentEnv(): string {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function should be added to test/mongodb_bundled.ts (alphabetically next to getFAASEnv) for the bundled tests to succeed.

johnmtll added a commit that referenced this pull request Sep 16, 2026
johnmtll added a commit that referenced this pull request Sep 16, 2026
johnmtll added a commit that referenced this pull request Sep 16, 2026
@PavelSafronov PavelSafronov self-assigned this Sep 17, 2026
@PavelSafronov PavelSafronov added Primary Review In Review with primary reviewer, not yet ready for team's eyes wip and removed Primary Review In Review with primary reviewer, not yet ready for team's eyes labels Sep 17, 2026
@johnmtll
johnmtll force-pushed the NODE-7666/environment-variables-in-the-handshake-metadata branch from 612b981 to b9f4582 Compare September 17, 2026 19:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants