# scoutfs-notify

Observer-only file access notifications for [ScoutFS](https://github.com/versity/scoutfs),
distributed as a rebasable `git format-patch` series plus a small Go
userspace relay daemon.  Layers onto each upstream release with minimal
maintenance.

## What the series adds

Three patches against the scoutfs source tree:

1. **Kmod core** — a per-mount 64 KiB ring of 64-byte notification records and
   a single-reader drain ioctl (`SCOUTFS_IOC_READ_NOTIFY`, nr 25).  Emit is
   non-blocking, drop-on-full; the monotonic `seq` field exposes drops to
   consumers.  Three percpu counters (`notify_emitted`,
   `notify_dropped_ring_full`, `notify_reader_attached`).  No mount option,
   no sysfs toggle.
2. **Kmod hooks** — `->open` wrapper and READ emit in
   `scoutfs_file_aio_read` / `scoutfs_file_read_iter`.  Every hook is a
   single predicted-false branch when no reader is attached.  Nothing in
   the data-waiter state machine is touched.
3. **scoutfs-notifyd (Go)** — userspace daemon that binds
   `/run/scoutfs/<fsid>/notify.sock` (AF_UNIX SOCK_SEQPACKET, mode 0600,
   root-only), drains the ring, and broadcasts each record to connected
   clients.  Pure-stdlib Go; no external module dependencies.  Shipped
   with a systemd template unit `scoutfs-notifyd@<mountpoint>.service`.

## Base

Currently rebased against:

    scoutfs v1.29

See [base.txt](./base.txt).

## Build dependencies added

On top of the stock scoutfs build requirements, patch 3 adds:

* `golang >= 1.21` on the build host (RHEL/EL9: `golang`, EL8: `go-toolset`).
  Debian 12 / Ubuntu 22.04+: `golang-go`.

The Go build is offline (`GOPROXY=off`) — no network access required at
build time.  `CGO_ENABLED=0` so the produced binary is a pure-Go static
ELF.

## Applying

```sh
./apply.sh /path/to/scoutfs
```

Runs `git am --3way` on each patch.  For a tarball instead of a git tree,
loop `patch -p1 < patches/*.patch`.

## Rebasing onto a new upstream release

```sh
git fetch --tags
git checkout -B notify v1.30
git am --3way patches/*.patch
# resolve any conflicts, git am --continue
git format-patch v1.30..notify -o patches/
# update base.txt and commit
```

## Tag history

    v1.29-notify-3   (current — Go daemon, struct alignment fix)
    v1.29-notify-2   (retired — C daemon; had latent ring-size compile bug)
    v1.29-notify-1   (retired — shipped mount options)

## Quick smoke test after installation

```sh
systemctl enable --now scoutfs-notifyd@mnt-scoutfs.service
FSID=$(stat -f -c %i /mnt/scoutfs)   # or use your scoutfs cli
socat - UNIX-CONNECT:/run/scoutfs/${FSID}/notify.sock | xxd | head
# touch some files in /mnt/scoutfs in another terminal
```