λgitsite

~ober/jerboa-inotify

Imported from ~/mine/jerboa-inotify

download snapshot

about

# jerboa-inotify

Linux inotify filesystem event monitoring for Jerboa.

Status: experimental and Linux-only. Treat this repository as a native FFI
filesystem component until the release gates in `SECURITY.md` and
`docs/ffi-boundary.md` are complete.

## Requirements

- Linux with inotify support
- Jerboa `jerbuild`
- C compiler

## Build And Test

```sh
make test-linux
make audit
make security
make platform-evidence
make sbom
make reproducibility-report
make release-evidence
```

On non-Linux hosts, `make test` transpiles the Jerboa source and skips runtime
tests. CI runs the real kernel tests on Ubuntu.

Dynamic builds must set `JERBOA_INOTIFY_LIB` to the absolute path of the
trusted directory containing `jerboa_inotify_shim.so`. The loader rejects
relative paths, current-working-directory searches, bare library names, and a
final shim path that is a symbolic link. Statically linked hosts are detected
from the registered native entry points and do not need this variable.

If `jerbuild` is not installed, the Makefile bootstraps the pinned Jerboa
release into `.jerboa/bin`.

`make release-evidence` records test output, platform evidence, native linkage
when Linux is available, SBOM manifests, and reproducibility output under
`dist/release-evidence/`. On non-Linux hosts it is expected to report partial
evidence because inotify runtime checks require the Linux kernel.

Production Linux support is blocked until `make platform-evidence` records
Linux runtime/linkage proof and overflow/backpressure proof through
`JERBOA_INOTIFY_TARGET_LINUX_PROOF_FILE` and
`JERBOA_INOTIFY_TARGET_OVERFLOW_PROOF_FILE`, or a Linux release host runs the
full evidence target directly. Production release hosts should set the matching
`JERBOA_INOTIFY_REQUIRE_TARGET_*_PROOF=1` variables when proof files are
required. Proof files must not contain private paths, hostnames, secrets, raw
production watch output, or raw command output.

## Usage

```scheme
(import (jerboa-inotify))

(define fd (inotify-init))
(define wd (inotify-add-watch fd "/path/to/watch"
             (bitwise-ior IN_CREATE IN_DELETE IN_MODIFY)))

(when (inotify-poll fd 5000)
  (for-each
    (lambda (ev)
      (printf "wd=~a mask=~a name=~a~%"
        (inotify-event-wd ev)
        (inotify-event-mask ev)
        (inotify-event-name ev)))
    (inotify-read-events fd)))

(inotify-rm-watch fd wd)
(inotify-close fd)
```

Consumers must handle `IN_Q_OVERFLOW` by rescanning watched state. Inotify does
not recursively watch directory trees. Production callers should follow
`docs/overflow-handling.md` for cache invalidation, backpressure, and path-log
redaction.

## API

| Function | Description |
| --- | --- |
| `(inotify-init)` | Create inotify instance, returns fd |
| `(inotify-close fd)` | Close inotify fd |
| `(inotify-add-watch fd path mask)` | Add watch, returns wd |
| `(inotify-rm-watch fd wd)` | Remove watch |
| `(inotify-poll fd timeout-ms)` | Poll for events |
| `(inotify-read-events fd)` | Read pending events |

## Event Record

| Accessor | Description |
| --- | --- |
| `(inotify-event-wd ev)` | Watch descriptor |
| `(inotify-event-mask ev)` | Event mask |
| `(inotify-event-cookie ev)` | Cookie for rename tracking |
| `(inotify-event-name ev)` | Filename or `#f` |

## Security

See `SECURITY.md`, `docs/ffi-boundary.md`, `docs/overflow-handling.md`, and
`docs/release-evidence.md`.

recent commits