Support FUSE clients without READDIRPLUS (fall back to plain readdir)

[zeddybot]

Problem

pyfuse3 cannot be used at all under a FUSE client that implements plain
FUSE_READDIR but not FUSE_READDIRPLUS. Two independent things break:

1. Init aborts. fuse_init raises RuntimeError('Kernel too old, pyfuse3 requires kernel 3.9 or newer!') whenever the connection does not advertise
   FUSE_CAP_READDIRPLUS, so the mount never comes up.

2. Plain readdir is unimplemented. pyfuse3 registers only
   fuse_ops.readdirplus. A client that issues a plain FUSE_READDIR hits a
   NULL operation and libfuse answers ENOSYS, so directory listings fail even
   if init is bypassed.

The motivating client is gVisor's sentry, whose VFS
implements plain FUSE_READDIR but not FUSE_READDIRPLUS
(google/gvisor#3404, open since
2020). Running any pyfuse3 filesystem inside a gVisor sandbox is currently
impossible.

Plain FUSE_READDIR (opcode 28) is the mandatory FUSE baseline;
FUSE_READDIRPLUS (opcode 44, FUSE 7.21 / Linux 3.9) is a negotiated
optimization that bundles each entry's attributes to save a follow-up LOOKUP.
libfuse treats them as independent, optional vtable slots — its own
hello_ll.c implements only plain readdir, and passthrough_ll.c implements
both and branches on a plus flag.

Fix

• Register both operations. fuse_ops.readdir is now registered alongside
  fuse_ops.readdirplus; the client's opcode selects which is invoked. No new
  init/Operations flag is introduced — the client already advertises what it
  supports, so auto-detection is the right axis.
• Stop requiring READDIRPLUS. fuse_init no longer raises when
  FUSE_CAP_READDIRPLUS is absent. (FUSE_CAP_READDIRPLUS_AUTO is still
  cleared, so a capable Linux client keeps sending READDIRPLUS.)
• Share one async path. Both entry points funnel into the existing
  fuse_readdirplus_async. A new read-only attribute ReaddirToken.plus
  records which request the client made, and readdir_reply emits
  fuse_add_direntry (plain) or fuse_add_direntry_plus accordingly.

Correctness — lookup counts

READDIRPLUS entries take an implicit per-entry kernel lookup reference (balanced
later by FORGET); plain READDIR entries take none. The Operations.readdir
contract therefore now depends on token.plus:

• token.plus is True → each entry for which readdir_reply returns True takes
  a lookup reference; the filesystem must increase the inode's lookup count
  (unchanged behaviour).
• token.plus is False → the kernel takes no reference; the filesystem must
  not increase the lookup count, or the inode leaks with no balancing
  FORGET.

This is documented on Operations.readdir and applied in the passthroughfs
example (its _add_path bookkeeping is now gated on token.plus).

Compatibility

Inert on Linux. A normal Linux kernel always negotiates READDIRPLUS, so
token.plus is always True, the new plain-readdir callback is never invoked,
and byte-for-byte behaviour is unchanged. The only public surface added is one
read-only attribute (ReaddirToken.plus); no handler signature changes.

Testing

• No-regression (CI). The full test/ suite passes unchanged. Fs.readdir
  now asserts token.plus is True (a normal kernel never sends plain
  FUSE_READDIR), and a new test_readdir forces opendir+readdir through a
  real listing so the assertion and the new attribute are exercised from Python.
  A stock kernel cannot drive the plain-readdir branch, so CI proves only that
  nothing regresses — see below for the branch's real coverage.

• Plain-readdir branch (under gVisor). Verified by building the patched
  wheel and running a pyfuse3 hello filesystem inside a gVisor (runsc)
  sandbox. Before/after transcript, same code, same image:

  # BEFORE (stock) — mount fails, listing impossible
  $ runsc do -- python3 hello.py /tmp/mp & ls /tmp/mp; cat /tmp/mp/hello
  cat: /tmp/mp/hello: Transport endpoint is not connected
  RuntimeError: Kernel too old, pyfuse3 requires kernel 3.9 or newer!
      at src/pyfuse3/handlers.pxi:35 in fuse_init
  
  # AFTER (patched) — listing and read succeed
  $ runsc do -- python3 hello.py /tmp/mp & ls /tmp/mp; cat /tmp/mp/hello
  hello
  ls_exit=0
  Hello World from pyfuse3!
  cat_exit=0
  # daemon stderr: readdir called: token.plus=False   (plain FUSE_READDIR branch)
  
  # CONTROL (patched, normal Linux kernel via runc) — unchanged
  hello
  Hello World from pyfuse3!
  # daemon stderr: readdir called: token.plus=True     (READDIRPLUS still negotiated)
  

Open question

Happy to add a lower-level readdir_reply(..) unit test that constructs a
token with plus=False and asserts a plain fuse_dirent record is emitted,
if you'd prefer in-CI coverage of the plain path. It's fragile to build outside
a live request, so I left it out — let me know your preference.

[Nikratio]

Could you please clarify which agent was used for this PR, and to what extent human oversight was applied?

[zeddybot]

Could you please clarify which agent was used for this PR, and to what extent human oversight was applied?

thank you for the quick response! this pr was authored by claude opus 4.8 in the claude code harness. i've reviewed all the code by hand, and tested it on gvisor + on a linux machine that supports readdir_plus and it seems to work for me. please do let me know if i can do anything else for you here!

[Nikratio]

I can't help but think I'm communicating with an agent here again, rather than a human. Sorry.

[zeddybot]

hey no this is me writing this by hand, not an agent - i did have claude write the pr but i saw your comment and responded by hand