ApiFeatures.Mqtt.MongoDatabases 9.2.0

ApiFeatures.Mqtt.MongoDatabases

MongoDB persistence for the MQTT module. Isolated from ApiFeatures.Mqtt.Apis so the Mongo layer can be composed by the host and swapped without touching the domain (ApiFeatures.Mqtt.Cores) or the API surface (ApiFeatures.Mqtt.Apis).

Contents

• Databases/MongoMqttDatabaseContext.cs — the Mongo client/database/collections, index creation, and BSON class-map registration.
• Serializers/MqOptionsBsonSerializer.cs — polymorphic BSON serializer for MqOptions (HiveMQ / self-hosted broker options).
• Models/Options/MongoMqttDatabaseOptions.cs — extends the shared ApiFeatures.Modules.Cores.Models.Options.ModuleMongoDatabaseOptions (Type == Mongo, broken-out connection components: Host, Port, DatabaseName, Username, Password, AuthenticationDatabase, ReplicaSet, UseTls — no single connection string), plus the MQTT-specific Collections (per-collection name overrides).
• Models/Options/MongoMqttDatabaseCollectionOptions.cs — one nullable name override per collection (Mqtts, MqttConnections, Brokers, BrokerUsers); null/blank falls back to the agreed PascalCase default (Mqtts, MqttConnections, Brokers, BrokerUsers).
• Services/{MqttService,MqttConnectionService,BrokerService,BrokerUserService}.cs — Mongo-backed implementations of the ApiFeatures.Mqtt.Cores.Interfaces service contracts.
• Extensions/MqttMongoDatabaseExtensions.cs — WithMongoDatabase(this IServiceCollection, options) composition entry point.

Options and client settings

MongoMqttDatabaseOptions -> ModuleMongoDatabaseOptions -> DataMagic MongoDatabaseOptions. DataMagic's field semantics apply. MongoMqttClientSettingsFactory.Create(options) (pure, no I/O) builds the client settings:

• Servers = [new MongoServerAddress(Host, Port)]. Port is a non-nullable int (DataMagic's model default 27017 applies when the key is absent during configuration binding or when options are built in code); there is no Port ?? 27017 fallback in this provider. Host likewise defaults to localhost in DataMagic's model. The host app (Task 5) is what makes these keys required.
• When Username is non-blank: Credential = MongoCredential.CreateCredential(AuthenticationDatabase, Username, Password). AuthenticationDatabase is used as-is and defaults to admin. A blank Username means anonymous.
• When ReplicaSet is non-blank: ReplicaSetName = ReplicaSet (works with a single host).
• UseTls = options.UseTls (off unless enabled).
• DatabaseName is the database.

Validation

WithMongoDatabase calls EnsureValidForMongo() first, so invalid settings stop host composition with an InvalidModuleDatabaseOptionsException naming the setting (for example MongoMqttDatabaseOptions.Host). Rules: supported Type, non-blank Host, Port 1-65535, non-blank DatabaseName, and a non-blank AuthenticationDatabase when Username is set. The context constructor runs the same check.

GUID serialization

The former uuidRepresentation=standard connection-string hint is not needed — the context has always set GuidSerializer(GuidRepresentation.Standard) explicitly on every entity's Guid-typed BSON class-map member (MqttEntity.Id, MqttConnectionEntity.Id/MqttId, BrokerEntity.Id, BrokerUserEntity.Id/BrokerId). Those class maps move here unchanged, so GUID serialization behaviour is identical.

Breaking changes (no compatibility, DataMagic defaults win)

• AuthenticationDatabase now defaults to admin. A deployment with a Username but no AuthenticationDatabase previously authenticated against DatabaseName; it now authenticates against admin. Set AuthenticationDatabase explicitly if the user lives in the app database.
• Port is a plain int with no ?? 27017 fallback in this provider; the host (Task 5) makes the key required.
• Blank Host / DatabaseName fail at composition instead of at first use.

Collection-name defaults

The pre-existing codebase had two different defaults for the same collections: the context's internal fallback ("mqtts", "mqttConnections", "Brokers", "BrokerUsers", used only when Collections was null) and the options class's documented defaults ("Mqtts", "MqttConnections", "Brokers", "BrokerUsers", used when a non-null Collections left a property at its default). This project resolves that inconsistency to one agreed PascalCase default per collection — MongoMqttDatabaseCollectionOptions.DefaultMqtts / DefaultMqttConnections / DefaultBrokers / DefaultBrokerUsers — matching the documented options defaults and the real demo host's explicit appsettings.Development.json values (so the running app and any consumer with an explicit Collections section are unaffected). A null or whitespace-only override falls back to the default.

Usage

using ApiFeatures.Mqtt.MongoDatabases.Extensions;
using ApiFeatures.Mqtt.MongoDatabases.Models.Options;

var mongoOptions = new MongoMqttDatabaseOptions
{
    Host = "localhost",
    Port = 27017,
    DatabaseName = "demo-mqtt",
    // Username/Password/AuthenticationDatabase/ReplicaSet/UseTls optional
    Collections = new MongoMqttDatabaseCollectionOptions
    {
        Mqtts = "Mqtts",
        MqttConnections = "MqttConnections",
        Brokers = "Brokers",
        BrokerUsers = "BrokerUsers"
    }
};

builder.Services.WithMongoDatabase(mongoOptions);

WithMongoDatabase registers MongoMqttDatabaseContext plus IMqttService, IMqttConnectionService, IBrokerService, and IBrokerUserService (all keyed ApiFeatures.Mqtt.Cores.Constants.ServiceKeys.Default, scoped). It does not register IBrokerUserPasswordHasher — the host must also call AddMqttsModule(...) (from ApiFeatures.Mqtt.Apis), which registers the hasher implementation unconditionally; BrokerUserService resolves it lazily at request time from the same container, so call order between WithMongoDatabase and AddMqttsModule does not matter.