Add lookup context injection annotations

Author: oschwald

CHANGELOG.md

@@ -30,6 +30,9 @@ CHANGELOG
     match field names in the database: for records, component names are used;
     for classes, Java parameter names are used (when compiled with
     `-parameters`). Annotations still take precedence when present.
+  * Added `@MaxMindDbIpAddress` and `@MaxMindDbNetwork` annotations to inject
+    the lookup IP address and resulting network into constructors. Annotation
+    metadata is cached per type to avoid repeated reflection overhead.
 
 3.2.0 (2025-05-28)
 ------------------

README.md

@@ -160,6 +160,16 @@ Defaults for missing values
   ) { }
   ```
 
+Lookup context injection
+
+- Use `@MaxMindDbIpAddress` to inject the IP address being decoded.
+  Supported parameter types are `InetAddress` and `String`.
+- Use `@MaxMindDbNetwork` to inject the network of the resulting record.
+  Supported parameter types are `Network` and `String`.
+- Context annotations cannot be combined with `@MaxMindDbParameter` on the same
+  constructor argument. Values are populated for every lookup without being
+  cached between different IPs.
+
 You can also use the reader object to iterate over the database.
 The `reader.networks()` and `reader.networksWithin()` methods can
 be used for this purpose.

src/main/java/com/maxmind/db/CachedConstructor.java

@@ -8,5 +8,7 @@ record CachedConstructor<T>(
     Class<?>[] parameterTypes,
     java.lang.reflect.Type[] parameterGenericTypes,
     Map<String, Integer> parameterIndexes,
-    Object[] parameterDefaults
+    Object[] parameterDefaults,
+    ParameterInjection[] parameterInjections,
+    boolean requiresLookupContext
 ) {}