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

[johnmtll]

Description

Summary of Changes

1. Adds an AI agent identifier, env.agent, to the client metadata handshake.
2. Refactors how the env sub-document is built and truncated.
3. Alters the way we populate metadata documents so changes can be mutative instead of just additive (adding logic to handle considering existing values when calling LimitedSizeDocument.ifItFitsItSits)

Notes for Reviewers

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) 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 normalization/truncation as unpopulated and skip it.

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 is 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 prepares us for a future spec alignment effort tracked in https://jira.mongodb.org/browse/NODE-7851.

Truncation is a byte-op, not a character-op. This means that we can potentially slice multi-byte values during truncation. The remnants of a multi-byte slice are discarded. This allows us to also close out an outstanding bug (NODE-5150) via the use of a shared util (truncateStringBytes) where multi-byte partials remained when constructing appName.

Other info

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

Some tests which covered truncation logic (appName construction) have been moved to util tests when using a shared function. This is to keep the tests purely-scoped to the behaviour of the function being tested.

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

[PavelSafronov]

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.

[PavelSafronov]

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.

[PavelSafronov]

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