Design an explicit Native AOT-compatible model mapping path

[KonstantinKritsin]

Design an explicit Native AOT-compatible model mapping path

Problem

We would like to use MaxMind.Db (and, transitively, MaxMind.GeoIP2) from
.NET Native AOT applications.

Enabling the AOT and trimming analyzers currently reports warnings in the
reader/deserializer path. A native-published smoke application can also fail
while constructing Metadata, because its non-public constructor is discovered
through reflection and may be removed by trimming.

A minimal preservation fix for Metadata is small and will be proposed
separately. It fixes that concrete runtime failure, but it does not make the
package fully AOT-compatible: the general Find<T> path still builds
deserialization metadata at runtime using reflection, including closed generic
construction.

Goal

Provide a public, statically analyzable database lookup path that:

• does not require runtime code generation;
• does not rely on unbounded reflection over user model types;
• preserves the existing mapping behavior (MapKey, nested records/classes,
  collections, nullable values, injected values, and network data);
• can be exercised by a real dotnet publish -p:PublishAot=true smoke test; and
• eventually allows the package to set <IsAotCompatible>true</IsAotCompatible>
  without suppressing analyzer warnings.

The existing reflection-based API can remain for compatibility and be
annotated honestly if necessary.

Proposed direction

Introduce an explicit descriptor/type-info abstraction for mapped models. The
descriptor would contain the object factory and member mappings needed by the
decoder. It could be:

1. supplied manually by a consumer;
2. generated at compile time by a source generator from the existing mapping
   attributes; and/or
3. shipped by higher-level packages such as MaxMind.GeoIP2 for their built-in
   response models.

Conceptually, the reader would gain an overload along these lines (names only
illustrative):

T? Find<T>(IPAddress address, IMaxMindDbTypeInfo<T> typeInfo);

The decoder would consume this descriptor instead of calling
Type.GetTypeInfo(), GetCustomAttributes(), MakeGenericType(), and reflected
constructors/setters for every model graph. The current Find<T>(...) overload
could keep using the reflection-backed descriptor builder.

This separates two concerns:

• the binary decoder, which can be AOT-safe; and
• model metadata discovery, which is currently reflection-based but can be
  moved to build time.

Suggested delivery sequence

1. Preserve the internal Metadata constructor and add a Native AOT smoke test
   (small correctness PR).
2. Agree on the descriptor API and supported mapping semantics in this issue.
3. Implement a descriptor-driven decoder path with tests matching the
   reflection path.
4. Add source generation or generated descriptors for first-party GeoIP2
   models.
5. Enable AOT compatibility metadata only after analyzer-clean build and
   native-publish/runtime tests.

Related GeoIP2 constraint

MaxMind.GeoIP2 also has a separate web-service concern: its reflection-based
System.Text.Json calls produce trimming/AOT warnings. A straightforward
source-generated context is not behavior-preserving today because the public
response records use init properties with non-null default initializers;
missing JSON members can become explicit null constructor arguments in
generated code. That should be handled independently (for example, internal
mutable wire DTOs plus mapping) rather than hidden with warning suppressions.

Would this descriptor/source-generation direction fit the project's API
design? If so, I can turn the proposal into a smaller API sketch and
implementation PR before changing the existing reader surface.

[horgh]

Thanks for the issues and the PRs! This has come up before and we have an open issue about it: maxmind/GeoIP2-dotnet#359. Since this is would be a large change, it's something we would want to design and implement ourselves if we were to do it. As such I don't think we'll be accepting PRs on this right now. Thank you for the interest though!

[KonstantinKritsin]

Thanks — that makes sense. I agree that the descriptor/source-generation work is a substantial design change and should be designed and owned by the MaxMind team. I’m not asking you to accept that design or commit to a timeline for #321 or maxmind/GeoIP2-dotnet#359.

Could I ask you to consider #322 separately?

It is intentionally not an implementation of the larger AOT design. It only preserves the existing Metadata constructor that the current reflection-based decoder already requires, and adds a native-publish/runtime regression test.

It does not:

• add or change a public API;
• change the mapping design;
• suppress the remaining AOT analyzer warnings;
• claim that the package is fully AOT-compatible or set IsAotCompatible.

Without this preservation, a Native AOT application may publish successfully and then fail deterministically at runtime when Reader tries to construct Metadata, because the required constructor has been trimmed.

With this small fix, the existing API can already be used in practical Native AOT scenarios when the consumer explicitly preserves the remaining reflection-based model graph. We have also validated this approach in a real linux-musl-x64 Native AOT consumer.

So the intended separation is:

• Preserve metadata constructor for Native AOT #322 — a narrow runtime-correctness fix for the existing implementation;
• Design an explicit Native AOT-compatible model mapping path #321 and NativeAOT support GeoIP2-dotnet#359 — the long-term, analyzer-clean AOT design, whenever and if the project decides to implement it.

Would you be open to reviewing #322 on that narrower basis? If the smoke-test project or CI scope makes the PR too large, I’m happy to reduce it to the minimal preservation change and whatever regression-test form you would prefer.

If you would still prefer to defer even this narrow fix, I understand. A confirmation would help downstream consumers decide whether they need to keep carrying the preservation workaround themselves.

[horgh]

While I see that the change would make the library AOT compatible to some degree, it seems like there would be a number of limitations, and I don't think we would want to encourage it being used that way. I think we would prefer to have a more complete solution in place if we were to make it compatible. As such I don't think we'll take the change today. Sorry about that!