ngclient: Be better with concurrent instances

[jku]

Users may run multiple updaters at the same time -- it's not useful but it can happen with longer dependency chains like sigstore/sigstore-python#1403: model-signing uses sigstore-python which uses python-tuf...

Currently we don't handle the potential conflicts WRT reading and writing metadata and target files to local cache that result from concurrent updaters. This is especially an issue with windows where concurrent file access leads to issues more often but it can be problematic in linux too -- this is why currently we just document Updater as "should be a singleton".

Possible improvement: lockfile

I think it makes sense to not try to solve this for just a single process but multiple real processes running updaters (something I can easily imagine happening in real life). In that case I think a lock file per repository would be best we can do:

• check for lock file before reading/writing
• create lock file, read/write, remove lock file

The reason this hasn't been done is that lockfiles are a pain to do especially cross platform.

Some open questions:

• what to do when a lock file exists -- log a warning and wait (for how long?)? I don't usually like when libraries wait for things but maybe this works? What if the lock file is stale (let's say hours old)?
• manually handling lockfiles in a way that works on windows is painful... but we've also done a lot of work to avoid unnecessary dependencies in this project. Using a dependency for this is likely the smaller evil
• when exactly do we lock?
  • locking for lifetime of Updater probably has annoying side effects and is not expected by users
  • locking for duration of refresh() and get_targetinfo() seems logical at least at first glance. Locking for duration of download_target() is probably less important but could be done

Possible improvement: global state

If we are not interested in multiple processes but just multiple threads with updaters, we could always add some global state tracking... It sounds quite unappealing but possible. I feel like I'd rather advice python-tuf users to use ngclient Updater as a "per-repository-singleton"?

CC @spencerschrock, let me know if you have thoughts

[spencerschrock]

Possible improvement: lockfile

I'll just chime in here that lockfiles were what was discussed originally in model-transparency:
sigstore/model-transparency#465 (comment)

Of course it's easier to say lockfile than to be the one to implement it :)

[stefanberger]

I have changed it (= venv/lib64/python3.13/site-packages/tuf/ngclient/updater.py) locally to this here and it seems to work:

    def _update_root_symlink(self) -> None:
        """Symlink root.json to current trusted root version in root_history/"""
        linkname = os.path.join(self._dir, "root.json")
        version = self._trusted_set.root.version
        current = os.path.join("root_history", f"{version}.root.json")

        with open(os.path.join(self._dir, current + ".lock"), "wb") as f:            <---- create new file; could also be just '.lock'
            lock_file(f)                                                             <---- lock it
            with contextlib.suppress(FileNotFoundError):
                os.remove(linkname)
            os.symlink(current, linkname)

This relies on file locking proposed here (not using 3rd party library): https://stackoverflow.com/questions/489861/locking-a-file-in-python

PS: What I don't know about TUF is what role the version plays here and what kind of effects the symbolic link would have on version 11 for example when version 12 set the link and version 11 reads a file that may not be in its version 11 format but in v12 format. In this case I would not know what the solution would be. The above resolves the immediate issue of avoiding a FileExistsError.

[jku]

the root.json symlink is not the only potential conflict. My initial thought was that it would make sense to have a high level lock in the public methods:

locking for duration of refresh() and get_targetinfo() seems logical at least at first glance. Locking for duration of download_target() is probably less important but could be done

If someone makes a convincing case that this high level lock is not needed or that more granular locking is useful, I'll listen...

WRT using a dependency or not, I think the Advisory locking (fcntl.lockf()) is appealing but there's a couple of downsides:

• IIUC this does not protect against access from multiple threads in same process (maybe this is not that relevant)
• I'm sure we will at some point end up debugging platform specific issues... testing this stuff comprehensively is so very difficult