feat: Add option databaseOptions.clientMetadata to send custom metadata to database server for logging and debugging

[Copilot]

Pull Request

• Report security issues confidentially.
• Any contribution is under this license.
• Link this pull request to an issue.

Approach

Adds opt-in clientMetadata option to identify Parse Server instances in database logs during connection handshakes. Disabled by default to avoid data transfer overhead. The option is database-agnostic and can be used with MongoDB, Postgres, or other database adapters in the future.

Note

The feature is explicitly implemented as opt-in. We believe it is in developers’ best interest for this to remain opt-in, mainly to not by default silently reveal metadata about a developer’s infrastructure or stack to a third party (e.g. a DBaaS provider). By definition, that weakens the security posture and violates the principle of explicit consent.

Implementation:

• New Parse Server option databaseOptions.clientMetadata
• When set, passes driverInfo to database client: { name: <custom_metadata.name>, version: <custom_metadata.version> }
• Updated MongoStorageAdapter and GridFSBucketAdapter to conditionally set metadata
• Tests updated to handle MongoDB driver's default behavior of creating empty driverInfo objects

Without this option, no metadata is sent (current behavior maintained).

Tasks

• Add tests
• Add security check

Summary by CodeRabbit

• New Features

  • Added client metadata configuration support, allowing applications to provide name and version information for identification in database logs and monitoring.

• Tests

  • Added verification tests for client metadata handling in MongoDB adapter connections.

• Chores

  • Updated configuration environment variable mappings and defaults for client metadata support.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[parseplatformorg]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

This PR adds support for custom client metadata that can be passed to MongoDB driver connections. The feature introduces configuration options, environment variable mappings, adapter implementations to inject driver metadata, and test coverage to verify the metadata is properly transmitted to the MongoDB client.

Changes

Cohort / File(s)	Summary
Configuration & Options Definitions resources/buildConfigDefinitions.js, src/Options/Definitions.js, src/Options/index.js, src/Options/docs.js	Introduces new ClientMetadata type with name and version fields, adds clientMetadata option to ParseServerOptions with environment variable support (PARSE_SERVER_CLIENT_METADATA and nested environment variable prefix mappings), and documents the new public API.
Storage Adapters Implementation src/Adapters/Storage/Mongo/MongoStorageAdapter.js, src/Adapters/Files/GridFSBucketAdapter.js	Both adapters now accept and store clientMetadata from options in a private field, then conditionally inject a driverInfo object (containing name and version) into the MongoDB connection options before connecting.
Database Options Filtering src/defaults.js	Adds 'clientMetadata' to the ParseServerDatabaseOptions array to filter it out before passing database options to the MongoDB client.
Test Coverage spec/MongoStorageAdapter.spec.js, spec/GridFSBucketStorageAdapter.spec.js	Adds two test suites ("MongoDB Client Metadata") verifying that: (1) by default no custom driver metadata is passed to MongoClient, and (2) when clientMetadata is provided, the MongoDB driverInfo includes the specified name and version.

Sequence Diagram(s)

sequenceDiagram
    participant Config as Configuration / Environment
    participant Parser as ParseServer Options Parser
    participant Adapter as MongoStorageAdapter / GridFSBucketAdapter
    participant MongoDrv as MongoDB Driver (MongoClient)
    participant MongoSvr as MongoDB Server

    Config->>Parser: PARSE_SERVER_CLIENT_METADATA env vars
    Parser->>Adapter: ParseServerOptions with clientMetadata
    Adapter->>Adapter: Store clientMetadata in _clientMetadata field
    Adapter->>Adapter: Read _clientMetadata during _connect()
    alt clientMetadata is provided
        Adapter->>Adapter: Create driverInfo object {name, version}
        Adapter->>Adapter: Inject driverInfo into MongoDB connection options
    end
    Adapter->>MongoDrv: connect() with options (potentially including driverInfo)
    MongoDrv->>MongoSvr: Initial handshake with driver metadata
    MongoSvr-->>MongoDrv: Connection established
    MongoDrv-->>Adapter: Connection ready

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix: GridFSBucketAdapter throws when using some Parse Server specific options in MongoDB database options #9915: Modifies how Parse Server specific database options are filtered before passing to MongoDB client, affecting the same defaults and adapter configuration flow.
• feat: Add options to skip automatic creation of internal database indexes on server start #9897: Updates MongoStorageAdapter's handling of mongo client options when connecting, potentially overlapping with the clientMetadata/driverInfo injection logic.
• feat: Add Parse Server option allowPublicExplain to allow Parse.Query.explain without master key #9890: Modifies MongoStorageAdapter's database options handling before MongoDB client connection, sharing similar code patterns for option preparation.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title accurately summarizes the main change: adding a clientMetadata option to send custom metadata to the database server.
Description check	✅ Passed	The pull request description covers the approach, implementation details, usage examples, and task completion status. It provides sufficient information about the feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[parse-github-assistant]

🚀 Thanks for opening this pull request!

[mtrezza]

@copilot rename the option to clientMetadata, since it may be used for Postgres or other DBs in the future.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.54%. Comparing base (ba3e760) to head (f7412ef).
⚠️ Report is 2 commits behind head on alpha.

Additional details and impacted files

@@            Coverage Diff             @@
##            alpha   #10017      +/-   ##
==========================================
- Coverage   92.54%   92.54%   -0.01%     
==========================================
  Files         190      190              
  Lines       15468    15477       +9     
  Branches      176      176              
==========================================
+ Hits        14315    14323       +8     
- Misses       1141     1142       +1     
  Partials       12       12              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

@copilot rename the option to clientMetadata, since it may be used for Postgres or other DBs in the future.

Renamed to clientMetadata in commit 74346fb. Updated all references including option name, environment variable (now PARSE_SERVER_CLIENT_METADATA), and documentation to be database-agnostic.

[mtrezza]

@copilot fix the failing CI:

1. MongoStorageAdapter MongoDB Client Metadata should not pass metadata to MongoClient by default

• Expected Object({ }) to be undefined.

2. GridFSBucket MongoDB Client Metadata should not pass metadata to MongoClient by default

• Expected Object({ }) to be undefined.

[Copilot]

@copilot fix the failing CI:

1. MongoStorageAdapter MongoDB Client Metadata should not pass metadata to MongoClient by default
   ...

Fixed in commit 9c86062. Updated tests to check that driverInfo.name is undefined (when driverInfo exists) instead of expecting the entire driverInfo object to be undefined. This handles the MongoDB driver creating an empty driverInfo object by default.

[mtrezza]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

resources/buildConfigDefinitions.js (1)

31-51: Fix the environment variable prefix for clientMetadata nested properties.

The ClientMetadata mapping in buildConfigDefinitions.js uses PARSE_SERVER_DATABASE_OPTIONS_CLIENT_METADATA_ as the prefix, which is incorrect. Since clientMetadata is a top-level ParseServerOptions property (not nested under DatabaseOptions), the nested properties (name, version) should use PARSE_SERVER_CLIENT_METADATA_ as the prefix instead.

This causes the generated environment variables in src/Options/Definitions.js to be PARSE_SERVER_DATABASE_OPTIONS_CLIENT_METADATA_NAME and PARSE_SERVER_DATABASE_OPTIONS_CLIENT_METADATA_VERSION, when they should be PARSE_SERVER_CLIENT_METADATA_NAME and PARSE_SERVER_CLIENT_METADATA_VERSION.

Update line 33 in resources/buildConfigDefinitions.js from:

ClientMetadata: 'PARSE_SERVER_DATABASE_OPTIONS_CLIENT_METADATA_',

to:

ClientMetadata: 'PARSE_SERVER_CLIENT_METADATA_',

Then run npm run definitions to regenerate src/Options/Definitions.js and src/Options/docs.js with the correct prefixes.

[parseplatformorg]

🎉 This change has been released in version 9.2.0-alpha.1