Validate metadata the same way in both readers

HISTORY.rst

@@ -27,6 +27,17 @@ History
     during iteration, from another thread or from a signal handler.
   * Fixed a crash on free-threaded Python when two threads advanced the same
     iterator.
+  * Added the ``node_byte_size`` and ``search_tree_size`` properties to
+    ``Metadata``, as the pure Python ``Metadata`` has.
+
+* Metadata:
+
+  * The pure Python reader ignores unknown keys, which a new minor version of
+    the format can add. It raises ``InvalidDatabaseError`` for a missing key, a
+    value of the wrong type or out of range, an invalid ``ip_version`` or
+    format version, or a ``build_epoch`` of 0.
+  * The C extension ignores unknown keys. Previously, ``Reader.metadata()``
+    crashed on them.
 
 3.2.0 (2026-09-10)
 ++++++++++++++++++

extension/maxminddb.c

@@ -659,40 +659,62 @@ static PyObject *Reader_metadata(PyObject *self, PyObject *UNUSED(args)) {
         return NULL;
     }
 
-    MMDB_entry_data_list_s *entry_data_list;
-    int status =
+    // libmaxminddb checked the metadata when it opened the database, so take
+    // the numbers from its copy. Its strings end at the first NUL, so take
+    // the strings from the decoded metadata map, which keeps their lengths.
+    // Keys that Metadata does not know are ignored.
+    const MMDB_metadata_s *m = &mmdb_obj->mmdb->metadata;
+    MMDB_entry_data_list_s *entry_data_list = NULL;
+    int const status =
         MMDB_get_metadata_as_entry_data_list(mmdb_obj->mmdb, &entry_data_list);
     if (status != MMDB_SUCCESS) {
         reader_release_read_lock(mmdb_obj);
+        MMDB_free_entry_data_list(entry_data_list);
         PyErr_Format(state->MaxMindDB_error,
                      "Error decoding metadata. %s",
                      MMDB_strerror(status));
         return NULL;
     }
     MMDB_entry_data_list_s *original_entry_data_list = entry_data_list;
-
-    PyObject *metadata_dict = from_entry_data_list(state, &entry_data_list);
+    PyObject *map = from_entry_data_list(state, &entry_data_list);
     MMDB_free_entry_data_list(original_entry_data_list);
-    if (metadata_dict == NULL || !PyDict_Check(metadata_dict)) {
-        reader_release_read_lock(mmdb_obj);
-        PyErr_SetString(state->MaxMindDB_error, "Error decoding metadata.");
-        Py_XDECREF(metadata_dict);
-        return NULL;
+
+    PyObject *metadata = NULL;
+    if (map != NULL) {
+        // MMDB_open requires these keys, so a missing key is a bug.
+        PyObject *database_type = NULL;
+        PyObject *description = NULL;
+        PyObject *languages = NULL;
+        if (PyDict_Check(map)) {
+            database_type = PyDict_GetItemString(map, "database_type");
+            description = PyDict_GetItemString(map, "description");
+            languages = PyDict_GetItemString(map, "languages");
+        }
+        if (database_type == NULL || description == NULL ||
+            languages == NULL) {
+            PyErr_SetString(state->MaxMindDB_error,
+                            "Error decoding metadata.");
+        } else {
+            metadata = PyObject_CallFunction(state->Metadata_Type,
+                                             "HHKOOHOIH",
+                                             m->binary_format_major_version,
+                                             m->binary_format_minor_version,
+                                             (unsigned long long)m->build_epoch,
+                                             database_type,
+                                             description,
+                                             m->ip_version,
+                                             languages,
+                                             (unsigned int)m->node_count,
+                                             m->record_size);
+        }
+        Py_DECREF(map);
     }
 
     reader_release_read_lock(mmdb_obj);
-
-    PyObject *args = PyTuple_New(0);
-    if (args == NULL) {
-        Py_DECREF(metadata_dict);
-        return NULL;
+    // libmaxminddb does not check that the metadata strings are UTF-8.
+    if (metadata == NULL && PyErr_ExceptionMatches(PyExc_UnicodeDecodeError)) {
+        PyErr_SetString(state->MaxMindDB_error, "Error decoding metadata.");
     }
-
-    PyObject *metadata =
-        PyObject_Call(state->Metadata_Type, args, metadata_dict);
-
-    Py_DECREF(metadata_dict);
-    Py_DECREF(args);
     return metadata;
 }
 
@@ -1323,6 +1345,44 @@ static PyMemberDef Metadata_members[] = {
      NULL},
     {NULL, 0, 0, 0, NULL}};
 
+static PyObject *Metadata_node_byte_size(PyObject *self,
+                                         void *UNUSED(closure)) {
+    Metadata_obj *obj = (Metadata_obj *)self;
+    PyObject *four = PyLong_FromLong(4);
+    if (four == NULL) {
+        return NULL;
+    }
+    PyObject *node_byte_size = PyNumber_FloorDivide(obj->record_size, four);
+    Py_DECREF(four);
+    return node_byte_size;
+}
+
+static PyObject *Metadata_search_tree_size(PyObject *self,
+                                           void *UNUSED(closure)) {
+    Metadata_obj *obj = (Metadata_obj *)self;
+    PyObject *node_byte_size = Metadata_node_byte_size(self, NULL);
+    if (node_byte_size == NULL) {
+        return NULL;
+    }
+    PyObject *search_tree_size =
+        PyNumber_Multiply(obj->node_count, node_byte_size);
+    Py_DECREF(node_byte_size);
+    return search_tree_size;
+}
+
+// These match the properties of the pure Python Metadata class.
+static PyGetSetDef Metadata_getset[] = {{"node_byte_size",
+                                         Metadata_node_byte_size,
+                                         NULL,
+                                         "The size of a node in bytes.",
+                                         NULL},
+                                        {"search_tree_size",
+                                         Metadata_search_tree_size,
+                                         NULL,
+                                         "The size of the search tree.",
+                                         NULL},
+                                        {NULL, NULL, NULL, NULL, NULL}};
+
 // =============================================================================
 // Type specs for heap type conversion (PEP 489)
 // =============================================================================
@@ -1351,6 +1411,7 @@ static PyType_Slot Metadata_Type_slots[] = {
     {Py_tp_new, Metadata_new},
     {Py_tp_methods, Metadata_methods},
     {Py_tp_members, Metadata_members},
+    {Py_tp_getset, Metadata_getset},
     {0, NULL},
 };
 

maxminddb/extension.pyi

@@ -127,3 +127,11 @@ class Metadata:
         record_size: int,
     ) -> None:
         """Create new Metadata object from the metadata fields in the spec."""
+
+    @property
+    def node_byte_size(self) -> int:
+        """The size of a node in bytes."""
+
+    @property
+    def search_tree_size(self) -> int:
+        """The size of the search tree."""

maxminddb/reader.py

@@ -24,7 +24,7 @@
 
     from typing_extensions import Self
 
-    from maxminddb.types import Record
+    from maxminddb.types import Record, RecordDict
 
 _IPV4_MAX_NUM = 2**32
 _REOPENED = "Attempt to iterate over a reopened MaxMind DB. Create a new iterator."
@@ -95,24 +95,22 @@ def __init__(
 
             metadata_start += len(self._METADATA_START_MARKER)
             metadata_decoder = Decoder(self._buffer, metadata_start)
-            (metadata, _) = metadata_decoder.decode(metadata_start)
+            try:
+                (metadata, _) = metadata_decoder.decode(metadata_start)
+            except (TypeError, UnicodeDecodeError) as e:
+                # For example, a map key that is a list, or a string that is
+                # not UTF-8. The C extension raises InvalidDatabaseError too.
+                msg = f"Error reading metadata in database file ({filename})."
+                raise InvalidDatabaseError(msg) from e
 
             if not isinstance(metadata, dict):
                 msg = f"Error reading metadata in database file ({filename})."
                 raise InvalidDatabaseError(  # noqa: TRY301
                     msg,
                 )
 
-            # The MaxMind DB spec fixes these keys and their value types.
-            fields: dict[str, Any] = metadata
-            self._metadata = Metadata(**fields)
+            self._metadata = Metadata(**_metadata_fields(metadata, filename))
             self._record_size = self._metadata.record_size
-            if self._record_size not in (24, 28, 32):
-                msg = f"Unknown record size: {self._record_size}"
-                raise InvalidDatabaseError(msg)  # noqa: TRY301
-            if self._metadata.node_count < 0:
-                msg = f"Invalid node count: {self._metadata.node_count}"
-                raise InvalidDatabaseError(msg)  # noqa: TRY301
 
             # Traversal reads nodes below node_count. Once the tree fits, those
             # reads need no length checks of their own.
@@ -356,6 +354,86 @@ def __enter__(self) -> Self:
         return self
 
 
+# The type of each metadata value. libmaxminddb also rejects a database with a
+# missing key or a value of another type. It also checks the width and sign of
+# each integer, which the decoder does not report.
+_METADATA_TYPES: dict[str, type] = {
+    "binary_format_major_version": int,
+    "binary_format_minor_version": int,
+    "build_epoch": int,
+    "database_type": str,
+    "description": dict,
+    "ip_version": int,
+    "languages": list,
+    "node_count": int,
+    "record_size": int,
+}
+
+
+# The size in bits of each unsigned integer metadata value in libmaxminddb.
+_METADATA_UINT_BITS: dict[str, int] = {
+    "binary_format_major_version": 16,
+    "binary_format_minor_version": 16,
+    "build_epoch": 64,
+    "ip_version": 16,
+    "node_count": 32,
+    "record_size": 16,
+}
+
+
+def _metadata_fields(metadata: RecordDict, filename: object) -> dict[str, Any]:
+    """Return the known metadata fields after a check of their types.
+
+    A new minor version of the format can add keys. This ignores them.
+    """
+    prefix = f"Error reading metadata in database file ({filename})."
+    fields: dict[str, Any] = {}
+    for key, value_type in _METADATA_TYPES.items():
+        value = metadata.get(key)
+        # The exact type check rejects bool, a subclass of int.
+        valid = type(value) is value_type
+        if valid and isinstance(value, list):
+            valid = all(type(v) is str for v in value)
+        elif valid and isinstance(value, dict):
+            valid = all(type(k) is str and type(v) is str for k, v in value.items())
+        if not valid:
+            msg = f"{prefix} The {key} value is missing or has the wrong type."
+            raise InvalidDatabaseError(msg)
+        fields[key] = value
+
+    _check_metadata_ranges(fields, prefix)
+    return fields
+
+
+def _check_metadata_ranges(fields: dict[str, Any], prefix: str) -> None:
+    """Raise InvalidDatabaseError for a value that libmaxminddb rejects."""
+    # libmaxminddb stores each integer as an unsigned value of the size in
+    # _METADATA_UINT_BITS. The reader decodes only the version 2 format,
+    # ip_version drives the tree walk, and record_size picks the node layout.
+    # libmaxminddb also rejects node_count 0, but this reader accepts an empty
+    # search tree.
+    if fields["record_size"] not in (24, 28, 32):
+        msg = f"{prefix} Unknown record size: {fields['record_size']}."
+        raise InvalidDatabaseError(msg)
+    if fields["node_count"] < 0:
+        msg = f"{prefix} Invalid node count: {fields['node_count']}."
+        raise InvalidDatabaseError(msg)
+    for key, bits in _METADATA_UINT_BITS.items():
+        if not 0 <= fields[key] < 1 << bits:
+            msg = f"{prefix} The {key} value {fields[key]} is out of range."
+            raise InvalidDatabaseError(msg)
+    if fields["binary_format_major_version"] != 2:
+        version = fields["binary_format_major_version"]
+        msg = f"{prefix} Unsupported binary format version {version}."
+        raise InvalidDatabaseError(msg)
+    if fields["ip_version"] not in (4, 6):
+        msg = f"{prefix} The ip_version is {fields['ip_version']}, not 4 or 6."
+        raise InvalidDatabaseError(msg)
+    if fields["build_epoch"] == 0:
+        msg = f"{prefix} The build_epoch is 0."
+        raise InvalidDatabaseError(msg)
+
+
 @dataclass(kw_only=True, frozen=True)
 class Metadata:
     """Metadata for the MaxMind DB reader."""