Summary

The logic for connection string parsing and defaults is duplicated across multiple classes including ConnectionString, MongoUrl, MongoUrlBuilder, and MongoClientSettings. Given the same starting connection string URI, each class can produce a slightly different connection string. These differences include whether ampersands or semi-colons are used to separate options, whether or not the default database name is followed by a slash, and whether the default port (27017) is rendered or not.

Additionally each of these classes will at times modify the connection string, serialize it to a string, and then re-parse it. This often happens when calling ConnectionString.Resolve or MongoUrl.Resolve (and their async counterparts). This can lead to a mongodb+srv:// scheme URI being transliterated into a mongodb:// scheme URI. This is especially problematic in the case of SRV-only options such as srvMaxHosts because a valid mongodb+srv://SRV_RECORD_FQDN/?srvMaxHosts=2 is turned into an invalid mongodb://LIST_OF_SERVERS_AND_PORTS/?srvMaxHosts=2. This has required logic to skip validity checks such as the ConnectionString._isInternalRepresentation flag or reworking MongoUrl.Resolve to not re-parse a serialized (and invalid) connection string.

When a new connection string option is introduced, all of the above classes need to be updated appropriately often duplicating logic for validation and defaults across the classes.

Motivation

Who is the affected end user?

Users should have a consistent experience being able to set URI options in the connection string or through our API.
Driver engineers should be able to add new connection string URI options with minimal duplication.

How does this affect the end user?

Users have complained about inconsistent URI behaviour. (CSHARP-2887)
Driver engineers must spend additional time implementing and verifying correct behaviour when setting a new option via the connection string URI, via ConnectionString, via MongoUrl, via MongoUrlBuilder, and via MongoClientSettings. This can lead to subtle errors where certain combinations of valid options can only be set in one way but not another.

How likely is it that this problem or use case will occur?

Every user needs to parse or construct a URI to connect to a cluster. While problems are not frequent in this code, improvements and changes will affect all users of the driver.

If the problem does occur, what are the consequences and how severe are they?

The main consequence is subtle bugs in URI parsing or construction logic. These bugs might prevent you from configuring valid options in certain ways. For example, you might be able to specify an option in the URI string, but not when programatically creating a MongoUrl. Another possibility is that an invalid configuration is rejected in the connection string, but permitted in MongoClientSettings.

Inconsistencies can lead to user confusion and/or incorrect driver behaviour.

Is this issue urgent?

The current code has evolved over many years and generally works in common scenarios. While not urgent, it is desirable to clean up and improve this code in the 3.0 timeframe for the driver.

Is this ticket required by a downstream team?

No.

Is this ticket only for tests?

This ticket intends to improve the reliability and readability of our connection string URI parsing code.

Cast of Characters

Engineering Lead:
Document Author:
POCers:
Product Owner:
Program Manager:
Stakeholders:

Channels & Docs

Slack Channel

[Scope Document|some.url]

[Technical Design Document|some.url]