A few consideration on the open design questions:

Here's a blueprint for implementing a SourceForge lister, based on an exchange with a SourceForge tech contact:

lowering priority, as it's not needed for swh-fuse for now

Agreed. In terms of where this doc go, I think it should just be a new section under https://archive.softwareheritage.org/api/ , where we already have other stuff very similar in nature. And we will be able to link to the relevant section of it via # anchors, as we already do for, e.g., rate limit.

This is fine. Two things to do before merge though:

• make sure the commit message is mainly about non-ignoring user configuration, because this is the big change here, the logging is a nice addition but is marginal
• consider turning this warning logging.warning("No swh.fuse stanza found in global configuration") into just pass, because, again, it would be entirely legitimate for the user to have a global.yml without that stanza, so it's not even something to be warned about (and the user will know from other messages that their conf is not being used)

just a style matter: instead of "error during BLA: {err}", please use something like "cannot BLA: {err}", which is more relevant for the user

rebase

In a different test, I've seen the Too many request error, but only after Ctrl-C, with an asyncio issue:

ERROR:root:Unknown name during lookup: 'HEAD'
   unique: 1866, error: -2 (No such file or directory), outsize: 16
^CERROR:asyncio:Task exception was never retrieved
future: <Task finished name='Task-45' coro=<_session_loop() done, defined at /home/zack/.virtualenvs/swh/lib/python3.8/site-packages/_pyfuse3.py:28> exception=HTTPError('429 Client Error: Too Many Requests for url: https://archive.softwareheritage.org/api/1/content/sha1_git:642be81e2679d4524e736bafe6c4576360a9fd5c/raw/')>

This might be the key issue here, a missing (async) exception handler somewhere.

• doc: add tutorial for end users
• tutorial: add directory listing examples

submitted by mistake, should've been an update of D4296

Looks like a lot of unrelated error are hidden behind "unknown SWHID". For instance, using the Web API via the VPN with the VPN down, results in that error too, with the syscall hanging.
There seems to be two things to fix about this:

• more appropriate error reporting (rate limit exceeded, can't connect to API server, etc.)
• the syscall should not hang, but rather return the user space an appropriate failure (note indeed that these hangs are bad, of the kind you can't Ctrl-C out of)

join strings that fit on a single line