EOS table registry check

Checks that a PALEOS table on disk is the release the fwl-io registry pins. verify hashes a table once per process (again when the file changes on disk) and compares the digest with the pins an installed fwl-io manifest gives its file name and the name of the file it resolves to: of the two names, only those a registry pins are checked, and the digest must match a pin common to all of them, compared case-insensitively. Every pin must be an md5; a pin in another form stops the read and names the pin. Any failure of the check itself is a StaleTableError too; when fwl-io cannot be imported, every checked read raises MissingFwlIoError, a StaleTableError that names the file and how to install fwl-io. A table in its version directory under the current FWL_DATA that differs is fetched again through fwl-io; a table anywhere else that differs raises StaleTableError. A file name that no PALEOS registry lists, such as a table of your own or a PALEOS-API table, is not checked. StaleTableError is not a RuntimeError or ValueError, so a caller that turns those into a failed structure solve does not hide it.

`registry_guard`

Check that a PALEOS table on disk is the release the fwl-io registry pins.

A PALEOS table whose file name an installed fwl-io manifest registry pins is read only when its md5 is a pinned one. A table that differs is fetched again when it sits in its version directory under the current FWL_DATA and is refused anywhere else, so an older release is never read without notice. A file whose name no registry lists (a table of your own, a PALEOS-API table) is not checked, so a table of your own must not carry the name of a registry file. Without an importable fwl-io no file can be checked, since the manifest says which names are pinned, so every checked read raises MissingFwlIoError.

`StaleTableError`

Bases: Exception

A PALEOS table differs from the release its registry pins.

Not a RuntimeError or ValueError, so a caller that turns those into a failed structure solve does not hide it.

`MissingFwlIoError`

Bases: StaleTableError

fwl-io cannot be imported, so no PALEOS table can be checked against its registry.

A StaleTableError, so the PALEOS, Seager and melting-curve readers, which pass StaleTableError on and turn other errors into None, stop; not an ImportError, so the binary-cache reader, which rebuilds a cache it cannot unpickle, does not take it for a broken cache.

`verify(eos_file)`

Raise unless eos_file is the release its registry pins.

The digest must be pinned for the file name and, for a link, also for the name of the file it resolves to; names are compared case-insensitively. A file in its version directory under the current FWL_DATA is fetched again first and checked once more. A file whose names no PALEOS registry lists is not checked.

Raises:

Type	Description
`MissingFwlIoError`	If fwl-io cannot be imported; the message names `eos_file`.
`StaleTableError`	If the file is not a release pinned for its names and the pinned file cannot be put in its place, or if the check itself fails (an unreadable file, a broken registry, a pin that cannot be checked).

Source code in src/zalmoxis/eos/registry_guard.py

def verify(eos_file: str) -> None:
    """Raise unless ``eos_file`` is the release its registry pins.

    The digest must be pinned for the file name and, for a link, also for the name of the
    file it resolves to; names are compared case-insensitively. A file in its version
    directory under the current FWL_DATA is fetched again first and checked once more. A
    file whose names no PALEOS registry lists is not checked.

    Raises
    ------
    MissingFwlIoError
        If fwl-io cannot be imported; the message names ``eos_file``.
    StaleTableError
        If the file is not a release pinned for its names and the pinned file cannot be
        put in its place, or if the check itself fails (an unreadable file, a broken
        registry, a pin that cannot be checked).
    """
    with _checking(eos_file):
        _verify(eos_file)

`verify_digest(eos_file, digest, label=None)`

Raise unless digest is a pin common to the pinned names of eos_file: its own name and, for a link, the name of the file it resolves to, also when that file is gone.

Used for a binary cache whose text table is absent or unreadable: the cache carries the md5 of the table it was built from, and label (the cache file) names it in the error. A file whose names no PALEOS registry lists passes.

Raises:

Type	Description
`MissingFwlIoError`	If fwl-io cannot be imported.
`StaleTableError`	If a name is pinned and `digest` is not a pin common to the pinned names, or if the check itself fails (a broken registry, a pin that cannot be checked).

Source code in src/zalmoxis/eos/registry_guard.py

def verify_digest(eos_file: str, digest: str | None, label: str | None = None) -> None:
    """Raise unless ``digest`` is a pin common to the pinned names of ``eos_file``: its own
    name and, for a link, the name of the file it resolves to, also when that file is gone.

    Used for a binary cache whose text table is absent or unreadable: the cache carries
    the md5 of the table it was built from, and ``label`` (the cache file) names it in the
    error. A file whose names no PALEOS registry lists passes.

    Raises
    ------
    MissingFwlIoError
        If fwl-io cannot be imported.
    StaleTableError
        If a name is pinned and ``digest`` is not a pin common to the pinned names, or if
        the check itself fails (a broken registry, a pin that cannot be checked).
    """
    with _checking(label or eos_file):
        found = _accepted(eos_file)
        if found is not None and digest not in found[0]:
            raise _stale(label or eos_file, found[1], found[0], digest)

`file_md5(path)`

Return the md5 of path, hashed again when the file changes on disk.

Source code in src/zalmoxis/eos/registry_guard.py

def file_md5(path: str) -> str:
    """Return the md5 of ``path``, hashed again when the file changes on disk."""
    st = os.stat(path)
    key = (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns)
    if key not in _HASHES:
        _HASHES[key] = _md5(path)
    return _HASHES[key]