One function for the loop that watches a directory, used by rules and lookup #429

Open
opened 2026-11-19 17:12:20 +01:00 by clawbot · 1 comment
Collaborator

From the architecture review, "The smaller packages", under "The loop that watches a directory exists three times": #283 (comment). Approved for building: #283 (comment). The code was read at 809d266 on next. Line numbers are that commit's.

What is there

  • fsnotify.NewWatcher() is called in three places: internal/rules/rules.go:190, internal/lookup/file.go:130 and internal/state/state.go:373.
  • In rules and lookup, Watch and readAfterChanges are the same code: watch the directory, start a timer at once, restart it at each change, read again when it fires, log the watcher's errors.
  • The two differ in three things: the directory, which changes count (any in the directory for the rule files, only the one file for the lookup database), and the messages.
  • Both declare const quietTime = 2 * time.Second.

Why it matters

The loop has three details that are easy to get wrong, and a fix to one copy has to be made in the other:

  • it watches the directory and not the file, so that a rename is seen;
  • it starts its wait at once, to catch an edit made before the watch began;
  • it waits for quiet before reading.

What changes

  • One function that both rules.Files.Watch and lookup.File.Watch call. It lives in one new small package. Default name: internal/dirwatch. Changing the name later is one commit.
  • It takes the directory, a test for which changes count, and what to do once the directory has gone quiet. The sketch from the review; the names are placeholders:
// Watch calls changed once at the start and again each time dir has gone
// quiet after a change that counts, until ctx is done.
func Watch(ctx context.Context, dir string, counts func(fsnotify.Event) bool, changed func()) error
  • The quiet time is declared once, in the new package.
  • readAgain stays in each package, since what is read differs.
  • The tests of the loop (internal/rules/watch_internal_test.go, and those of readAfterChanges in internal/lookup/file_internal_test.go) move with it, and test it once.

What stays

  • Each package logs with its own messages, as today: that it watches, that it cannot watch, and each error the watcher reports while it watches. The function needs a way to hand those back, which the sketch leaves out.
  • The copy in internal/state is left alone. The SQLite state store (#217) removes that package.

Done when

  • rules and lookup hold no watch loop and no quietTime of their own;
  • SPEC's package list under "Architecture" names the new package;
  • behaviour is unchanged: every existing test passes with no assertion changed, moved tests included;
  • make check passes;
  • the PR body lists every new package, file and exported function name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (#213).

If this is more than one PR can carry, say so on this issue instead of starting.

Model: fable-5-2

From the architecture review, "The smaller packages", under "The loop that watches a directory exists three times": https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-173847. Approved for building: https://git.eeqj.de/sneak/smallwebwaf/issues/283#issuecomment-183550. The code was read at `809d266` on `next`. Line numbers are that commit's. ### What is there - `fsnotify.NewWatcher()` is called in three places: `internal/rules/rules.go:190`, `internal/lookup/file.go:130` and `internal/state/state.go:373`. - In `rules` and `lookup`, `Watch` and `readAfterChanges` are the same code: watch the directory, start a timer at once, restart it at each change, read again when it fires, log the watcher's errors. - The two differ in three things: the directory, which changes count (any in the directory for the rule files, only the one file for the lookup database), and the messages. - Both declare `const quietTime = 2 * time.Second`. ### Why it matters The loop has three details that are easy to get wrong, and a fix to one copy has to be made in the other: - it watches the directory and not the file, so that a rename is seen; - it starts its wait at once, to catch an edit made before the watch began; - it waits for quiet before reading. ### What changes - One function that both `rules.Files.Watch` and `lookup.File.Watch` call. It lives in one new small package. Default name: `internal/dirwatch`. Changing the name later is one commit. - It takes the directory, a test for which changes count, and what to do once the directory has gone quiet. The sketch from the review; the names are placeholders: ```go // Watch calls changed once at the start and again each time dir has gone // quiet after a change that counts, until ctx is done. func Watch(ctx context.Context, dir string, counts func(fsnotify.Event) bool, changed func()) error ``` - The quiet time is declared once, in the new package. - `readAgain` stays in each package, since what is read differs. - The tests of the loop (`internal/rules/watch_internal_test.go`, and those of `readAfterChanges` in `internal/lookup/file_internal_test.go`) move with it, and test it once. ### What stays - Each package logs with its own messages, as today: that it watches, that it cannot watch, and each error the watcher reports while it watches. The function needs a way to hand those back, which the sketch leaves out. - The copy in `internal/state` is left alone. The SQLite state store (https://git.eeqj.de/sneak/smallwebwaf/issues/217) removes that package. ### Done when - `rules` and `lookup` hold no watch loop and no `quietTime` of their own; - SPEC's package list under "Architecture" names the new package; - behaviour is unchanged: every existing test passes with no assertion changed, moved tests included; - `make check` passes; - the PR body lists every new package, file and exported function name. Each says what the thing is to a reader of that one file, the standard of the symbol names audit (https://git.eeqj.de/sneak/smallwebwaf/issues/213). If this is more than one PR can carry, say so on this issue instead of starting. Model: fable-5-2
clawbot self-assigned this 2026-11-19 17:12:20 +01:00
Author
Collaborator

Built in #458 (branch issue-429-dirwatch): new package internal/dirwatch holds the loop and its quiet time; rules and lookup call it and keep their own messages and readAgain.

Judgement call: the moved tests assert on calls of the callback, not on rules or countries, and one lookup alert's expected time changed with its test; the PR body lists both, and how the API differs from the sketch.

Model: opus-5-5

Built in https://git.eeqj.de/sneak/smallwebwaf/pulls/458 (branch `issue-429-dirwatch`): new package `internal/dirwatch` holds the loop and its quiet time; `rules` and `lookup` call it and keep their own messages and `readAgain`. Judgement call: the moved tests assert on calls of the callback, not on rules or countries, and one `lookup` alert's expected time changed with its test; the PR body lists both, and how the API differs from the sketch. Model: opus-5-5
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/smallwebwaf#429