#127 feat: unified headless backend and agent control socket

state
merged · 67bf3fe · merge commit
branch
feat/headless-control → main
opened
bnema ·
updated

Implements the ADR "Headless unifié et contrôle programmatique pour agents".

What

  • One headless backend with profiles. --backend=headless --profile=ephemeral|persistent; individual flags override profile defaults. --backend=server is a deprecated CLI alias of headless + persistent (warning on stderr; rejected with an explicit --profile). domain.BackendServer is gone.
  • Control socket per session ($XDG_RUNTIME_DIR/neferwl/sessions/<id>/control.sock), JSON lines, SO_PEERCRED same-uid, capability set advertised by hello with the command catalog (internal/domain/command.go, shared with the config validator).
  • Act, then observe. do/inject reply at committed, settled (default) or presented, or when an --until predicate holds (window-mapped/unmapped relative to the request, focused absolute). Replies carry a state diff, late windows and optional shots. Waits are bounded (5m timeout, 64 pending, busy above).
  • Injection through core: key, type, press/release, click, move, swipe use the real input path; refused with locked while the session is protected, as are control actions (except quit) and captures.
  • Captures: shot (PNG file, --inline base64, per-output) uses the existing capture pipeline fenced on the presented scene; shot --every-frame [--raw] [--dir] / shot --stop replaces --screenshot.
  • Sessions: session new|ls|rm, detached setsid child with ready fd, flock lifetime lock, target resolution -s > NEFERWL_SESSION > NEFERWL_CONTROL > WAYLAND_DISPLAY. Session logs under $XDG_STATE_HOME/neferwl/sessions/<id>/, pruned to 20.
  • Runtime outputs: output add WxH@Hz [--name] / output rm NAME (admin cap).
  • The systemd server unit runs --backend=headless --profile=persistent --session --session-id=server.

Breaking changes

  • --input and headless input scripts are removed (use the control CLI).
  • --screenshot / --screenshot-raw are removed (use shot / shot --every-frame).
  • --backend=server is an alias only.

Out of scope

Tokens/allowlist, MCP, event stream, semantic targeting, a DRM control socket, single-shot raw PQ.

Verification

  • make check, make race, make mocks-check, staticcheck ./..., make arch pass; -tags xwayland and -tags colorcheck app suites pass.
  • Headless e2e on a remote Arch host (49 checks): session new/ls/rm, query/state, do + --until, waits committed/presented, --shot, trailing flags, timeout cap, key/type/move/click/press/release/swipe, single and inline shots, every-frame frames + frames.ffconcat, runtime output add/shot/rm, help exit codes, persistent profile with config outputs, server alias + deprecation warning, packaged systemd unit as session server.
  • Lock refusal checked locally with swaylock: inject, shot, do and every-frame reply locked; query still works; session rm succeeds.
  • Wrap-up review (3 reviewers + targeted re-review); all findings fixed.

Known

TestXwaylandLineageTVSeat is intermittently flaky (timing in tv-seat/lineage placement); it fails on commits predating this change as well.

CommitSubjectAuthorDateSignatureStatus
88afa23test(capture): drop recorded frame reads before closing two-frame pipelinesbrice GPG Verified
73615ddtest(app): start the two-output recording once both outputs existbrice GPG Verified
31ecbd0fix(capture): read headless shots back on the CPU without sync filesbrice GPG Verified
a260967docs(skills): add the neferwl agent skillbrice GPG Verified
0098131docs(dev): make control.md the protocol referencebrice GPG Verified
b434a7cdocs: document headless sessions and agent controlbrice GPG Verified
a00eb01test(app): watch the session state directory in xwayland testsbrice GPG Verified
9b8bd53fix(ports): seal the continuous capture targetbrice GPG Verified
0a20a4drefactor(app): open the control socket in openControlbrice GPG Verified
ddfc620refactor(core): decide continuous capture in corebrice GPG Verified
99e50a5test(app): send control input through a typed inject helperbrice GPG Verified
c515818refactor(core): decide runtime output reply codes in corebrice GPG Verified
785ca4frefactor(control): take listener options as one valuebrice GPG Verified
717dff0refactor(control): parse output modes with domain.ParseOutputModebrice GPG Verified
bd81082refactor(control): size shots in core and encode them in placebrice GPG Verified
bc341cerefactor(control): split control handling, waits and one timeout signalbrice GPG Verified
2cb013atest(core): compare the command catalog with exported workspace actionsbrice GPG Verified
ca489c4test(app): keep the realtime directive on the cast startup helperbrice GPG Verified
b262287refactor(cli): reuse the control reply error in session rmbrice GPG Verified
61a048etest(control): do not pin the security snapshot count of injectionbrice GPG Verified
79a3652refactor(app): pass the control keymap channel as one optional parameterbrice GPG Verified
32ff54crefactor(core): decide control, session bus and startup terminal in the backend planbrice GPG Verified
ea4790brefactor(headlessbackend): drop startup screenshot optionsbrice GPG Verified
589835cfix(config): validate log.debug through the logger namesbrice GPG Verified
6bf0063perf(core): skip lineage observation for commits and idle wait timer stopsbrice GPG Verified
0e4d65fperf(wayland): reuse configure serial queues on ackbrice GPG Verified
3f696derefactor(domain): parse and format virtual output modes in one placebrice GPG Verified
193b8befix(core): record configures only after a successful sendbrice GPG Verified
9b8ca53docs(dev): document runtime output control requestsbrice GPG Verified
95ec50efix(headless): keep locked ahead of later continuous capture checksbrice GPG Verified
ade07b0fix(cli): reject control timeouts above 5mbrice GPG Verified
aad6dd9fix(control): bound shots by the request deadlinebrice GPG Verified
60c1a6ctest(core): cover an injected batch ended by quitbrice GPG Verified
7999cebfix(core): keep quit and wait-free requests usable at the control wait capbrice GPG Verified
38914cbrefactor(core): decide sized headless heads in the backend planbrice GPG Verified
3a03ba9test(core): skip the pending wait allocation budget under -racebrice GPG Verified
757344dfix(headless): reject relative frame directories and roll back partial startsbrice GPG Verified
1462fd9fix(sessiondir): remove a closed session directory under the registry lockbrice GPG Verified
9cbe40fperf(app): record shot sizes and reload the control keymap only with controlbrice GPG Verified
2f20e72fix(control): cap request timeouts and accept requests without idbrice GPG Verified
8dce768fix(core): forget presented sequences of removed outputsbrice GPG Verified
077d12ffix(control): bound control waits and timeoutsbrice GPG Verified
a835005fix(wayland): report X11 commits for unsized configuresbrice GPG Verified
72cf799docs(dev): document control actions refused while protectedbrice GPG Verified
3fa5a14fix(core): reply to control injections interrupted by a security changebrice GPG Verified
898e3f8fix(app): keep capture replies routed without control or hintsbrice GPG Verified
933eb76docs(dev): document optional control request idsbrice GPG Verified
2e11dccfix(cli): send shot --dir as an absolute pathbrice GPG Verified
b89e7d9docs(dev): document control CLI flags, bare state, hello reply and session logsbrice GPG Verified
f04616frefactor(demo): forward every input line as one control callbrice GPG Verified
dd64727docs(vulkan): name shot --every-frame --raw for HDR readbackbrice GPG Verified
58666b4fix(logging): open session logs explicitly and prune old session directoriesbrice GPG Verified
977bc47refactor(core): make the backend plan the single startup terminal decisionbrice GPG Verified
66d1d83test(cli): check the output request decode before asserting fieldsbrice GPG Verified
1bfe166fix(domain): name the expected syntax in until predicate errorsbrice GPG Verified
284a9cafix(cli): add session subverb help, refuse server with --profile, drop --exportbrice GPG Verified
bbb2e9cfix(cli): print bare state from neferwl state over controlbrice GPG Verified
0937088refactor(cli): drop the legacy display control socket and split dialPathbrice GPG Verified
b129bf0fix(cli): share completion flags between do and input verbs; add --shotbrice GPG Verified
336f139test(cli): isolate CLI tests from the live session environmentbrice GPG Verified
b782921refactor(domain)!: drop the server backend valuebrice GPG Verified
f21f809test(app): start session-lock, xwayland and colorcheck capture over controlbrice GPG Verified
5aeb335docs(dev): drive headless sessions through the control CLIbrice GPG Verified
c47fcf0refactor(app)!: capture headless frames over control, drop --screenshotbrice GPG Verified
8a34b6afix(control): omit unchanged diff fieldsbrice GPG Verified
786177cfix(core): match window-mapped against windows new since the requestbrice GPG Verified
2cd3dfafeat(headless): start and stop continuous captures over controlbrice GPG Verified
4164136feat(app): serve runtime virtual outputs on headlessbrice GPG Verified
76b769efeat(app): serve control shots on headlessbrice GPG Verified
40ab97efeat(cli): output add and rmbrice GPG Verified
969b727feat(core): reconcile runtime output control transactionsbrice GPG Verified
1959225feat(app): run each headless instance as a sessionbrice GPG Verified
861ced7feat(core): transact runtime virtual output desired setsbrice GPG Verified
e07c9f4feat(cli)!: select headless profiles with --profilebrice GPG Verified
6e411f9feat(control): shot op and shots on do and injectbrice GPG Verified
99c23b4refactor(app)!: replace scripted headless input with the control socketbrice GPG Verified
5e22253feat(cli): session rmbrice GPG Verified
656ab93docs(index): point the game server entry at the persistent headless profilebrice GPG Verified
87a041cdocs(dev): control inject and shot requestsbrice GPG Verified
4b59132docs(server): run the server as the persistent headless profilebrice GPG Verified
d95ce91feat(cli): session newbrice GPG Verified
2158834feat(cli): shot commandbrice GPG Verified
2c52c40feat(control): capture presented scenes to PNGbrice GPG Verified
edc254afeat(cli): session lsbrice GPG Verified
054eeb1feat(app): feed keymaps and session security to the control socketbrice GPG Verified
362aab9feat(core)!: plan the headless backend from a profile and overridesbrice GPG Verified
7e37555feat(cli): key, type and swipe commandsbrice GPG Verified
ac27236feat(core): resolve control shots to presented scene sequencesbrice GPG Verified
4f94795feat(control): inject op over the control socketbrice GPG Verified
eb7b9c0feat(cli): resolve the control target from -s, env or WAYLAND_DISPLAYbrice GPG Verified
5c36776feat(routing): route control captures to a dedicated sinkbrice GPG Verified
2a4490ffeat(sessiondir): session directory registrybrice GPG Verified
4dff57dfeat(headless): hold control captures until the target scene is presentedbrice GPG Verified
81554effeat(control): translate key, type, pointer and swipe into input eventsbrice GPG Verified
3b3912bfeat(core): inject control input through the real input pathbrice GPG Verified
244cea6fix(control): echo the reached wait level and omit empty errorsbrice GPG Verified
1570403feat(core): wait for settled or presented effects before replyingbrice GPG Verified
80777c8feat(app): serve the control socket on headlessbrice GPG Verified
9f8b012feat(wayland): report commits at the configured sizebrice GPG Verified
aa598d9feat(headless): report presented scene sequence to corebrice GPG Verified

the branch has more commits than the 100 listed.

Checks 1

171 files · +10757 -2496
1/1
M .hexcheck.yaml +1 -1
@@ -84,7 +84,7 @@ heuristics:
8484 ruleSettings:
8585 missing-generated-mock-for-port:
8686 # Sealed message unions are channel data, not ports; tested by sending messages (ADR 005).
87- excludePaths: [internal/ports/client_events.go, internal/ports/client_commands.go, internal/ports/input_events.go, internal/ports/output_events.go, internal/ports/lease.go, internal/ports/session_backend.go]
87+ excludePaths: [internal/ports/control.go, internal/ports/client_events.go, internal/ports/client_commands.go, internal/ports/input_events.go, internal/ports/output_events.go, internal/ports/lease.go, internal/ports/session_backend.go]
8888 no-adapter-to-adapter-imports:
8989 # Composition root wires concrete adapters; Makefile ADAPTER_LIBS governs adapter sharing.
9090 excludePaths: [internal/app/**]
@@ -84,7 +84,7 @@ heuristics:
84 ruleSettings:84 ruleSettings:
85 missing-generated-mock-for-port:85 missing-generated-mock-for-port:
86 # Sealed message unions are channel data, not ports; tested by sending messages (ADR 005).86 # Sealed message unions are channel data, not ports; tested by sending messages (ADR 005).
87- excludePaths: [internal/ports/client_events.go, internal/ports/client_commands.go, internal/ports/input_events.go, internal/ports/output_events.go, internal/ports/lease.go, internal/ports/session_backend.go]87+ excludePaths: [internal/ports/control.go, internal/ports/client_events.go, internal/ports/client_commands.go, internal/ports/input_events.go, internal/ports/output_events.go, internal/ports/lease.go, internal/ports/session_backend.go]
88 no-adapter-to-adapter-imports:88 no-adapter-to-adapter-imports:
89 # Composition root wires concrete adapters; Makefile ADAPTER_LIBS governs adapter sharing.89 # Composition root wires concrete adapters; Makefile ADAPTER_LIBS governs adapter sharing.
90 excludePaths: [internal/app/**]90 excludePaths: [internal/app/**]
M AGENTS.md +8 -7
@@ -40,13 +40,14 @@ Test doubles are always generated by Mockery v3 (`testify` template). Never hand
4040
4141 ## End-to-end tests (headless backend)
4242
43-Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on the headless backend before declaring it done; see [docs/dev/headless.md](docs/dev/headless.md).
44-
45-- Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and run it with a throwaway config: `<tmp>/neferwl --backend=headless --config <tmp>/config --no-xwayland --screenshot <tmp>/shots --input <script> --timeout 10s`.
46-- Input scripts drive keys and gestures (`key Super+s`, `swipe4 down`, `sleep 1s`); see the table in docs/dev/headless.md.
47-- Logs go to `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`, not stderr. Read the headless `WAYLAND_DISPLAY` from its `listening` entry.
48-- Isolate from the user's live session: run the headless compositor, its clients and `neferwl state` with `env -u NEFERWL_STATE -u NEFERWL_SLOT WAYLAND_DISPLAY=<headless>`. `NEFERWL_STATE` wins over `WAYLAND_DISPLAY` and would read the live session's state.
49-- Check results with `WAYLAND_DISPLAY=<headless> neferwl state` (windows, stash index/count, visibility) and the `latest.png` screenshot.
43+Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on an isolated headless session before declaring it done; see [docs/dev/headless.md](docs/dev/headless.md) and [docs/control.md](docs/control.md).
44+
45+- Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and use it for every command.
46+- Start a session with a throwaway config: `<tmp>/neferwl session new --id test --config <tmp>/config --ttl 60s -- --no-xwayland`. It prints readiness JSON with the session's Wayland display; use that display for external clients.
47+- Pass `-s test` to every control command so the live desktop stays untouched: `<tmp>/neferwl -s test key Super+s`, `swipe 4 down`, `type <text>`. Wait with `--until` and `--wait` instead of sleeping.
48+- Check state with `<tmp>/neferwl -s test state` and captures with `<tmp>/neferwl -s test shot`; for a frame sequence, `shot --every-frame`, then `shot --stop`.
49+- Logs are in `$XDG_STATE_HOME/neferwl/sessions/test/latest.log`, not stderr.
50+- Stop the session with `<tmp>/neferwl session rm test`.
5051
5152 ## Checks before merge
5253
@@ -40,13 +40,14 @@ Test doubles are always generated by Mockery v3 (`testify` template). Never hand
40 40
41 ## End-to-end tests (headless backend)41 ## End-to-end tests (headless backend)
42 42
43-Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on the headless backend before declaring it done; see [docs/dev/headless.md](docs/dev/headless.md).43+Unit tests are not enough for user-facing behavior (binds, gestures, window placement, config keys). Test it end to end on an isolated headless session before declaring it done; see [docs/dev/headless.md](docs/dev/headless.md) and [docs/control.md](docs/control.md).
44-44+
45-- Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and run it with a throwaway config: `<tmp>/neferwl --backend=headless --config <tmp>/config --no-xwayland --screenshot <tmp>/shots --input <script> --timeout 10s`.45+- Build the branch binary (`CGO_ENABLED=0 go build -o <tmp>/neferwl ./cmd/neferwl`) and use it for every command.
46-- Input scripts drive keys and gestures (`key Super+s`, `swipe4 down`, `sleep 1s`); see the table in docs/dev/headless.md.46+- Start a session with a throwaway config: `<tmp>/neferwl session new --id test --config <tmp>/config --ttl 60s -- --no-xwayland`. It prints readiness JSON with the session's Wayland display; use that display for external clients.
47-- Logs go to `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`, not stderr. Read the headless `WAYLAND_DISPLAY` from its `listening` entry.47+- Pass `-s test` to every control command so the live desktop stays untouched: `<tmp>/neferwl -s test key Super+s`, `swipe 4 down`, `type <text>`. Wait with `--until` and `--wait` instead of sleeping.
48-- Isolate from the user's live session: run the headless compositor, its clients and `neferwl state` with `env -u NEFERWL_STATE -u NEFERWL_SLOT WAYLAND_DISPLAY=<headless>`. `NEFERWL_STATE` wins over `WAYLAND_DISPLAY` and would read the live session's state.48+- Check state with `<tmp>/neferwl -s test state` and captures with `<tmp>/neferwl -s test shot`; for a frame sequence, `shot --every-frame`, then `shot --stop`.
49-- Check results with `WAYLAND_DISPLAY=<headless> neferwl state` (windows, stash index/count, visibility) and the `latest.png` screenshot.49+- Logs are in `$XDG_STATE_HOME/neferwl/sessions/test/latest.log`, not stderr.
50+- Stop the session with `<tmp>/neferwl session rm test`.
50 51
51 ## Checks before merge52 ## Checks before merge
52 53
M README.md +46 -1
@@ -25,6 +25,8 @@ https://github.com/user-attachments/assets/1ff42ce5-47b3-4cf8-a3a7-5fc5abde4af1
2525 - **Stash:** `cmd+s` toggles a floating strip of windows set aside for the current workspace; `cmd+shift+s` moves a window into or out of it. See [Stash](docs/config.md#stash).
2626 - **Hint mode:** click what is on screen by typing its label. Works best in apps like Firefox; see [Hint mode](docs/config.md#hint-mode).
2727 - **Animations:** short and cheap; turn them off with `animations = off`.
28+- **Headless server:** run without a screen on virtual outputs, then stream with Sunshine, watch over VNC or record; see [Headless and server mode](docs/server.md).
29+- **Agents and scripts:** throwaway sessions that a script or AI agent drives with actions, input, state and screenshots, each command waiting for its result; see [Scripting and agents](docs/control.md).
2830
2931 Written in Go, without cgo. Each piece of state has one owner goroutine, connected to the others by channels; hot paths reuse memory and client buffers stay off the Go heap. See [Architecture](docs/dev/architecture.md) for the concurrency model, the GC strategy and the reusable Go libraries.
3032
@@ -174,6 +176,47 @@ Bring your own layer-shell UI, such as Noctalia or Waybar. For capture and idle
174176
175177 Configuration is a flat `key = value` file that reloads on save. A JSON state file exposes outputs, workspaces and windows to scripts; see [Desktop integration](docs/desktop.md).
176178
179+### Headless server
180+
181+`neferwl --backend=headless --profile=persistent` runs NeferWL on a machine without a screen, on the virtual outputs declared in the config. `neferwl-server.service` runs it as a systemd user service. Apps connect to its Wayland display as usual; Sunshine, OBS and other PipeWire clients stream its outputs through the portal. See [Headless and server mode](docs/server.md) for the setup and a game streaming host with Sunshine.
182+
183+### Agents and automation
184+
185+Each headless session has a control socket for scripts and AI agents. Every command waits for its effect and replies with what changed, so no sleeps are needed. A session looks like this:
186+
187+1. Start a throwaway session; it prints its Wayland display and control socket:
188+
189+ ```sh
190+ neferwl session new --id demo --ttl 10m -- --no-terminal
191+ ```
192+
193+2. Launch an app and wait for its window:
194+
195+ ```sh
196+ neferwl -s demo do spawn foot --until 'window-mapped app_id=foot'
197+ ```
198+
199+3. Act, then wait until the result is on screen and capture it:
200+
201+ ```sh
202+ neferwl -s demo type 'echo hello'
203+ neferwl -s demo key Return --shot # prints the PNG path
204+ ```
205+
206+4. Read the state:
207+
208+ ```sh
209+ neferwl -s demo state | jq '.windows[] | {id, app_id, visible}'
210+ ```
211+
212+5. Stop the session:
213+
214+ ```sh
215+ neferwl session rm demo
216+ ```
217+
218+Give an agent the [`skills/neferwl`](skills/neferwl/SKILL.md) skill so it knows the commands. [Scripting and agents](docs/control.md) covers waits, captures, video and security; the wire protocol is in [docs/dev/control.md](docs/dev/control.md).
219+
177220 ## Hardware support
178221
179222 NeferWL requires Linux, atomic KMS and a Vulkan 1.3 device that can export images as dmabufs. It reports an error at startup if these requirements are not met.
@@ -192,7 +235,9 @@ Reports from NVIDIA and Intel users are welcome.
192235 - [Desktop integration](docs/desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.
193236 - [Screen capture](docs/capture.md): protocols, indicator, executable allowlist and portals.
194237 - [Performance](docs/performance.md): VRR and real-time priority.
195-- [Developer documentation](docs/dev/index.md): architecture, headless testing, profiling and frame stats.
238+- [Headless and server mode](docs/server.md): profiles, the server service, streaming with Sunshine and remote viewing.
239+- [Scripting and agents](docs/control.md): sessions, targeting, waits, state, captures and runtime outputs.
240+- [Developer documentation](docs/dev/index.md): architecture, headless testing, control protocol, profiling and frame stats.
196241
197242 ## Contributing
198243
@@ -25,6 +25,8 @@ https://github.com/user-attachments/assets/1ff42ce5-47b3-4cf8-a3a7-5fc5abde4af1
25 - **Stash:** `cmd+s` toggles a floating strip of windows set aside for the current workspace; `cmd+shift+s` moves a window into or out of it. See [Stash](docs/config.md#stash).25 - **Stash:** `cmd+s` toggles a floating strip of windows set aside for the current workspace; `cmd+shift+s` moves a window into or out of it. See [Stash](docs/config.md#stash).
26 - **Hint mode:** click what is on screen by typing its label. Works best in apps like Firefox; see [Hint mode](docs/config.md#hint-mode).26 - **Hint mode:** click what is on screen by typing its label. Works best in apps like Firefox; see [Hint mode](docs/config.md#hint-mode).
27 - **Animations:** short and cheap; turn them off with `animations = off`.27 - **Animations:** short and cheap; turn them off with `animations = off`.
28+- **Headless server:** run without a screen on virtual outputs, then stream with Sunshine, watch over VNC or record; see [Headless and server mode](docs/server.md).
29+- **Agents and scripts:** throwaway sessions that a script or AI agent drives with actions, input, state and screenshots, each command waiting for its result; see [Scripting and agents](docs/control.md).
28 30
29 Written in Go, without cgo. Each piece of state has one owner goroutine, connected to the others by channels; hot paths reuse memory and client buffers stay off the Go heap. See [Architecture](docs/dev/architecture.md) for the concurrency model, the GC strategy and the reusable Go libraries.31 Written in Go, without cgo. Each piece of state has one owner goroutine, connected to the others by channels; hot paths reuse memory and client buffers stay off the Go heap. See [Architecture](docs/dev/architecture.md) for the concurrency model, the GC strategy and the reusable Go libraries.
30 32
@@ -174,6 +176,47 @@ Bring your own layer-shell UI, such as Noctalia or Waybar. For capture and idle
174 176
175 Configuration is a flat `key = value` file that reloads on save. A JSON state file exposes outputs, workspaces and windows to scripts; see [Desktop integration](docs/desktop.md).177 Configuration is a flat `key = value` file that reloads on save. A JSON state file exposes outputs, workspaces and windows to scripts; see [Desktop integration](docs/desktop.md).
176 178
179+### Headless server
180+
181+`neferwl --backend=headless --profile=persistent` runs NeferWL on a machine without a screen, on the virtual outputs declared in the config. `neferwl-server.service` runs it as a systemd user service. Apps connect to its Wayland display as usual; Sunshine, OBS and other PipeWire clients stream its outputs through the portal. See [Headless and server mode](docs/server.md) for the setup and a game streaming host with Sunshine.
182+
183+### Agents and automation
184+
185+Each headless session has a control socket for scripts and AI agents. Every command waits for its effect and replies with what changed, so no sleeps are needed. A session looks like this:
186+
187+1. Start a throwaway session; it prints its Wayland display and control socket:
188+
189+ ```sh
190+ neferwl session new --id demo --ttl 10m -- --no-terminal
191+ ```
192+
193+2. Launch an app and wait for its window:
194+
195+ ```sh
196+ neferwl -s demo do spawn foot --until 'window-mapped app_id=foot'
197+ ```
198+
199+3. Act, then wait until the result is on screen and capture it:
200+
201+ ```sh
202+ neferwl -s demo type 'echo hello'
203+ neferwl -s demo key Return --shot # prints the PNG path
204+ ```
205+
206+4. Read the state:
207+
208+ ```sh
209+ neferwl -s demo state | jq '.windows[] | {id, app_id, visible}'
210+ ```
211+
212+5. Stop the session:
213+
214+ ```sh
215+ neferwl session rm demo
216+ ```
217+
218+Give an agent the [`skills/neferwl`](skills/neferwl/SKILL.md) skill so it knows the commands. [Scripting and agents](docs/control.md) covers waits, captures, video and security; the wire protocol is in [docs/dev/control.md](docs/dev/control.md).
219+
177 ## Hardware support220 ## Hardware support
178 221
179 NeferWL requires Linux, atomic KMS and a Vulkan 1.3 device that can export images as dmabufs. It reports an error at startup if these requirements are not met.222 NeferWL requires Linux, atomic KMS and a Vulkan 1.3 device that can export images as dmabufs. It reports an error at startup if these requirements are not met.
@@ -192,7 +235,9 @@ Reports from NVIDIA and Intel users are welcome.
192 - [Desktop integration](docs/desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.235 - [Desktop integration](docs/desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.
193 - [Screen capture](docs/capture.md): protocols, indicator, executable allowlist and portals.236 - [Screen capture](docs/capture.md): protocols, indicator, executable allowlist and portals.
194 - [Performance](docs/performance.md): VRR and real-time priority.237 - [Performance](docs/performance.md): VRR and real-time priority.
195-- [Developer documentation](docs/dev/index.md): architecture, headless testing, profiling and frame stats.238+- [Headless and server mode](docs/server.md): profiles, the server service, streaming with Sunshine and remote viewing.
239+- [Scripting and agents](docs/control.md): sessions, targeting, waits, state, captures and runtime outputs.
240+- [Developer documentation](docs/dev/index.md): architecture, headless testing, control protocol, profiling and frame stats.
196 241
197 ## Contributing242 ## Contributing
198 243
M docs/capture.md +2 -2
@@ -88,7 +88,7 @@ NeferWL serves the GNOME ScreenCast, DisplayConfig, Introspect and Screenshot D-
8888
8989 The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the gnome portal.
9090
91-The D-Bus interfaces are served on the session bus when NeferWL runs on a hardware session. With `--backend=headless`, pass `-dbus` to serve them. Names already owned (by a GNOME session) are skipped.
91+The D-Bus interfaces are served on the session bus when NeferWL runs on a hardware session. The persistent [headless profile](server.md#profiles) serves them too; the ephemeral profile only with `--dbus`. Names already owned (by a GNOME session) are skipped.
9292
9393 Screenshots through the portal are taken without asking, for any program running as you whose executable is on the allowlist. The indicator still flashes.
9494
@@ -102,4 +102,4 @@ capture = portal
102102
103103 Pick the output in the portal dialog, for example a virtual `tv` with `output.tv.hdr = on`.
104104
105-To stream from a machine with no display, run NeferWL in server mode: see [Game server](server.md).
105+To stream from a machine with no display, see [Game streaming with Sunshine](server.md#game-streaming-with-sunshine).
@@ -88,7 +88,7 @@ NeferWL serves the GNOME ScreenCast, DisplayConfig, Introspect and Screenshot D-
88 88
89 The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the gnome portal.89 The packaged `neferwl-portals.conf` routes `ScreenCast` and `Screenshot` to the gnome portal.
90 90
91-The D-Bus interfaces are served on the session bus when NeferWL runs on a hardware session. With `--backend=headless`, pass `-dbus` to serve them. Names already owned (by a GNOME session) are skipped.91+The D-Bus interfaces are served on the session bus when NeferWL runs on a hardware session. The persistent [headless profile](server.md#profiles) serves them too; the ephemeral profile only with `--dbus`. Names already owned (by a GNOME session) are skipped.
92 92
93 Screenshots through the portal are taken without asking, for any program running as you whose executable is on the allowlist. The indicator still flashes.93 Screenshots through the portal are taken without asking, for any program running as you whose executable is on the allowlist. The indicator still flashes.
94 94
@@ -102,4 +102,4 @@ capture = portal
102 102
103 Pick the output in the portal dialog, for example a virtual `tv` with `output.tv.hdr = on`.103 Pick the output in the portal dialog, for example a virtual `tv` with `output.tv.hdr = on`.
104 104
105-To stream from a machine with no display, run NeferWL in server mode: see [Game server](server.md).105+To stream from a machine with no display, see [Game streaming with Sunshine](server.md#game-streaming-with-sunshine).
A docs/control.md +188 -0
@@ -0,0 +1,188 @@
1+# Scripting and agents
2+
3+Every headless NeferWL session has a control socket. Scripts, tests and AI
4+agents use it to run actions, inject input, read state and take screenshots,
5+and each command waits for its result, so no fixed sleeps are needed. Use it on
6+a throwaway session to test a config or an app away from your desktop, or on
7+the long-running [server](server.md). The `neferwl` CLI wraps the socket; the
8+wire protocol is in [docs/dev/control.md](dev/control.md).
9+
10+## Sessions
11+
12+A session is one headless compositor with its own Wayland display, control
13+socket, state and captures.
14+
15+```sh
16+neferwl session new --id demo --ttl 10m # start a session, print its readiness JSON
17+neferwl session ls # list live sessions
18+neferwl session rm demo # stop it
19+```
20+
21+`session new` starts the compositor detached and prints one JSON line once it
22+is ready:
23+
24+```json
25+{"id":"demo","wayland":"wayland-3","control":"/run/user/1000/neferwl/sessions/demo/control.sock","display":":2"}
26+```
27+
28+`display` is the X11 display, empty with `--no-xwayland`. `--env` prints
29+`NEFERWL_SESSION=` and `WAYLAND_DISPLAY=` lines instead.
30+
31+| Flag | Default | Meaning |
32+|---|---|---|
33+| `--id ID` | random | Session ID |
34+| `--profile` | `ephemeral` | `ephemeral` or `persistent`; see [Headless and server mode](server.md#profiles) |
35+| `--size WxH[,WxH...]` | `1920x1080` (ephemeral) | Output sizes, laid out left to right (`HEADLESS-1`, `HEADLESS-2`, ...) |
36+| `--config PATH` | XDG default | Config file; use a throwaway one for tests |
37+| `--ttl DURATION` | none | The session exits after this time |
38+| `--start-timeout DURATION` | `30s` | Give up if the session is not ready in time |
39+| `--dbus-session` | off | Keep the parent D-Bus session bus (removed by default) |
40+| `--env` | off | Print shell assignments instead of JSON |
41+
42+Compositor flags go after `--`, for example
43+`neferwl session new --id demo -- --no-xwayland --no-terminal`. The ephemeral
44+profile opens the configured terminal at startup unless `--no-terminal` is
45+given.
46+
47+The session does not inherit the caller's `WAYLAND_DISPLAY`, `DISPLAY` or
48+session targets, so apps it starts never open on your desktop. Logs go to
49+`$XDG_STATE_HOME/neferwl/sessions/<id>/latest.log`.
50+
51+`neferwl-server.service` runs the persistent [server](server.md) as the session
52+`server`.
53+
54+## Targeting
55+
56+Control commands pick their session in this order:
57+
58+1. `-s ID`;
59+2. `NEFERWL_SESSION`;
60+3. `NEFERWL_CONTROL` (a control socket path);
61+4. the session whose Wayland display is `WAYLAND_DISPLAY`.
62+
63+Programs started inside a session get `NEFERWL_SESSION`, `NEFERWL_CONTROL` and
64+`WAYLAND_DISPLAY`, so `neferwl key` run from a session's terminal controls that
65+session. In scripts, always pass `-s ID`. Without a target, the command fails
66+and lists live sessions.
67+
68+Start your own clients with the session's `wayland` display
69+(`WAYLAND_DISPLAY=wayland-3 foot &`), or let the compositor start them with
70+`neferwl -s demo do spawn foot`.
71+
72+## Act, then observe
73+
74+Each action or input command waits for its effect, then replies with what
75+changed:
76+
77+```sh
78+neferwl -s demo do spawn foot --until 'window-mapped app_id=foot'
79+```
80+
81+```json
82+{"ok":true,"done":"settled","diff":{"mapped":[2],"focus_from":1,"focus_to":2,"focus_changed":true},...}
83+```
84+
85+| Command | Effect |
86+|---|---|
87+| `do ACTION [ARG...]` | Run a bind action: `do focus-workspace-next`, `do spawn foot`, `do workspace dev` |
88+| `key COMBO` | Press and release a combination: `key Super+Return` |
89+| `type TEXT` | Type text with the session's keymap |
90+| `press COMBO`, `release COMBO` | Hold or release keys |
91+| `move X Y` | Move the pointer to global logical coordinates |
92+| `click [left\|right\|middle]` | Click a button (left by default) |
93+| `swipe 3\|4 up\|down\|left\|right` | Touchpad swipe |
94+
95+Action names are the bind actions of the [configuration](config.md). Compositor
96+binds such as `Super+o` also work through `key`. These flags go before or after
97+the arguments:
98+
99+| Flag | Default | Meaning |
100+|---|---|---|
101+| `--wait LEVEL` | `settled` | `committed`: the action is applied. `settled`: animations are done and windows have committed their new sizes. `presented`: the result is on screen. |
102+| `--until PREDICATE` | none | Also wait for `window-mapped app_id=APP`, `focused app_id=APP` or `unmapped id=N` |
103+| `--timeout DURATION` | `10s` | Wait at most this long, up to `5m` |
104+| `--shot` | off | Capture every output once the result is presented |
105+
106+`diff` lists mapped and unmapped window IDs, the focus change and the workspace
107+now shown on each changed output (`HEADLESS-1:2`). On timeout the command
108+prints `timeout` and exits with status 1. The reply still carries the partial
109+diff; the action may have run, so check the state before retrying.
110+
111+`--` ends flag parsing for arguments that start with a dash:
112+`neferwl -s demo move -- -640 0`, `neferwl -s demo type -- -x`.
113+
114+There is no sleep or hold command: use the shell between `press` and `release`.
115+
116+## Observe state
117+
118+```sh
119+neferwl -s demo state # outputs, workspaces, windows, focus
120+neferwl -s demo state | jq '.windows[] | {id, app_id, workspace, visible}'
121+neferwl -s demo query state # the same state inside a reply envelope
122+```
123+
124+The state has the shape of the desktop [state file](desktop.md#state-for-scripts)
125+and never contains window titles.
126+
127+## Captures
128+
129+```sh
130+neferwl -s demo shot # every output
131+neferwl -s demo shot --output HEADLESS-1 # repeat --output for several
132+neferwl -s demo shot --inline # also return base64 PNG data
133+```
134+
135+A shot waits for the next presented frame and writes one 8-bit sRGB PNG per
136+output under `$XDG_RUNTIME_DIR/neferwl/sessions/<id>/shots/`. The reply lists
137+`{output, path, seq}` for each, where `seq` is the presented scene. `--shot` on
138+an action captures its result in the same round trip. Single shots do not show
139+the cursor.
140+
141+### Every frame and video
142+
143+```sh
144+neferwl -s demo shot --every-frame # start writing frames
145+neferwl -s demo swipe 4 down --wait presented
146+neferwl -s demo shot --stop # stop and close the index
147+frames="$XDG_RUNTIME_DIR/neferwl/sessions/demo/shots/frames"
148+ffmpeg -f concat -safe 0 -i "$frames/frames.ffconcat" -vf "fps=60,format=yuv420p" -c:v libx264 -crf 18 demo.mp4
149+```
150+
151+Continuous capture writes `frame-NNNNNN.png` per presented frame, `latest.png`
152+(a hard link to the newest frame) and `frames.ffconcat` with the frame timing.
153+`--dir DIR` selects another directory and `--output NAME` limits capture to
154+that output. With several outputs, each gets a subdirectory named after it.
155+The directory grows until `shot --stop`.
156+
157+On an HDR output, `--every-frame --raw` also writes `latest-pq.png`, the newest
158+frame in raw PQ.
159+
160+## Runtime outputs
161+
162+```sh
163+neferwl -s demo output add 1280x720@60 --name side
164+neferwl -s demo output rm side
165+```
166+
167+An added output lasts until `output rm` or the end of the session. The reply
168+comes once the state lists or drops it.
169+
170+## Security
171+
172+- The socket and its directory are private to the user (`0600`, `0700`), and
173+ the compositor checks the peer's uid with `SO_PEERCRED`. Any process of the
174+ same user gets full control, including input and captures; other users are
175+ rejected.
176+- While the session is locked (`ext-session-lock-v1`), actions, input and
177+ captures are refused with `locked`, and continuous capture writes no frames.
178+ `quit` is still accepted so `session rm` can stop a locked session. Same-uid
179+ access does not bypass the lock.
180+
181+## Limits
182+
183+- Only headless sessions have a control socket. On a DRM desktop, use the
184+ [state file](desktop.md#state-for-scripts) and Wayland tools.
185+- Single shots are 8-bit sRGB; raw PQ is only available with `--every-frame`.
186+- On a device without sync-file export (software Vulkan such as lavapipe, in
187+ CI or VMs), shots are read back on the CPU: slower, same pixels.
188+- At most 64 requests wait at once per session; more get `busy`.
@@ -0,0 +1,188 @@
1+# Scripting and agents
2+
3+Every headless NeferWL session has a control socket. Scripts, tests and AI
4+agents use it to run actions, inject input, read state and take screenshots,
5+and each command waits for its result, so no fixed sleeps are needed. Use it on
6+a throwaway session to test a config or an app away from your desktop, or on
7+the long-running [server](server.md). The `neferwl` CLI wraps the socket; the
8+wire protocol is in [docs/dev/control.md](dev/control.md).
9+
10+## Sessions
11+
12+A session is one headless compositor with its own Wayland display, control
13+socket, state and captures.
14+
15+```sh
16+neferwl session new --id demo --ttl 10m # start a session, print its readiness JSON
17+neferwl session ls # list live sessions
18+neferwl session rm demo # stop it
19+```
20+
21+`session new` starts the compositor detached and prints one JSON line once it
22+is ready:
23+
24+```json
25+{"id":"demo","wayland":"wayland-3","control":"/run/user/1000/neferwl/sessions/demo/control.sock","display":":2"}
26+```
27+
28+`display` is the X11 display, empty with `--no-xwayland`. `--env` prints
29+`NEFERWL_SESSION=` and `WAYLAND_DISPLAY=` lines instead.
30+
31+| Flag | Default | Meaning |
32+|---|---|---|
33+| `--id ID` | random | Session ID |
34+| `--profile` | `ephemeral` | `ephemeral` or `persistent`; see [Headless and server mode](server.md#profiles) |
35+| `--size WxH[,WxH...]` | `1920x1080` (ephemeral) | Output sizes, laid out left to right (`HEADLESS-1`, `HEADLESS-2`, ...) |
36+| `--config PATH` | XDG default | Config file; use a throwaway one for tests |
37+| `--ttl DURATION` | none | The session exits after this time |
38+| `--start-timeout DURATION` | `30s` | Give up if the session is not ready in time |
39+| `--dbus-session` | off | Keep the parent D-Bus session bus (removed by default) |
40+| `--env` | off | Print shell assignments instead of JSON |
41+
42+Compositor flags go after `--`, for example
43+`neferwl session new --id demo -- --no-xwayland --no-terminal`. The ephemeral
44+profile opens the configured terminal at startup unless `--no-terminal` is
45+given.
46+
47+The session does not inherit the caller's `WAYLAND_DISPLAY`, `DISPLAY` or
48+session targets, so apps it starts never open on your desktop. Logs go to
49+`$XDG_STATE_HOME/neferwl/sessions/<id>/latest.log`.
50+
51+`neferwl-server.service` runs the persistent [server](server.md) as the session
52+`server`.
53+
54+## Targeting
55+
56+Control commands pick their session in this order:
57+
58+1. `-s ID`;
59+2. `NEFERWL_SESSION`;
60+3. `NEFERWL_CONTROL` (a control socket path);
61+4. the session whose Wayland display is `WAYLAND_DISPLAY`.
62+
63+Programs started inside a session get `NEFERWL_SESSION`, `NEFERWL_CONTROL` and
64+`WAYLAND_DISPLAY`, so `neferwl key` run from a session's terminal controls that
65+session. In scripts, always pass `-s ID`. Without a target, the command fails
66+and lists live sessions.
67+
68+Start your own clients with the session's `wayland` display
69+(`WAYLAND_DISPLAY=wayland-3 foot &`), or let the compositor start them with
70+`neferwl -s demo do spawn foot`.
71+
72+## Act, then observe
73+
74+Each action or input command waits for its effect, then replies with what
75+changed:
76+
77+```sh
78+neferwl -s demo do spawn foot --until 'window-mapped app_id=foot'
79+```
80+
81+```json
82+{"ok":true,"done":"settled","diff":{"mapped":[2],"focus_from":1,"focus_to":2,"focus_changed":true},...}
83+```
84+
85+| Command | Effect |
86+|---|---|
87+| `do ACTION [ARG...]` | Run a bind action: `do focus-workspace-next`, `do spawn foot`, `do workspace dev` |
88+| `key COMBO` | Press and release a combination: `key Super+Return` |
89+| `type TEXT` | Type text with the session's keymap |
90+| `press COMBO`, `release COMBO` | Hold or release keys |
91+| `move X Y` | Move the pointer to global logical coordinates |
92+| `click [left\|right\|middle]` | Click a button (left by default) |
93+| `swipe 3\|4 up\|down\|left\|right` | Touchpad swipe |
94+
95+Action names are the bind actions of the [configuration](config.md). Compositor
96+binds such as `Super+o` also work through `key`. These flags go before or after
97+the arguments:
98+
99+| Flag | Default | Meaning |
100+|---|---|---|
101+| `--wait LEVEL` | `settled` | `committed`: the action is applied. `settled`: animations are done and windows have committed their new sizes. `presented`: the result is on screen. |
102+| `--until PREDICATE` | none | Also wait for `window-mapped app_id=APP`, `focused app_id=APP` or `unmapped id=N` |
103+| `--timeout DURATION` | `10s` | Wait at most this long, up to `5m` |
104+| `--shot` | off | Capture every output once the result is presented |
105+
106+`diff` lists mapped and unmapped window IDs, the focus change and the workspace
107+now shown on each changed output (`HEADLESS-1:2`). On timeout the command
108+prints `timeout` and exits with status 1. The reply still carries the partial
109+diff; the action may have run, so check the state before retrying.
110+
111+`--` ends flag parsing for arguments that start with a dash:
112+`neferwl -s demo move -- -640 0`, `neferwl -s demo type -- -x`.
113+
114+There is no sleep or hold command: use the shell between `press` and `release`.
115+
116+## Observe state
117+
118+```sh
119+neferwl -s demo state # outputs, workspaces, windows, focus
120+neferwl -s demo state | jq '.windows[] | {id, app_id, workspace, visible}'
121+neferwl -s demo query state # the same state inside a reply envelope
122+```
123+
124+The state has the shape of the desktop [state file](desktop.md#state-for-scripts)
125+and never contains window titles.
126+
127+## Captures
128+
129+```sh
130+neferwl -s demo shot # every output
131+neferwl -s demo shot --output HEADLESS-1 # repeat --output for several
132+neferwl -s demo shot --inline # also return base64 PNG data
133+```
134+
135+A shot waits for the next presented frame and writes one 8-bit sRGB PNG per
136+output under `$XDG_RUNTIME_DIR/neferwl/sessions/<id>/shots/`. The reply lists
137+`{output, path, seq}` for each, where `seq` is the presented scene. `--shot` on
138+an action captures its result in the same round trip. Single shots do not show
139+the cursor.
140+
141+### Every frame and video
142+
143+```sh
144+neferwl -s demo shot --every-frame # start writing frames
145+neferwl -s demo swipe 4 down --wait presented
146+neferwl -s demo shot --stop # stop and close the index
147+frames="$XDG_RUNTIME_DIR/neferwl/sessions/demo/shots/frames"
148+ffmpeg -f concat -safe 0 -i "$frames/frames.ffconcat" -vf "fps=60,format=yuv420p" -c:v libx264 -crf 18 demo.mp4
149+```
150+
151+Continuous capture writes `frame-NNNNNN.png` per presented frame, `latest.png`
152+(a hard link to the newest frame) and `frames.ffconcat` with the frame timing.
153+`--dir DIR` selects another directory and `--output NAME` limits capture to
154+that output. With several outputs, each gets a subdirectory named after it.
155+The directory grows until `shot --stop`.
156+
157+On an HDR output, `--every-frame --raw` also writes `latest-pq.png`, the newest
158+frame in raw PQ.
159+
160+## Runtime outputs
161+
162+```sh
163+neferwl -s demo output add 1280x720@60 --name side
164+neferwl -s demo output rm side
165+```
166+
167+An added output lasts until `output rm` or the end of the session. The reply
168+comes once the state lists or drops it.
169+
170+## Security
171+
172+- The socket and its directory are private to the user (`0600`, `0700`), and
173+ the compositor checks the peer's uid with `SO_PEERCRED`. Any process of the
174+ same user gets full control, including input and captures; other users are
175+ rejected.
176+- While the session is locked (`ext-session-lock-v1`), actions, input and
177+ captures are refused with `locked`, and continuous capture writes no frames.
178+ `quit` is still accepted so `session rm` can stop a locked session. Same-uid
179+ access does not bypass the lock.
180+
181+## Limits
182+
183+- Only headless sessions have a control socket. On a DRM desktop, use the
184+ [state file](desktop.md#state-for-scripts) and Wayland tools.
185+- Single shots are 8-bit sRGB; raw PQ is only available with `--every-frame`.
186+- On a device without sync-file export (software Vulkan such as lavapipe, in
187+ CI or VMs), shots are read back on the CPU: slower, same pixels.
188+- At most 64 requests wait at once per session; more get `busy`.
M docs/desktop.md +5 -1
@@ -150,7 +150,7 @@ Workspace IDs are `name:<name>` for named workspaces, stable across launches. Nu
150150
151151 ## State for scripts
152152
153-NeferWL writes its state as JSON to `$XDG_RUNTIME_DIR/neferwl/<wayland socket>.json`, also given to started programs as `$NEFERWL_STATE`. It lists outputs, workspaces, the focused window, and every window with its app ID, PID, workspace, column and row, and whether it is floating or the fullscreen window of its workspace (`floating`, `fullscreen`). A fullscreen window keeps `fullscreen` while a stashed window is shown over it and while its workspace is not shown; combine it with `visible` to know what covers an output.
153+NeferWL writes its state as JSON to `$XDG_RUNTIME_DIR/neferwl/<wayland socket>.json` (`$XDG_RUNTIME_DIR/neferwl/sessions/<id>/state.json` for a [headless session](server.md)), also given to started programs as `$NEFERWL_STATE`. It lists outputs, workspaces, the focused window, and every window with its app ID, PID, workspace, column and row, and whether it is floating or the fullscreen window of its workspace (`floating`, `fullscreen`). A fullscreen window keeps `fullscreen` while a stashed window is shown over it and while its workspace is not shown; combine it with `visible` to know what covers an output.
154154
155155 Each window also carries metadata keys:
156156
@@ -163,6 +163,10 @@ Each window also carries metadata keys:
163163
164164 The `workspaces` list holds every workspace with its `visible` flag, its columns and the windows in them, each with `x`, `y`, `width` and `height` in logical pixels of its output. A workspace's `cover` is its active fullscreen window, 0 if none; a window's `fullscreen` is also set for the other fullscreen windows it holds, which sit output-sized in their own column or band. The file is written at most once per second.
165165
166+`neferwl state` prints it. On a headless session it reads the live state over
167+the [control socket](control.md) (`neferwl -s ID state`); otherwise it reads the
168+file.
169+
166170 ```sh
167171 neferwl state # the whole state
168172 neferwl state output-of "$PID" # the output showing that process's window
@@ -150,7 +150,7 @@ Workspace IDs are `name:<name>` for named workspaces, stable across launches. Nu
150 150
151 ## State for scripts151 ## State for scripts
152 152
153-NeferWL writes its state as JSON to `$XDG_RUNTIME_DIR/neferwl/<wayland socket>.json`, also given to started programs as `$NEFERWL_STATE`. It lists outputs, workspaces, the focused window, and every window with its app ID, PID, workspace, column and row, and whether it is floating or the fullscreen window of its workspace (`floating`, `fullscreen`). A fullscreen window keeps `fullscreen` while a stashed window is shown over it and while its workspace is not shown; combine it with `visible` to know what covers an output.153+NeferWL writes its state as JSON to `$XDG_RUNTIME_DIR/neferwl/<wayland socket>.json` (`$XDG_RUNTIME_DIR/neferwl/sessions/<id>/state.json` for a [headless session](server.md)), also given to started programs as `$NEFERWL_STATE`. It lists outputs, workspaces, the focused window, and every window with its app ID, PID, workspace, column and row, and whether it is floating or the fullscreen window of its workspace (`floating`, `fullscreen`). A fullscreen window keeps `fullscreen` while a stashed window is shown over it and while its workspace is not shown; combine it with `visible` to know what covers an output.
154 154
155 Each window also carries metadata keys:155 Each window also carries metadata keys:
156 156
@@ -163,6 +163,10 @@ Each window also carries metadata keys:
163 163
164 The `workspaces` list holds every workspace with its `visible` flag, its columns and the windows in them, each with `x`, `y`, `width` and `height` in logical pixels of its output. A workspace's `cover` is its active fullscreen window, 0 if none; a window's `fullscreen` is also set for the other fullscreen windows it holds, which sit output-sized in their own column or band. The file is written at most once per second.164 The `workspaces` list holds every workspace with its `visible` flag, its columns and the windows in them, each with `x`, `y`, `width` and `height` in logical pixels of its output. A workspace's `cover` is its active fullscreen window, 0 if none; a window's `fullscreen` is also set for the other fullscreen windows it holds, which sit output-sized in their own column or band. The file is written at most once per second.
165 165
166+`neferwl state` prints it. On a headless session it reads the live state over
167+the [control socket](control.md) (`neferwl -s ID state`); otherwise it reads the
168+file.
169+
166 ```sh170 ```sh
167 neferwl state # the whole state171 neferwl state # the whole state
168 neferwl state output-of "$PID" # the output showing that process's window172 neferwl state output-of "$PID" # the output showing that process's window
A docs/dev/control.md +187 -0
@@ -0,0 +1,187 @@
1+# Control protocol
2+
3+Wire reference for the headless control socket. For sessions, targeting and CLI
4+usage, see [Scripting and agents](../control.md).
5+
6+## Connection
7+
8+Each session listens on `$XDG_RUNTIME_DIR/neferwl/sessions/<id>/control.sock`
9+(directory `0700`, socket `0600`). The server reads the peer's credentials with
10+`SO_PEERCRED` and closes connections from another uid. An accepted connection
11+has every capability: `read`, `act`, `input`, `capture`, `admin`.
12+
13+Messages are JSON lines: one object per line, in both directions. A connection
14+handles one request at a time: the next line is read after the previous reply
15+is sent. Open several connections for concurrent requests.
16+
17+`id` is optional and may be any JSON value; the reply echoes it, or carries
18+`null` when it is missing or the line is not valid JSON.
19+
20+## Handshake
21+
22+```json
23+{"id":1,"op":"hello"}
24+{"id":1,"ok":true,"v":1,"caps":["read","act","input","capture","admin"],"commands":[{"name":"output-add","arg":"MODE","kind":"admin","caps":["admin"],"summary":"Add a runtime virtual output."},...]}
25+```
26+
27+`commands` is the catalog: each entry has `name`, `arg`, `kind` (`action`,
28+`action-arg`, `query`, `inject`, `shot`, `admin`), `caps` and `summary`. Action
29+names are the bind actions; `do` has no automation-only names. Additive changes
30+keep `v: 1`; clients ignore unknown fields.
31+
32+## Requests
33+
34+| `op` | Fields | Capability |
35+|---|---|---|
36+| `do` | `action` (name and arguments, e.g. `"focus-workspace 2"`), wait fields | `act` |
37+| `inject` | `kind` and its fields (below), wait fields | `input` |
38+| `query` | `what`: `"state"` | `read` |
39+| `shot` | `outputs`, `inline`, `raw`, `timeout` | `capture` |
40+| `shot` (continuous) | `every_frame` or `stop`, `outputs`, `dir`, `raw` | `capture` |
41+| `output-add` | `mode` (`WxH[@Hz]`), optional `name` | `admin` |
42+| `output-rm` | `name` | `admin` |
43+
44+Wait fields, on `do` and `inject`:
45+
46+| Field | Type | Default | Meaning |
47+|---|---|---|---|
48+| `wait` | `"committed"`, `"settled"`, `"presented"` | `"settled"` | Completion level |
49+| `until` | string | none | State predicate |
50+| `timeout` | Go duration string | `"10s"` | Bound on the wait, at most `5m` |
51+| `shot` | `true`, `false` or a list of output names | none | Capture after the wait; implies `presented` |
52+
53+### Inject kinds
54+
55+| `kind` | Fields | Meaning |
56+|---|---|---|
57+| `key` | `combo` | Press and release a combination such as `Super+Return` |
58+| `type` | `text` | Type text through the session keymap |
59+| `press`, `release` | `combo` | Press, or release in reverse order |
60+| `pointer` | `cmd`, `args` | `move` with absolute global logical `x`, `y` strings; `click` (default `left`), `down`, `up` with `left`, `right` or `middle` |
61+| `swipe` | `fingers` (3 or 4), `dir` | Touchpad swipe `up`, `down`, `left` or `right` |
62+
63+```json
64+{"id":1,"op":"inject","kind":"key","combo":"Super+Return","until":"window-mapped app_id=foot"}
65+{"id":2,"op":"inject","kind":"pointer","cmd":"move","args":["320","240"]}
66+{"id":3,"op":"inject","kind":"swipe","fingers":4,"dir":"down","wait":"presented"}
67+```
68+
69+Injected input goes through the core input path, so compositor binds run as
70+for a physical device. The first injection on a connection announces an input
71+device with ID `1` named `control` (for `output.<name>.input = control`).
72+
73+## Wait semantics
74+
75+- `committed`: the action or input batch has been applied to core state.
76+- `settled`: animations are finished and every affected window has committed
77+ its configured size.
78+- `presented`: the resulting scene has been presented on its outputs.
79+
80+`until` is checked on top of the level; the reply comes when both hold.
81+
82+| Predicate | Holds when |
83+|---|---|
84+| `window-mapped app_id=APP` | A window with that app ID mapped after the request |
85+| `focused app_id=APP` | A window with that app ID has focus |
86+| `unmapped id=N` | Window `N` is gone |
87+
88+`timeout` covers the wait and any capture together. A `timeout` above `5m` is
89+`bad-request` with `detail: "timeout exceeds 5m"`. On timeout the reply has
90+`error: "timeout"` and still carries `diff`, `state` and `late`: the action may
91+have run.
92+
93+At most 64 requests wait at once per session (any request with `wait` above
94+`committed`, `until`, `shot`, `output-add` or `output-rm`). A further one gets
95+`busy` before it runs. Committed-only requests and `quit` are never refused for
96+this.
97+
98+## Replies
99+
100+```json
101+{"id":2,"ok":true,"done":"settled","diff":{"mapped":[2],"focus_from":1,"focus_to":2,"focus_changed":true},"state":{...},"late":null}
102+```
103+
104+| Field | Meaning |
105+|---|---|
106+| `id` | Echo of the request `id` |
107+| `ok` | `true` on success |
108+| `done` | Level reached: `committed`, `settled`, `presented` |
109+| `diff` | Changes since the request: `mapped`, `unmapped` (window IDs), `focus_from`, `focus_to`, `focus_changed`, `workspaces` (`"OUTPUT:WS"` for each output whose shown workspace changed). Unchanged parts are omitted. |
110+| `state` | State after the request, in the state file's shape, without window titles |
111+| `late` | Window IDs still not settled at timeout |
112+| `shots` | Captures: `{output, path, seq, png?}` |
113+| `dir` | Continuous capture directory |
114+| `error` | Error code, omitted on success |
115+| `detail` | Human-readable detail for some errors |
116+
117+## Captures
118+
119+```json
120+{"id":4,"op":"shot","outputs":["HEADLESS-1"],"inline":true}
121+{"id":4,"ok":true,"done":"presented","shots":[{"output":"HEADLESS-1","path":"/run/user/1000/neferwl/sessions/demo/shots/7-HEADLESS-1.png","seq":7,"png":"iVBOR..."}],...}
122+```
123+
124+An empty or missing `outputs` selects every output; an unknown name is
125+`bad-request`. Shots wait for presentation and write private 8-bit sRGB PNG
126+files under the session's `shots/` directory. `seq` is the presented scene
127+sequence. `png` (base64) is present only with `inline: true`; the file is
128+written anyway. `raw: true` on a single shot is `bad-request` with
129+`detail: "raw shots need --every-frame"`.
130+
131+Continuous capture:
132+
133+```json
134+{"id":5,"op":"shot","every_frame":true,"dir":"/tmp/frames","outputs":["HEADLESS-1"],"raw":false}
135+{"id":6,"op":"shot","stop":true}
136+```
137+
138+`dir` must be absolute; it defaults to the session's `shots/frames`. With
139+several outputs, each writes to `<dir>/<output>/`. Each directory gets
140+`frame-NNNNNN.png`, `latest.png` (hard link to the newest frame) and
141+`frames.ffconcat`; `raw: true` adds `latest-pq.png` on HDR outputs. Frames are
142+skipped while the session is locked. `every_frame` with `stop`, or with
143+`inline`, is `bad-request`.
144+
145+## Runtime outputs
146+
147+```json
148+{"id":7,"op":"output-add","mode":"800x600@60","name":"extra"}
149+{"id":8,"op":"output-rm","name":"extra"}
150+```
151+
152+The reply comes once core state lists or drops the output, within 10 seconds.
153+
154+## Errors
155+
156+| Code | Meaning |
157+|---|---|
158+| `bad-request` | Invalid JSON, unknown `op`, or invalid fields |
159+| `unknown-command` | `action` is not in the catalog |
160+| `forbidden` | The connection lacks the capability |
161+| `locked` | The session is locked: actions other than `quit`, input and captures are refused |
162+| `busy` | 64 requests are already waiting, or the capture backend is busy; retry later |
163+| `timeout` | The completion condition was not reached in time; partial results are included |
164+| `capture-failed` | A capture or the frame writer failed; see `detail` |
165+
166+## Session startup
167+
168+`neferwl session new` starts a detached child with stdin, stdout and stderr on
169+`/dev/null`:
170+
171+```text
172+<executable> --backend=headless --profile=P --session-id=ID --ready-fd=3
173+ [--size=WxH,...] [--config=PATH] [--timeout=TTL] [extra flags...]
174+```
175+
176+The child writes one JSON line with `id`, `wayland`, `control` and `display`
177+to fd 3 when ready, then closes it. EOF before that line means startup failed.
178+The child environment drops `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`, `DISPLAY`,
179+`NEFERWL_SESSION`, `NEFERWL_CONTROL`, `NEFERWL_STATE` and `NEFERWL_SLOT`, and
180+`DBUS_SESSION_BUS_ADDRESS` unless `--dbus-session` is given.
181+
182+Session metadata lives in `$XDG_RUNTIME_DIR/neferwl/sessions/<id>/meta.json`
183+beside `control.sock`, `state.json`, `shots/` and a lifetime `lock`.
184+`session ls` reclaims unlocked stale directories. `session rm` sends
185+`{"op":"do","action":"quit","wait":"committed"}` and waits for the lock to be
186+released; if the socket is unreachable, it sends SIGTERM only after checking
187+that the recorded PID runs the same executable.
@@ -0,0 +1,187 @@
1+# Control protocol
2+
3+Wire reference for the headless control socket. For sessions, targeting and CLI
4+usage, see [Scripting and agents](../control.md).
5+
6+## Connection
7+
8+Each session listens on `$XDG_RUNTIME_DIR/neferwl/sessions/<id>/control.sock`
9+(directory `0700`, socket `0600`). The server reads the peer's credentials with
10+`SO_PEERCRED` and closes connections from another uid. An accepted connection
11+has every capability: `read`, `act`, `input`, `capture`, `admin`.
12+
13+Messages are JSON lines: one object per line, in both directions. A connection
14+handles one request at a time: the next line is read after the previous reply
15+is sent. Open several connections for concurrent requests.
16+
17+`id` is optional and may be any JSON value; the reply echoes it, or carries
18+`null` when it is missing or the line is not valid JSON.
19+
20+## Handshake
21+
22+```json
23+{"id":1,"op":"hello"}
24+{"id":1,"ok":true,"v":1,"caps":["read","act","input","capture","admin"],"commands":[{"name":"output-add","arg":"MODE","kind":"admin","caps":["admin"],"summary":"Add a runtime virtual output."},...]}
25+```
26+
27+`commands` is the catalog: each entry has `name`, `arg`, `kind` (`action`,
28+`action-arg`, `query`, `inject`, `shot`, `admin`), `caps` and `summary`. Action
29+names are the bind actions; `do` has no automation-only names. Additive changes
30+keep `v: 1`; clients ignore unknown fields.
31+
32+## Requests
33+
34+| `op` | Fields | Capability |
35+|---|---|---|
36+| `do` | `action` (name and arguments, e.g. `"focus-workspace 2"`), wait fields | `act` |
37+| `inject` | `kind` and its fields (below), wait fields | `input` |
38+| `query` | `what`: `"state"` | `read` |
39+| `shot` | `outputs`, `inline`, `raw`, `timeout` | `capture` |
40+| `shot` (continuous) | `every_frame` or `stop`, `outputs`, `dir`, `raw` | `capture` |
41+| `output-add` | `mode` (`WxH[@Hz]`), optional `name` | `admin` |
42+| `output-rm` | `name` | `admin` |
43+
44+Wait fields, on `do` and `inject`:
45+
46+| Field | Type | Default | Meaning |
47+|---|---|---|---|
48+| `wait` | `"committed"`, `"settled"`, `"presented"` | `"settled"` | Completion level |
49+| `until` | string | none | State predicate |
50+| `timeout` | Go duration string | `"10s"` | Bound on the wait, at most `5m` |
51+| `shot` | `true`, `false` or a list of output names | none | Capture after the wait; implies `presented` |
52+
53+### Inject kinds
54+
55+| `kind` | Fields | Meaning |
56+|---|---|---|
57+| `key` | `combo` | Press and release a combination such as `Super+Return` |
58+| `type` | `text` | Type text through the session keymap |
59+| `press`, `release` | `combo` | Press, or release in reverse order |
60+| `pointer` | `cmd`, `args` | `move` with absolute global logical `x`, `y` strings; `click` (default `left`), `down`, `up` with `left`, `right` or `middle` |
61+| `swipe` | `fingers` (3 or 4), `dir` | Touchpad swipe `up`, `down`, `left` or `right` |
62+
63+```json
64+{"id":1,"op":"inject","kind":"key","combo":"Super+Return","until":"window-mapped app_id=foot"}
65+{"id":2,"op":"inject","kind":"pointer","cmd":"move","args":["320","240"]}
66+{"id":3,"op":"inject","kind":"swipe","fingers":4,"dir":"down","wait":"presented"}
67+```
68+
69+Injected input goes through the core input path, so compositor binds run as
70+for a physical device. The first injection on a connection announces an input
71+device with ID `1` named `control` (for `output.<name>.input = control`).
72+
73+## Wait semantics
74+
75+- `committed`: the action or input batch has been applied to core state.
76+- `settled`: animations are finished and every affected window has committed
77+ its configured size.
78+- `presented`: the resulting scene has been presented on its outputs.
79+
80+`until` is checked on top of the level; the reply comes when both hold.
81+
82+| Predicate | Holds when |
83+|---|---|
84+| `window-mapped app_id=APP` | A window with that app ID mapped after the request |
85+| `focused app_id=APP` | A window with that app ID has focus |
86+| `unmapped id=N` | Window `N` is gone |
87+
88+`timeout` covers the wait and any capture together. A `timeout` above `5m` is
89+`bad-request` with `detail: "timeout exceeds 5m"`. On timeout the reply has
90+`error: "timeout"` and still carries `diff`, `state` and `late`: the action may
91+have run.
92+
93+At most 64 requests wait at once per session (any request with `wait` above
94+`committed`, `until`, `shot`, `output-add` or `output-rm`). A further one gets
95+`busy` before it runs. Committed-only requests and `quit` are never refused for
96+this.
97+
98+## Replies
99+
100+```json
101+{"id":2,"ok":true,"done":"settled","diff":{"mapped":[2],"focus_from":1,"focus_to":2,"focus_changed":true},"state":{...},"late":null}
102+```
103+
104+| Field | Meaning |
105+|---|---|
106+| `id` | Echo of the request `id` |
107+| `ok` | `true` on success |
108+| `done` | Level reached: `committed`, `settled`, `presented` |
109+| `diff` | Changes since the request: `mapped`, `unmapped` (window IDs), `focus_from`, `focus_to`, `focus_changed`, `workspaces` (`"OUTPUT:WS"` for each output whose shown workspace changed). Unchanged parts are omitted. |
110+| `state` | State after the request, in the state file's shape, without window titles |
111+| `late` | Window IDs still not settled at timeout |
112+| `shots` | Captures: `{output, path, seq, png?}` |
113+| `dir` | Continuous capture directory |
114+| `error` | Error code, omitted on success |
115+| `detail` | Human-readable detail for some errors |
116+
117+## Captures
118+
119+```json
120+{"id":4,"op":"shot","outputs":["HEADLESS-1"],"inline":true}
121+{"id":4,"ok":true,"done":"presented","shots":[{"output":"HEADLESS-1","path":"/run/user/1000/neferwl/sessions/demo/shots/7-HEADLESS-1.png","seq":7,"png":"iVBOR..."}],...}
122+```
123+
124+An empty or missing `outputs` selects every output; an unknown name is
125+`bad-request`. Shots wait for presentation and write private 8-bit sRGB PNG
126+files under the session's `shots/` directory. `seq` is the presented scene
127+sequence. `png` (base64) is present only with `inline: true`; the file is
128+written anyway. `raw: true` on a single shot is `bad-request` with
129+`detail: "raw shots need --every-frame"`.
130+
131+Continuous capture:
132+
133+```json
134+{"id":5,"op":"shot","every_frame":true,"dir":"/tmp/frames","outputs":["HEADLESS-1"],"raw":false}
135+{"id":6,"op":"shot","stop":true}
136+```
137+
138+`dir` must be absolute; it defaults to the session's `shots/frames`. With
139+several outputs, each writes to `<dir>/<output>/`. Each directory gets
140+`frame-NNNNNN.png`, `latest.png` (hard link to the newest frame) and
141+`frames.ffconcat`; `raw: true` adds `latest-pq.png` on HDR outputs. Frames are
142+skipped while the session is locked. `every_frame` with `stop`, or with
143+`inline`, is `bad-request`.
144+
145+## Runtime outputs
146+
147+```json
148+{"id":7,"op":"output-add","mode":"800x600@60","name":"extra"}
149+{"id":8,"op":"output-rm","name":"extra"}
150+```
151+
152+The reply comes once core state lists or drops the output, within 10 seconds.
153+
154+## Errors
155+
156+| Code | Meaning |
157+|---|---|
158+| `bad-request` | Invalid JSON, unknown `op`, or invalid fields |
159+| `unknown-command` | `action` is not in the catalog |
160+| `forbidden` | The connection lacks the capability |
161+| `locked` | The session is locked: actions other than `quit`, input and captures are refused |
162+| `busy` | 64 requests are already waiting, or the capture backend is busy; retry later |
163+| `timeout` | The completion condition was not reached in time; partial results are included |
164+| `capture-failed` | A capture or the frame writer failed; see `detail` |
165+
166+## Session startup
167+
168+`neferwl session new` starts a detached child with stdin, stdout and stderr on
169+`/dev/null`:
170+
171+```text
172+<executable> --backend=headless --profile=P --session-id=ID --ready-fd=3
173+ [--size=WxH,...] [--config=PATH] [--timeout=TTL] [extra flags...]
174+```
175+
176+The child writes one JSON line with `id`, `wayland`, `control` and `display`
177+to fd 3 when ready, then closes it. EOF before that line means startup failed.
178+The child environment drops `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`, `DISPLAY`,
179+`NEFERWL_SESSION`, `NEFERWL_CONTROL`, `NEFERWL_STATE` and `NEFERWL_SLOT`, and
180+`DBUS_SESSION_BUS_ADDRESS` unless `--dbus-session` is given.
181+
182+Session metadata lives in `$XDG_RUNTIME_DIR/neferwl/sessions/<id>/meta.json`
183+beside `control.sock`, `state.json`, `shots/` and a lifetime `lock`.
184+`session ls` reclaims unlocked stale directories. `session rm` sends
185+`{"op":"do","action":"quit","wait":"committed"}` and waits for the lock to be
186+released; if the socket is unreachable, it sends SIGTERM only after checking
187+that the recorded PID runs the same executable.
M docs/dev/headless.md +69 -77
@@ -1,59 +1,45 @@
1-# Headless mode
1+# Headless testing
22
3-Runs NeferWL without a screen, for tests and quick checks:
3+Test user-facing changes on an isolated headless session before merging. The
4+session has its own Wayland display, control socket and logs, so the desktop
5+stays untouched. [Scripting and agents](../control.md) documents every control
6+command; this page covers testing NeferWL itself.
47
5-```sh
6-neferwl --backend=headless --screenshot /tmp/neferwl-shots
7-WAYLAND_DISPLAY=<name from the log> foot
8-```
9-
10-- `latest.png` shows the current frame; `frames.ffconcat` records frame timing. Every frame is also saved as `frame-NNNNNN.png`, so the directory grows. `latest.png` is a hard link to the newest frame, so replace it rather than editing it in place.
11-- `--size 640x360,640x360` creates two outputs, arranged left to right,
12- for testing `focus-monitor-left/right` and moving columns between outputs.
13-- With several outputs, each writes to `<dir>/HEADLESS-<n>/`.
14-- `--timeout 5s` stops NeferWL after 5 seconds.
15-- Animations are on by default. For checks that need instant layout changes, set `animations = off` in the throwaway config; otherwise let transitions settle before checking final geometry.
16-- `grim` and recorders work too; see [Screen capture](../capture.md).
17-
18-## Recording a video
19-
20-Convert the screenshots and their real-time timing index into a video:
8+## End-to-end recipe
219
2210 ```sh
23-ffmpeg -f concat -safe 0 -i /tmp/shots/frames.ffconcat -vf "fps=60,format=yuv420p" -c:v libx264 -crf 18 demo.mp4
11+T=$(mktemp -d)
12+CGO_ENABLED=0 go build -o "$T/neferwl" ./cmd/neferwl
13+printf 'animations = off\n' >"$T/config"
14+"$T/neferwl" session new --id test --config "$T/config" --ttl 60s -- --no-xwayland
15+"$T/neferwl" -s test key Super+Return --until 'window-mapped app_id=foot'
16+"$T/neferwl" -s test state | jq '.windows[] | {id, app_id, column, row}'
17+"$T/neferwl" -s test shot
18+"$T/neferwl" session rm test
2419 ```
2520
26-For a GIF, convert `demo.mp4` with ffmpeg's `palettegen` and `paletteuse` filters.
27-
28-### Demo recording
21+- Use the branch binary for every command and `-s test` for every control
22+ command.
23+- `--size 640x360,640x360` creates two outputs, left to right.
24+- With animations on, keep the default `--wait settled` before reading
25+ geometry.
26+- Launch external clients with the `wayland` display from the readiness JSON.
27+- Logs: `$XDG_STATE_HOME/neferwl/sessions/test/latest.log`.
28+- Record a sequence with `shot --every-frame` and `shot --stop`; see
29+ [Every frame and video](../control.md#every-frame-and-video).
30+
31+## Demo recording
2932 Run `tools/demo/record.sh`. It requires Go 1.27, rootless Docker, ffmpeg, network access and an AMD GPU.
3033 It builds the Arch image (apps, tesseract, AT-SPI) and the compositor binary, then records the 1080p README demo.
3134 The compositor runs headless inside a disposable container, with the binary and a work directory bind-mounted and `/dev/dri` passed for the GPU.
3235 The image only carries Mesa's radeon Vulkan driver, and hint scans need the sync files that a hardware driver exports; the script stops early without an AMD render node.
3336 Firefox opens a live DuckDuckGo page, so the recording needs the network and its content varies.
34-A FIFO feeds `input.txt` while the script launches the apps on the same clock.
37+The recording script translates `input.txt` into control-socket commands while launching apps on the same clock.
3538 The hint step makes Firefox fullscreen and labels the page with `hint`; `hint-click <words>` then types the label of the link that shows those words, found from the scan's dump and an OCR read of the still page (`hint-read`).
36-The recording only counts if the compositor stops on the quit key that ends `input.txt`; reaching its `--timeout` first fails the run as truncated.
39+The recording only counts if the compositor stops on the quit key that ends `input.txt`; reaching its lifetime limit first fails the run as truncated.
3740 Temporary captures are removed by default; set `KEEP_CAPTURE=1` to keep successful runs.
3841 The recording and poster replace `docs/media/demo.mp4` and `docs/media/demo.png`.
3942
40-## Input scripts
41-
42-`--input <file>`, or `--input -` for stdin, plays one command per line:
43-
44-| Command | Effect |
45-|---|---|
46-| `type <text>` | Type text |
47-| `key Super+Return` | Press a key, with optional Shift, Ctrl, Alt or Super |
48-| `hold Super+h 1s` | Press a key like `key`, hold it, then release it |
49-| `press Super`, `release Super` | Hold or release a modifier across mouse actions (`Super`, `Shift`, `Ctrl`, `Alt`) |
50-| `sleep 1s` | Wait |
51-| `move <x> <y>` | Move the pointer, in output coordinates |
52-| `click [left\|right\|middle]`, `down <button>`, `up <button>` | Mouse buttons |
53-| `vt away`, `vt back` | Simulate a VT switch: the keys and modifiers held are forgotten and the seat goes inactive, then active again |
54-| `swipe up\|down\|left\|right` | Three-finger flick |
55-| `swipe4 up\|down` | Four-finger flick |
56-
5743 ## Testing input methods
5844
5945 `examples/testime` sends a preedit string, then commits text, each time an app enables text input:
@@ -66,7 +52,7 @@ WAYLAND_DISPLAY=<name> go run ./examples/testime -preedit nihon -commit 日本
6652
6753 ## Testing the virtual pointer
6854
69-`neferwl pointer` drives the pointer of the headless session (same display resolution as `neferwl state`); run it with the headless `WAYLAND_DISPLAY`:
55+`neferwl pointer` drives the pointer of the session whose `WAYLAND_DISPLAY` it runs with:
7056
7157 ```sh
7258 WAYLAND_DISPLAY=<name> neferwl pointer abs 0.1 0.5 click
@@ -74,7 +60,7 @@ WAYLAND_DISPLAY=<name> neferwl pointer drag 100 0 scroll down 3
7460 WAYLAND_DISPLAY=<name> neferwl pointer --output HEADLESS-2 abs 0.5 0.5
7561 ```
7662
77-Check the result with `neferwl state` (`.window.id` is the focused window). Headless screenshots do not show the cursor. `TestPointerCLI` (`internal/app`, in `go test ./...`) runs the built binary against a headless NeferWL and checks a click, a drag, a scroll and the release at exit on a test client.
63+Check the result with `neferwl -s <id> state` (`.window.id` is the focused window). Single shots do not show the cursor; `--every-frame` frames do. `TestPointerCLI` (`internal/app`, in `go test ./...`) runs the built binary against a headless NeferWL and checks a click, a drag, a scroll and the release at exit on a test client.
7864
7965 ## wayvnc check
8066
@@ -138,41 +124,36 @@ For the test installation these are
138124 `~/.local/share/nefer-hints-test/models`.
139125
140126 ```sh
141-env -u NEFERWL_STATE -u NEFERWL_SLOT XDG_STATE_HOME="$T/state" \
142- NEFERWL_HINT_DEBUG=1 dbus-run-session -- bash -c '
127+XDG_STATE_HOME="$T/state" NEFERWL_HINT_DEBUG=1 dbus-run-session -- bash -c '
143128 T=$1
144- # Enable accessibility before either the compositor or its clients starts.
145129 gdbus call --session --dest org.a11y.Bus --object-path /org/a11y/bus \
146130 --method org.freedesktop.DBus.Properties.Set org.a11y.Status IsEnabled "<true>"
147- # On hosts whose registry service activation is unavailable (adjust path).
148131 /usr/lib/at-spi2-registryd >"$T/registry.log" 2>&1 &
149- WAYLAND_DISPLAY=wp4-headless "$T/neferwl" --backend=headless \
150- --config "$T/config" --no-xwayland --screenshot "$T/shots" \
151- --input "$T/input" --timeout 20s & compositor=$!
152- # Bounded wait for the actual display, not an inherited live-session display.
153- for i in {1..50}; do
154- display=$(jq -r "select(.message == \"listening\") | .WAYLAND_DISPLAY" \
155- "$T/state/neferwl/runs/headless/latest.log" 2>/dev/null | head -1)
156- [ -n "$display" ] && break
157- sleep .1
158- done
159- [ -n "$display" ] || exit 1
160- export WAYLAND_DISPLAY="$display"
132+ ready=$("$T/neferwl" session new --id hints --dbus-session --config "$T/config" \
133+ --ttl 60s -- --no-xwayland)
134+ export WAYLAND_DISPLAY=$(printf "%s" "$ready" | jq -r .wayland)
135+ "$T/neferwl" -s hints shot --every-frame --dir "$T/shots"
161136 foot sh -c "printf https://example.org/a; exec sleep 60" &
162137 chromium --ozone-platform=wayland --force-renderer-accessibility \
163138 --user-data-dir="$T/chrome" "file://$T/page.html" >"$T/chromium.log" 2>&1 &
164- wait "$compositor"
139+ "$T/neferwl" -s hints key Super+g --until "window-mapped app_id=chromium"
140+ read -r -p "Visible hint label: " label
141+ "$T/neferwl" -s hints type "$label"
142+ "$T/neferwl" -s hints shot
143+ "$T/neferwl" -s hints shot --stop
144+ "$T/neferwl" session rm hints
165145 ' bash "$T"
166146 ```
167147
168148 All clients and state queries must run inside that wrapper shell so they share
169149 its session bus as well as its Wayland display. Logs are in
170-`$T/state/neferwl/runs/headless/latest.log`.
171-Prepare `$T/page.html` with underlined local links before running. OCR detects
150+`$T/state/neferwl/sessions/hints/latest.log`.
151+Prepare `$T/page.html` with underlined local links before running (the shell example also needs `jq`). OCR detects
172152 URL-like text without an underline and underlined link text; ordinary menu
173153 labels, buttons, separators and box borders do not produce OCR targets. Arrange both windows
174154 visibly; open a menu if possible.
175-Script `sleep 8s`, `key Super+g`, `sleep 4s`, then `type <visible label>`.
155+Wait for the clients to map, run `neferwl -s hints key Super+g`, then use
156+`neferwl -s hints type <visible-label>` while the session is running.
176157 Check screenshots before and after the click; a local link changing the page
177158 background is a convenient observable result.
178159
@@ -193,7 +174,7 @@ sources (startup rejects `hint.sources = ocr, ocr`).
193174
194175 ## OCR URL opening
195176
196-OCR targets with an http, https or mailto URL run `xdg-open` instead of a click. The recipe builds the binary, writes a minimal config and input script, and puts a fake `xdg-open` first in `PATH`. It needs the hint prerequisites listed above.
177+OCR targets with an http, https or mailto URL run `xdg-open` instead of a click. The recipe builds the binary, writes a minimal config, and puts a fake `xdg-open` first in `PATH`. It needs the hint prerequisites listed above.
197178
198179 ```sh
199180 T=$(mktemp -d); mkdir "$T/bin"
@@ -208,12 +189,21 @@ hint.sources = atspi, ocr
208189 bind.cmd+g = hint
209190 bind.cmd+u = spawn foot -o main.font=monospace:size=28 $T/show.sh
210191 EOF
211-printf 'sleep 1s\nkey Super+u\nsleep 4s\nkey Super+g\nsleep 4s\n' >"$T/input"
212-env -u NEFERWL_STATE -u NEFERWL_SLOT PATH="$T/bin:$PATH" "$T/neferwl" --backend=headless \
213- --config "$T/config" --no-xwayland --screenshot "$T/shots" --input "$T/input" --timeout 20s
192+PATH="$T/bin:$PATH" "$T/neferwl" session new --id ocr --config "$T/config" --ttl 60s -- --no-xwayland
193+"$T/neferwl" -s ocr shot --every-frame --dir "$T/shots"
194+"$T/neferwl" -s ocr key Super+u --until 'window-mapped app_id=foot'
195+"$T/neferwl" -s ocr key Super+g
196+"$T/neferwl" -s ocr shot
197+# Read the visible hint label, then:
198+"$T/neferwl" -s ocr type '<label>'
199+"$T/neferwl" -s ocr shot --stop
200+"$T/neferwl" session rm ocr
214201 ```
215202
216-The input script opens a large-font foot showing `https://example.com` and runs `hint`. Read the label from the screenshot, then append `type <label>` and a `sleep 2s` to `$T/input` and run again. `$T/opened` then holds exactly `https://example.com`. A `file:` target is clicked and leaves it empty. Launcher failures are in the log under `component=launcher`.
203+The foot window shows `https://example.com`. Typing its hint label opens that
204+URL; `$T/opened` holds exactly `https://example.com`. A `file:` target is clicked
205+and leaves it empty. Launcher failures are in the session log under
206+`component=launcher`.
217207
218208 ## Primary output coordinates
219209
@@ -247,13 +237,15 @@ output.HEADLESS-2.right-of = HEADLESS-1
247237 On the isolated headless display, `wayland-info -i wl_output` should report
248238 HEADLESS-1 at (-640,0) and HEADLESS-2 at (0,0).
249239
250-Scripted input announces device ID `1` with the fixed name `headless-script`.
251-Use `output.tv.input = headless-script` to test device-bound focus on a virtual
252-output. The script's `move` coordinates remain global logical coordinates.
240+## Control input device
241+
242+Control input announces device ID `1` named `control`. Use
243+`output.tv.input = control` to test device-bound focus on a virtual output.
244+Control `move` coordinates stay global logical coordinates.
245+
246+## Session paths
253247
254-`device <id>` selects the scripted device for subsequent keys, motions, buttons
255-and gestures (positive integer; default `1`). A newly selected ID is announced
256-once: ID `1` is `headless-script`, other IDs are `headless-script-<id>`.
257-Devices share the scripted seat's keymap; release held keys before switching.
258-For example, bind `headless-script-2` to `tv`, then interleave `device 2`,
259-`key a`, `device 1`, `key a` to exercise bound/unbound focus switching.
248+`$XDG_RUNTIME_DIR/neferwl/sessions/<id>/` holds `meta.json`, `control.sock`,
249+`state.json` and `shots/`. Logs live in
250+`$XDG_STATE_HOME/neferwl/sessions/<id>/`; the 20 most recent session log
251+directories are kept.
@@ -1,59 +1,45 @@
1-# Headless mode1+# Headless testing
2 2
3-Runs NeferWL without a screen, for tests and quick checks:3+Test user-facing changes on an isolated headless session before merging. The
4+session has its own Wayland display, control socket and logs, so the desktop
5+stays untouched. [Scripting and agents](../control.md) documents every control
6+command; this page covers testing NeferWL itself.
4 7
5-```sh8+## End-to-end recipe
6-neferwl --backend=headless --screenshot /tmp/neferwl-shots
7-WAYLAND_DISPLAY=<name from the log> foot
8-```
9-
10-- `latest.png` shows the current frame; `frames.ffconcat` records frame timing. Every frame is also saved as `frame-NNNNNN.png`, so the directory grows. `latest.png` is a hard link to the newest frame, so replace it rather than editing it in place.
11-- `--size 640x360,640x360` creates two outputs, arranged left to right,
12- for testing `focus-monitor-left/right` and moving columns between outputs.
13-- With several outputs, each writes to `<dir>/HEADLESS-<n>/`.
14-- `--timeout 5s` stops NeferWL after 5 seconds.
15-- Animations are on by default. For checks that need instant layout changes, set `animations = off` in the throwaway config; otherwise let transitions settle before checking final geometry.
16-- `grim` and recorders work too; see [Screen capture](../capture.md).
17-
18-## Recording a video
19-
20-Convert the screenshots and their real-time timing index into a video:
21 9
22 ```sh10 ```sh
23-ffmpeg -f concat -safe 0 -i /tmp/shots/frames.ffconcat -vf "fps=60,format=yuv420p" -c:v libx264 -crf 18 demo.mp411+T=$(mktemp -d)
12+CGO_ENABLED=0 go build -o "$T/neferwl" ./cmd/neferwl
13+printf 'animations = off\n' >"$T/config"
14+"$T/neferwl" session new --id test --config "$T/config" --ttl 60s -- --no-xwayland
15+"$T/neferwl" -s test key Super+Return --until 'window-mapped app_id=foot'
16+"$T/neferwl" -s test state | jq '.windows[] | {id, app_id, column, row}'
17+"$T/neferwl" -s test shot
18+"$T/neferwl" session rm test
24 ```19 ```
25 20
26-For a GIF, convert `demo.mp4` with ffmpeg's `palettegen` and `paletteuse` filters.21+- Use the branch binary for every command and `-s test` for every control
27-22+ command.
28-### Demo recording23+- `--size 640x360,640x360` creates two outputs, left to right.
24+- With animations on, keep the default `--wait settled` before reading
25+ geometry.
26+- Launch external clients with the `wayland` display from the readiness JSON.
27+- Logs: `$XDG_STATE_HOME/neferwl/sessions/test/latest.log`.
28+- Record a sequence with `shot --every-frame` and `shot --stop`; see
29+ [Every frame and video](../control.md#every-frame-and-video).
30+
31+## Demo recording
29 Run `tools/demo/record.sh`. It requires Go 1.27, rootless Docker, ffmpeg, network access and an AMD GPU.32 Run `tools/demo/record.sh`. It requires Go 1.27, rootless Docker, ffmpeg, network access and an AMD GPU.
30 It builds the Arch image (apps, tesseract, AT-SPI) and the compositor binary, then records the 1080p README demo.33 It builds the Arch image (apps, tesseract, AT-SPI) and the compositor binary, then records the 1080p README demo.
31 The compositor runs headless inside a disposable container, with the binary and a work directory bind-mounted and `/dev/dri` passed for the GPU.34 The compositor runs headless inside a disposable container, with the binary and a work directory bind-mounted and `/dev/dri` passed for the GPU.
32 The image only carries Mesa's radeon Vulkan driver, and hint scans need the sync files that a hardware driver exports; the script stops early without an AMD render node.35 The image only carries Mesa's radeon Vulkan driver, and hint scans need the sync files that a hardware driver exports; the script stops early without an AMD render node.
33 Firefox opens a live DuckDuckGo page, so the recording needs the network and its content varies.36 Firefox opens a live DuckDuckGo page, so the recording needs the network and its content varies.
34-A FIFO feeds `input.txt` while the script launches the apps on the same clock.37+The recording script translates `input.txt` into control-socket commands while launching apps on the same clock.
35 The hint step makes Firefox fullscreen and labels the page with `hint`; `hint-click <words>` then types the label of the link that shows those words, found from the scan's dump and an OCR read of the still page (`hint-read`).38 The hint step makes Firefox fullscreen and labels the page with `hint`; `hint-click <words>` then types the label of the link that shows those words, found from the scan's dump and an OCR read of the still page (`hint-read`).
36-The recording only counts if the compositor stops on the quit key that ends `input.txt`; reaching its `--timeout` first fails the run as truncated.39+The recording only counts if the compositor stops on the quit key that ends `input.txt`; reaching its lifetime limit first fails the run as truncated.
37 Temporary captures are removed by default; set `KEEP_CAPTURE=1` to keep successful runs.40 Temporary captures are removed by default; set `KEEP_CAPTURE=1` to keep successful runs.
38 The recording and poster replace `docs/media/demo.mp4` and `docs/media/demo.png`.41 The recording and poster replace `docs/media/demo.mp4` and `docs/media/demo.png`.
39 42
40-## Input scripts
41-
42-`--input <file>`, or `--input -` for stdin, plays one command per line:
43-
44-| Command | Effect |
45-|---|---|
46-| `type <text>` | Type text |
47-| `key Super+Return` | Press a key, with optional Shift, Ctrl, Alt or Super |
48-| `hold Super+h 1s` | Press a key like `key`, hold it, then release it |
49-| `press Super`, `release Super` | Hold or release a modifier across mouse actions (`Super`, `Shift`, `Ctrl`, `Alt`) |
50-| `sleep 1s` | Wait |
51-| `move <x> <y>` | Move the pointer, in output coordinates |
52-| `click [left\|right\|middle]`, `down <button>`, `up <button>` | Mouse buttons |
53-| `vt away`, `vt back` | Simulate a VT switch: the keys and modifiers held are forgotten and the seat goes inactive, then active again |
54-| `swipe up\|down\|left\|right` | Three-finger flick |
55-| `swipe4 up\|down` | Four-finger flick |
56-
57 ## Testing input methods43 ## Testing input methods
58 44
59 `examples/testime` sends a preedit string, then commits text, each time an app enables text input:45 `examples/testime` sends a preedit string, then commits text, each time an app enables text input:
@@ -66,7 +52,7 @@ WAYLAND_DISPLAY=<name> go run ./examples/testime -preedit nihon -commit 日本
66 52
67 ## Testing the virtual pointer53 ## Testing the virtual pointer
68 54
69-`neferwl pointer` drives the pointer of the headless session (same display resolution as `neferwl state`); run it with the headless `WAYLAND_DISPLAY`:55+`neferwl pointer` drives the pointer of the session whose `WAYLAND_DISPLAY` it runs with:
70 56
71 ```sh57 ```sh
72 WAYLAND_DISPLAY=<name> neferwl pointer abs 0.1 0.5 click58 WAYLAND_DISPLAY=<name> neferwl pointer abs 0.1 0.5 click
@@ -74,7 +60,7 @@ WAYLAND_DISPLAY=<name> neferwl pointer drag 100 0 scroll down 3
74 WAYLAND_DISPLAY=<name> neferwl pointer --output HEADLESS-2 abs 0.5 0.560 WAYLAND_DISPLAY=<name> neferwl pointer --output HEADLESS-2 abs 0.5 0.5
75 ```61 ```
76 62
77-Check the result with `neferwl state` (`.window.id` is the focused window). Headless screenshots do not show the cursor. `TestPointerCLI` (`internal/app`, in `go test ./...`) runs the built binary against a headless NeferWL and checks a click, a drag, a scroll and the release at exit on a test client.63+Check the result with `neferwl -s <id> state` (`.window.id` is the focused window). Single shots do not show the cursor; `--every-frame` frames do. `TestPointerCLI` (`internal/app`, in `go test ./...`) runs the built binary against a headless NeferWL and checks a click, a drag, a scroll and the release at exit on a test client.
78 64
79 ## wayvnc check65 ## wayvnc check
80 66
@@ -138,41 +124,36 @@ For the test installation these are
138 `~/.local/share/nefer-hints-test/models`.124 `~/.local/share/nefer-hints-test/models`.
139 125
140 ```sh126 ```sh
141-env -u NEFERWL_STATE -u NEFERWL_SLOT XDG_STATE_HOME="$T/state" \127+XDG_STATE_HOME="$T/state" NEFERWL_HINT_DEBUG=1 dbus-run-session -- bash -c '
142- NEFERWL_HINT_DEBUG=1 dbus-run-session -- bash -c '
143 T=$1128 T=$1
144- # Enable accessibility before either the compositor or its clients starts.
145 gdbus call --session --dest org.a11y.Bus --object-path /org/a11y/bus \129 gdbus call --session --dest org.a11y.Bus --object-path /org/a11y/bus \
146 --method org.freedesktop.DBus.Properties.Set org.a11y.Status IsEnabled "<true>"130 --method org.freedesktop.DBus.Properties.Set org.a11y.Status IsEnabled "<true>"
147- # On hosts whose registry service activation is unavailable (adjust path).
148 /usr/lib/at-spi2-registryd >"$T/registry.log" 2>&1 &131 /usr/lib/at-spi2-registryd >"$T/registry.log" 2>&1 &
149- WAYLAND_DISPLAY=wp4-headless "$T/neferwl" --backend=headless \132+ ready=$("$T/neferwl" session new --id hints --dbus-session --config "$T/config" \
150- --config "$T/config" --no-xwayland --screenshot "$T/shots" \133+ --ttl 60s -- --no-xwayland)
151- --input "$T/input" --timeout 20s & compositor=$!134+ export WAYLAND_DISPLAY=$(printf "%s" "$ready" | jq -r .wayland)
152- # Bounded wait for the actual display, not an inherited live-session display.135+ "$T/neferwl" -s hints shot --every-frame --dir "$T/shots"
153- for i in {1..50}; do
154- display=$(jq -r "select(.message == \"listening\") | .WAYLAND_DISPLAY" \
155- "$T/state/neferwl/runs/headless/latest.log" 2>/dev/null | head -1)
156- [ -n "$display" ] && break
157- sleep .1
158- done
159- [ -n "$display" ] || exit 1
160- export WAYLAND_DISPLAY="$display"
161 foot sh -c "printf https://example.org/a; exec sleep 60" &136 foot sh -c "printf https://example.org/a; exec sleep 60" &
162 chromium --ozone-platform=wayland --force-renderer-accessibility \137 chromium --ozone-platform=wayland --force-renderer-accessibility \
163 --user-data-dir="$T/chrome" "file://$T/page.html" >"$T/chromium.log" 2>&1 &138 --user-data-dir="$T/chrome" "file://$T/page.html" >"$T/chromium.log" 2>&1 &
164- wait "$compositor"139+ "$T/neferwl" -s hints key Super+g --until "window-mapped app_id=chromium"
140+ read -r -p "Visible hint label: " label
141+ "$T/neferwl" -s hints type "$label"
142+ "$T/neferwl" -s hints shot
143+ "$T/neferwl" -s hints shot --stop
144+ "$T/neferwl" session rm hints
165 ' bash "$T"145 ' bash "$T"
166 ```146 ```
167 147
168 All clients and state queries must run inside that wrapper shell so they share148 All clients and state queries must run inside that wrapper shell so they share
169 its session bus as well as its Wayland display. Logs are in149 its session bus as well as its Wayland display. Logs are in
170-`$T/state/neferwl/runs/headless/latest.log`.150+`$T/state/neferwl/sessions/hints/latest.log`.
171-Prepare `$T/page.html` with underlined local links before running. OCR detects151+Prepare `$T/page.html` with underlined local links before running (the shell example also needs `jq`). OCR detects
172 URL-like text without an underline and underlined link text; ordinary menu152 URL-like text without an underline and underlined link text; ordinary menu
173 labels, buttons, separators and box borders do not produce OCR targets. Arrange both windows153 labels, buttons, separators and box borders do not produce OCR targets. Arrange both windows
174 visibly; open a menu if possible.154 visibly; open a menu if possible.
175-Script `sleep 8s`, `key Super+g`, `sleep 4s`, then `type <visible label>`.155+Wait for the clients to map, run `neferwl -s hints key Super+g`, then use
156+`neferwl -s hints type <visible-label>` while the session is running.
176 Check screenshots before and after the click; a local link changing the page157 Check screenshots before and after the click; a local link changing the page
177 background is a convenient observable result.158 background is a convenient observable result.
178 159
@@ -193,7 +174,7 @@ sources (startup rejects `hint.sources = ocr, ocr`).
193 174
194 ## OCR URL opening175 ## OCR URL opening
195 176
196-OCR targets with an http, https or mailto URL run `xdg-open` instead of a click. The recipe builds the binary, writes a minimal config and input script, and puts a fake `xdg-open` first in `PATH`. It needs the hint prerequisites listed above.177+OCR targets with an http, https or mailto URL run `xdg-open` instead of a click. The recipe builds the binary, writes a minimal config, and puts a fake `xdg-open` first in `PATH`. It needs the hint prerequisites listed above.
197 178
198 ```sh179 ```sh
199 T=$(mktemp -d); mkdir "$T/bin"180 T=$(mktemp -d); mkdir "$T/bin"
@@ -208,12 +189,21 @@ hint.sources = atspi, ocr
208 bind.cmd+g = hint189 bind.cmd+g = hint
209 bind.cmd+u = spawn foot -o main.font=monospace:size=28 $T/show.sh190 bind.cmd+u = spawn foot -o main.font=monospace:size=28 $T/show.sh
210 EOF191 EOF
211-printf 'sleep 1s\nkey Super+u\nsleep 4s\nkey Super+g\nsleep 4s\n' >"$T/input"192+PATH="$T/bin:$PATH" "$T/neferwl" session new --id ocr --config "$T/config" --ttl 60s -- --no-xwayland
212-env -u NEFERWL_STATE -u NEFERWL_SLOT PATH="$T/bin:$PATH" "$T/neferwl" --backend=headless \193+"$T/neferwl" -s ocr shot --every-frame --dir "$T/shots"
213- --config "$T/config" --no-xwayland --screenshot "$T/shots" --input "$T/input" --timeout 20s194+"$T/neferwl" -s ocr key Super+u --until 'window-mapped app_id=foot'
195+"$T/neferwl" -s ocr key Super+g
196+"$T/neferwl" -s ocr shot
197+# Read the visible hint label, then:
198+"$T/neferwl" -s ocr type '<label>'
199+"$T/neferwl" -s ocr shot --stop
200+"$T/neferwl" session rm ocr
214 ```201 ```
215 202
216-The input script opens a large-font foot showing `https://example.com` and runs `hint`. Read the label from the screenshot, then append `type <label>` and a `sleep 2s` to `$T/input` and run again. `$T/opened` then holds exactly `https://example.com`. A `file:` target is clicked and leaves it empty. Launcher failures are in the log under `component=launcher`.203+The foot window shows `https://example.com`. Typing its hint label opens that
204+URL; `$T/opened` holds exactly `https://example.com`. A `file:` target is clicked
205+and leaves it empty. Launcher failures are in the session log under
206+`component=launcher`.
217 207
218 ## Primary output coordinates208 ## Primary output coordinates
219 209
@@ -247,13 +237,15 @@ output.HEADLESS-2.right-of = HEADLESS-1
247 On the isolated headless display, `wayland-info -i wl_output` should report237 On the isolated headless display, `wayland-info -i wl_output` should report
248 HEADLESS-1 at (-640,0) and HEADLESS-2 at (0,0).238 HEADLESS-1 at (-640,0) and HEADLESS-2 at (0,0).
249 239
250-Scripted input announces device ID `1` with the fixed name `headless-script`.240+## Control input device
251-Use `output.tv.input = headless-script` to test device-bound focus on a virtual241+
252-output. The script's `move` coordinates remain global logical coordinates.242+Control input announces device ID `1` named `control`. Use
243+`output.tv.input = control` to test device-bound focus on a virtual output.
244+Control `move` coordinates stay global logical coordinates.
245+
246+## Session paths
253 247
254-`device <id>` selects the scripted device for subsequent keys, motions, buttons248+`$XDG_RUNTIME_DIR/neferwl/sessions/<id>/` holds `meta.json`, `control.sock`,
255-and gestures (positive integer; default `1`). A newly selected ID is announced249+`state.json` and `shots/`. Logs live in
256-once: ID `1` is `headless-script`, other IDs are `headless-script-<id>`.250+`$XDG_STATE_HOME/neferwl/sessions/<id>/`; the 20 most recent session log
257-Devices share the scripted seat's keymap; release held keys before switching.251+directories are kept.
258-For example, bind `headless-script-2` to `tv`, then interleave `device 2`,
259-`key a`, `device 1`, `key a` to exercise bound/unbound focus switching.
M docs/dev/index.md +2 -1
@@ -3,6 +3,7 @@
33 These guides cover NeferWL's internals and tools for development, testing and performance investigation. For configuration and desktop setup, see the [user documentation](../index.md).
44
55 - [Architecture](architecture.md): owner goroutines, GC strategy and reusable purego libraries.
6-- [Headless mode](headless.md): screenshots, scripted input and testing without a screen.
6+- [Headless testing](headless.md): end-to-end recipe, demo recording, X11, colour and hint checks.
7+- [Control protocol](control.md): wire messages, wait semantics, captures and error codes.
78 - [Profiling](profiling.md): CPU and allocation profiling, logging and frame statistics.
89 - [Repository rules](../../AGENTS.md): architecture constraints, test requirements and checks before merge.
@@ -3,6 +3,7 @@
3 These guides cover NeferWL's internals and tools for development, testing and performance investigation. For configuration and desktop setup, see the [user documentation](../index.md).3 These guides cover NeferWL's internals and tools for development, testing and performance investigation. For configuration and desktop setup, see the [user documentation](../index.md).
4 4
5 - [Architecture](architecture.md): owner goroutines, GC strategy and reusable purego libraries.5 - [Architecture](architecture.md): owner goroutines, GC strategy and reusable purego libraries.
6-- [Headless mode](headless.md): screenshots, scripted input and testing without a screen.6+- [Headless testing](headless.md): end-to-end recipe, demo recording, X11, colour and hint checks.
7+- [Control protocol](control.md): wire messages, wait semantics, captures and error codes.
7 - [Profiling](profiling.md): CPU and allocation profiling, logging and frame statistics.8 - [Profiling](profiling.md): CPU and allocation profiling, logging and frame statistics.
8 - [Repository rules](../../AGENTS.md): architecture constraints, test requirements and checks before merge.9 - [Repository rules](../../AGENTS.md): architecture constraints, test requirements and checks before merge.
M docs/dev/layouts.md +1 -2
@@ -134,5 +134,4 @@ Required: `CGO_ENABLED=0 go build ./...`, `make check`, `make race`,
134134
135135 For end-to-end testing follow [headless.md](headless.md): a throwaway config per
136136 layout, several windows, focus/move on both axes, grow/shrink, maximize,
137-overview and swipe, with `WAYLAND_DISPLAY` isolated and `NEFERWL_STATE` and
138-`NEFERWL_SLOT` unset.
137+overview and swipe, on an isolated session driven with `-s`.
@@ -134,5 +134,4 @@ Required: `CGO_ENABLED=0 go build ./...`, `make check`, `make race`,
134 134
135 For end-to-end testing follow [headless.md](headless.md): a throwaway config per135 For end-to-end testing follow [headless.md](headless.md): a throwaway config per
136 layout, several windows, focus/move on both axes, grow/shrink, maximize,136 layout, several windows, focus/move on both axes, grow/shrink, maximize,
137-overview and swipe, with `WAYLAND_DISPLAY` isolated and `NEFERWL_STATE` and137+overview and swipe, on an isolated session driven with `-s`.
138-`NEFERWL_SLOT` unset.
M docs/index.md +3 -2
@@ -1,11 +1,12 @@
11 # NeferWL documentation
22
3-NeferWL is a small Wayland compositor in Go. Start with Configuration to set up your keyboard, outputs and workflows, then use the guides below for desktop integration, screen capture and performance.
3+NeferWL is a small Wayland compositor in Go. Start with Configuration to set up your keyboard, outputs and workflows, then use the guides below for desktop integration, screen capture, performance and headless use.
44
55 - [Configuration](config.md): keys, actions, default bindings, layouts and HDR.
66 - [Desktop integration](desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.
77 - [Screen capture](capture.md): protocols, indicator, executable allowlist and portals.
88 - [Performance](performance.md): resource use, VRR and real-time priority.
9-- [Game server](server.md): `--backend=server` on a headless machine, streaming with Sunshine.
9+- [Headless and server mode](server.md): run NeferWL without a screen, as a long-running server or a game streaming host with Sunshine.
10+- [Scripting and agents](control.md): sessions, actions, input, state and screenshots for scripts, tests and AI agents.
1011
1112 Developer documentation: [docs/dev](dev/index.md)
@@ -1,11 +1,12 @@
1 # NeferWL documentation1 # NeferWL documentation
2 2
3-NeferWL is a small Wayland compositor in Go. Start with Configuration to set up your keyboard, outputs and workflows, then use the guides below for desktop integration, screen capture and performance.3+NeferWL is a small Wayland compositor in Go. Start with Configuration to set up your keyboard, outputs and workflows, then use the guides below for desktop integration, screen capture, performance and headless use.
4 4
5 - [Configuration](config.md): keys, actions, default bindings, layouts and HDR.5 - [Configuration](config.md): keys, actions, default bindings, layouts and HDR.
6 - [Desktop integration](desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.6 - [Desktop integration](desktop.md): sessions, clipboard, input methods, X11 apps, session locking and scripting.
7 - [Screen capture](capture.md): protocols, indicator, executable allowlist and portals.7 - [Screen capture](capture.md): protocols, indicator, executable allowlist and portals.
8 - [Performance](performance.md): resource use, VRR and real-time priority.8 - [Performance](performance.md): resource use, VRR and real-time priority.
9-- [Game server](server.md): `--backend=server` on a headless machine, streaming with Sunshine.9+- [Headless and server mode](server.md): run NeferWL without a screen, as a long-running server or a game streaming host with Sunshine.
10+- [Scripting and agents](control.md): sessions, actions, input, state and screenshots for scripts, tests and AI agents.
10 11
11 Developer documentation: [docs/dev](dev/index.md)12 Developer documentation: [docs/dev](dev/index.md)
M docs/server.md +134 -49
@@ -1,22 +1,138 @@
1-# Game server
1+# Headless and server mode
22
3-`neferwl --backend=server` runs NeferWL without a display: it drives only the virtual outputs declared in the config, reads input devices directly and serves screen casting on the session bus. With [Sunshine](https://github.com/LizardByte/Sunshine), it turns a headless machine into a game streaming host.
3+`neferwl --backend=headless` runs the compositor without a screen. Apps connect
4+to its Wayland display as usual and draw into virtual outputs, which you can
5+stream, record or capture. Use it for a game streaming host, a remote desktop
6+box, demo recordings or tests in CI.
47
5-Server mode differs from a desktop session:
8+## Profiles
69
7-- No DRM/KMS and no logind session: no physical output lights up, and no VT is taken.
8-- Virtual outputs are laid out left to right in config order, starting at 0,0. They take the startup focus and every pointer reaches them, so they are not isolated as on a desktop.
9-- The screen-casting and screensaver D-Bus services always run. The logind power-key lock does not.
10-- No terminal opens at startup. Scale changes are saved to the config, as on a desktop.
11-- The test flags (`--screenshot`, `--screenshot-raw`, `--input`, `--size`, `--timeout`, `--headless-hdr`, `--dbus`) are rejected.
10+| | `ephemeral` (default) | `persistent` |
11+|---|---|---|
12+| Use | Throwaway sessions: tests, scripts, agents, recordings | A long-running server |
13+| Outputs | `--size` heads (`HEADLESS-1`, default 1920x1080); config virtual outputs stay isolated | Virtual outputs from the config |
14+| Input devices | None; input comes from the [control socket](control.md) | Reads `/dev/input/event*` directly |
15+| `--input-devices` | `grab` reads devices too | `none` reads none |
16+| Screen casting and screensaver D-Bus services | Only with `--dbus` | Always |
17+| Scale changes | Not saved | Saved to the config |
18+| Terminal at startup | Opens | None |
19+| GPU | Any Vulkan device | A DRM render node; software rasterizers are refused |
1220
13-## Requirements
21+Both profiles have no DRM/KMS and no logind session: no physical output lights
22+up, no VT is taken and the logind power keys are not handled. Both register a
23+session with a control socket, so [`neferwl -s ID ...`](control.md) works on
24+either. A session ends on `neferwl session rm ID`, on SIGINT or SIGTERM, on the
25+`quit` action, or when `--timeout` runs out (`--ttl` for `session new`).
1426
15-- A GPU with a DRM render node (`/dev/dri/renderD*`). Software rasterizers such as lavapipe are refused.
27+In the persistent profile, virtual outputs are laid out left to right in config
28+order from 0,0. They take the startup focus and every pointer reaches them,
29+unlike virtual outputs on a desktop. `--size` also creates fixed `HEADLESS-N`
30+heads.
31+
32+`--backend=server` is a deprecated alias for
33+`--backend=headless --profile=persistent`.
34+
35+## Run it
36+
37+Declare at least one virtual output in `~/.config/neferwl/config`:
38+
39+```ini
40+output.tv = virtual 1920x1080@60
41+startup = foot
42+```
43+
44+See [Virtual outputs](config.md#virtual-outputs) for modes, HDR and placement.
45+Then start the compositor by hand, for example over SSH:
46+
47+```sh
48+neferwl --backend=headless --profile=persistent --session-id=box
49+```
50+
51+or as the systemd user service:
52+
53+```sh
54+systemctl --user enable --now neferwl-server.service
55+```
56+
57+The service runs `neferwl --backend=headless --profile=persistent --session --session-id=server`.
58+It notifies systemd when ready, exports `WAYLAND_DISPLAY` and `DISPLAY` to the
59+user manager, binds `graphical-session.target` and restarts on failure. It
60+conflicts with `neferwl.service`, so it never runs beside a desktop session.
61+
62+Programs started by the compositor (`startup`, binds, `do spawn`) already have
63+the right environment. To start a client yourself, take the display from the
64+session list or from the user manager:
65+
66+```sh
67+neferwl session ls # WAYLAND column
68+export $(systemctl --user show-environment | grep -E '^(WAYLAND_DISPLAY|DISPLAY|XDG_RUNTIME_DIR)=')
69+firefox &
70+```
71+
72+Logs are in `$XDG_STATE_HOME/neferwl/sessions/<id>/latest.log` with `--session-id`, else in `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`.
73+
74+## Watch and control it
75+
76+- **Streaming and recording**: the screen-casting portal shares each virtual
77+ output with [Sunshine](#game-streaming-with-sunshine), OBS or any PipeWire
78+ client. It needs PipeWire, `xdg-desktop-portal` and
79+ `xdg-desktop-portal-gnome` with the packaged `neferwl-portals.conf`; see
80+ [Portals](capture.md#portals).
81+- **Screenshots**: `neferwl -s server shot --output tv` writes a PNG and prints
82+ its path. `grim -o tv` works too once its executable is in
83+ [the allowlist](capture.md#the-allowlist).
84+- **Remote desktop**: [wayvnc](#wayvnc) gives a VNC view with keyboard and
85+ pointer.
86+- **Scripts and agents**: actions, input, state and captures through the
87+ control socket; see [Scripting and agents](control.md).
88+
89+```sh
90+neferwl -s server state | jq '.windows[] | {id, app_id}'
91+neferwl -s server do focus-workspace-next
92+neferwl -s server key Super+Return --until 'window-mapped app_id=foot'
93+neferwl -s server shot --output tv
94+```
95+
96+### Virtual pointer
97+
98+Tools using `zwlr_virtual_pointer_v1` move the pointer like a real mouse, so
99+focus, hover and drags behave as they would for a person. Run them with the
100+session's `WAYLAND_DISPLAY`:
101+
102+```sh
103+neferwl pointer abs 0.5 0.5 click
104+neferwl pointer move 200 -50 click right
105+```
106+
107+- `neferwl pointer` actions: `abs X Y` (fractions 0..1 of the layout, or of one output with `--output <name>`), `move DX DY`, `press`/`release`/`click [BTN]`, `hold [BTN] [DURATION]`, `drag DX DY [BTN]` and `scroll up|down|left|right [N]`. BTN is `left` (default), `right`, `middle`, `side`, `extra`, `forward`, `back`, a `BTN_*` name or an evdev code. `--click-duration` (20ms), `--hold-duration` (500ms), `--drag-steps` (10) and `--drag-step-delay` (10ms) tune the timing. Buttons still pressed at exit are released. See `neferwl pointer --help`.
108+- [wlrctl](https://git.sr.ht/~brocellous/wlrctl) (AUR: `wlrctl`) works too: `wlrctl pointer move 200 -50`, `wlrctl pointer click left`.
109+- Absolute motion maps into the whole layout, or into one output when the tool binds it (`create_virtual_pointer_with_output`).
110+- `ydotool` writes to `/dev/uinput` through `ydotoold` and does not use this protocol; prefer `neferwl pointer`.
111+- Nothing is injected while the session is locked. Buttons a tool still held when it disconnects are released.
112+- Flatpak and other sandboxed clients (those on a `wp_security_context_v1` socket) do not see the virtual pointer global.
113+
114+### wayvnc
115+
116+[wayvnc](https://github.com/any1/wayvnc) captures an output with wlr-screencopy and injects input through the virtual pointer and keyboard. Add its executable (`/usr/bin/wayvnc`) to `/etc/neferwl/capture-allow`, then run it in the session:
117+
118+```sh
119+wayvnc -o tv 127.0.0.1 5900
120+```
121+
122+Keep it on localhost and reach it through an SSH tunnel, or configure wayvnc's own authentication and TLS.
123+
124+## Game streaming with Sunshine
125+
126+With [Sunshine](https://github.com/LizardByte/Sunshine), a persistent session
127+turns a machine without a screen into a game streaming host for Moonlight.
128+
129+### Requirements
130+
131+- A GPU with a DRM render node (`/dev/dri/renderD*`).
16132 - PipeWire, `xdg-desktop-portal` and `xdg-desktop-portal-gnome`, with the packaged `neferwl-portals.conf` (see [Portals](capture.md#portals)).
17133 - Sunshine with portal capture.
18134
19-## Account setup
135+### Account setup
20136
21137 The user service runs without anyone logged in:
22138
@@ -34,7 +150,7 @@ Log out and back in (or reboot) to apply.
34150
35151 **Security.** Membership in `input` lets every program of that user read every keyboard of the machine: it is the same as a keylogger. NeferWL grabs each device exclusively (`EVIOCGRAB`), so a local keyboard types into the server session, not into a console or another session. A device it cannot grab (another program already holds it) is skipped and logged as `input device skipped`. Use a dedicated account, and never run server mode while a desktop NeferWL session is running on the same machine: `neferwl-server.service` conflicts with `neferwl.service` for that reason.
36152
37-## Configuration
153+### Configuration
38154
39155 `~/.config/neferwl/config`:
40156
@@ -48,16 +164,14 @@ startup = steam -gamepadui
48164
49165 Check it with `neferwl validate-config`. See [Virtual outputs](config.md#virtual-outputs) and [GPUs](config.md#gpus).
50166
51-## Services
167+### Services
52168
53169 ```sh
54170 systemctl --user enable --now neferwl-server.service
55171 systemctl --user enable --now sunshine.service
56172 ```
57173
58-`neferwl-server.service` starts `neferwl --backend=server --session`, notifies systemd when ready, exports `WAYLAND_DISPLAY` and `DISPLAY` to the user manager and restarts on failure. It binds `graphical-session.target`, so Sunshine and the portals start in the right environment.
59-
60-## Sunshine
174+`neferwl-server.service` binds `graphical-session.target`, so Sunshine and the portals start in the right environment.
61175
62176 `~/.config/sunshine/sunshine.conf`:
63177
@@ -71,7 +185,7 @@ To match the client's resolution and refresh rate, change the virtual output's m
71185 global_prep_cmd = [{"do":"sh -c \"wlr-randr --output tv --custom-mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}\"","undo":"wlr-randr --output tv --custom-mode 1920x1080@60"}]
72186 ```
73187
74-## First portal approval
188+### First portal approval
75189
76190 The first time Sunshine captures, the portal shows its share dialog on `tv`, with nobody in front of the screen. Accept it once over SSH:
77191
@@ -83,46 +197,17 @@ ydotool key 28:1 28:0 # Return accepts the selected output
83197
84198 Move the selection with Tab (`15:1 15:0`) if needed, and take another screenshot to check. The portal gives Sunshine a restore token: later streams start without the dialog, as long as the output keeps its name.
85199
86-## HDR
200+### HDR
87201
88202 With `output.tv.hdr = on`, the output is HDR (PQ/BT.2020, reported as a 1000-nit display) and the cast offers 10-bit PQ first. Enable HDR in the Moonlight client and in the game. If the renderer cannot do HDR, the output falls back to SDR and the log says why. See [HDR](config.md#hdr) and [Screen capture](capture.md#portals).
89203
90-## Input
204+### Input
91205
92206 Moonlight's keyboard, mouse and gamepads reach the host through Sunshine's virtual devices. Keyboard and mouse events go through NeferWL to the focused window. Gamepads go straight to games: NeferWL does not handle them.
93207
94208 Steam's controller rules grant access through `uaccess`, which needs a logind seat. Server mode has none, so the `input` group is what gives Steam its gamepads.
95209
96-## Controlling a NeferWL session (agents)
97-
98-An agent or script on the host can watch the session and drive it with standard Wayland tools. Run them as the session user with the session's display:
99-
100-```sh
101-export $(systemctl --user show-environment | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=')
102-grim -o tv /tmp/screen.png # capture one output (see Screen capture)
103-neferwl pointer abs 0.5 0.5 click # click the middle of the layout
104-neferwl pointer move 200 -50 click right # actions run in order
105-wtype 'hello' # type into the focused window
106-neferwl state # windows, focus, outputs as JSON
107-```
108-
109-- `neferwl pointer` actions: `abs X Y` (fractions 0..1 of the layout, or of one output with `--output <name>`), `move DX DY`, `press`/`release`/`click [BTN]`, `hold [BTN] [DURATION]`, `drag DX DY [BTN]` and `scroll up|down|left|right [N]`. BTN is `left` (default), `right`, `middle`, `side`, `extra`, `forward`, `back`, a `BTN_*` name or an evdev code. `--click-duration` (20ms), `--hold-duration` (500ms), `--drag-steps` (10) and `--drag-step-delay` (10ms) tune the timing. Buttons still pressed at exit are released. See `neferwl pointer --help`.
110-- [wlrctl](https://git.sr.ht/~brocellous/wlrctl) (AUR: `wlrctl`) works too: `wlrctl pointer move 200 -50`, `wlrctl pointer click left`.
111-- Both use `zwlr_virtual_pointer_v1`. NeferWL routes their events like a real mouse, so focus, hover and drags behave as they would for a person. Absolute motion maps into the whole layout, or into one output when the tool binds it (`create_virtual_pointer_with_output`).
112-- `ydotool` writes to `/dev/uinput` through `ydotoold` and does not use this protocol; prefer `neferwl pointer`.
113-- Nothing is injected while the session is locked. Buttons a tool still held when it disconnects are released.
114-- Flatpak and other sandboxed clients (those on a `wp_security_context_v1` socket) do not see the virtual pointer global.
115-- `grim` needs the capture allowlist to admit it; see [the allowlist](capture.md#the-allowlist).
116-
117-[wayvnc](https://github.com/any1/wayvnc) works for remote viewing and control: it captures an output with wlr-screencopy and injects input through the virtual pointer and keyboard. Add its executable (`/usr/bin/wayvnc`) to `/etc/neferwl/capture-allow`, then run it in the session:
118-
119-```sh
120-wayvnc -o tv 127.0.0.1 5900
121-```
122-
123-Keep it on localhost and reach it through an SSH tunnel, or configure wayvnc's own authentication and TLS.
124-
125-## Hardening
210+### Hardening
126211
127212 On a dedicated box, a local keyboard should not reboot or reach a console:
128213
@@ -1,22 +1,138 @@
1-# Game server1+# Headless and server mode
2 2
3-`neferwl --backend=server` runs NeferWL without a display: it drives only the virtual outputs declared in the config, reads input devices directly and serves screen casting on the session bus. With [Sunshine](https://github.com/LizardByte/Sunshine), it turns a headless machine into a game streaming host.3+`neferwl --backend=headless` runs the compositor without a screen. Apps connect
4+to its Wayland display as usual and draw into virtual outputs, which you can
5+stream, record or capture. Use it for a game streaming host, a remote desktop
6+box, demo recordings or tests in CI.
4 7
5-Server mode differs from a desktop session:8+## Profiles
6 9
7-- No DRM/KMS and no logind session: no physical output lights up, and no VT is taken.10+| | `ephemeral` (default) | `persistent` |
8-- Virtual outputs are laid out left to right in config order, starting at 0,0. They take the startup focus and every pointer reaches them, so they are not isolated as on a desktop.11+|---|---|---|
9-- The screen-casting and screensaver D-Bus services always run. The logind power-key lock does not.12+| Use | Throwaway sessions: tests, scripts, agents, recordings | A long-running server |
10-- No terminal opens at startup. Scale changes are saved to the config, as on a desktop.13+| Outputs | `--size` heads (`HEADLESS-1`, default 1920x1080); config virtual outputs stay isolated | Virtual outputs from the config |
11-- The test flags (`--screenshot`, `--screenshot-raw`, `--input`, `--size`, `--timeout`, `--headless-hdr`, `--dbus`) are rejected.14+| Input devices | None; input comes from the [control socket](control.md) | Reads `/dev/input/event*` directly |
15+| `--input-devices` | `grab` reads devices too | `none` reads none |
16+| Screen casting and screensaver D-Bus services | Only with `--dbus` | Always |
17+| Scale changes | Not saved | Saved to the config |
18+| Terminal at startup | Opens | None |
19+| GPU | Any Vulkan device | A DRM render node; software rasterizers are refused |
12 20
13-## Requirements21+Both profiles have no DRM/KMS and no logind session: no physical output lights
22+up, no VT is taken and the logind power keys are not handled. Both register a
23+session with a control socket, so [`neferwl -s ID ...`](control.md) works on
24+either. A session ends on `neferwl session rm ID`, on SIGINT or SIGTERM, on the
25+`quit` action, or when `--timeout` runs out (`--ttl` for `session new`).
14 26
15-- A GPU with a DRM render node (`/dev/dri/renderD*`). Software rasterizers such as lavapipe are refused.27+In the persistent profile, virtual outputs are laid out left to right in config
28+order from 0,0. They take the startup focus and every pointer reaches them,
29+unlike virtual outputs on a desktop. `--size` also creates fixed `HEADLESS-N`
30+heads.
31+
32+`--backend=server` is a deprecated alias for
33+`--backend=headless --profile=persistent`.
34+
35+## Run it
36+
37+Declare at least one virtual output in `~/.config/neferwl/config`:
38+
39+```ini
40+output.tv = virtual 1920x1080@60
41+startup = foot
42+```
43+
44+See [Virtual outputs](config.md#virtual-outputs) for modes, HDR and placement.
45+Then start the compositor by hand, for example over SSH:
46+
47+```sh
48+neferwl --backend=headless --profile=persistent --session-id=box
49+```
50+
51+or as the systemd user service:
52+
53+```sh
54+systemctl --user enable --now neferwl-server.service
55+```
56+
57+The service runs `neferwl --backend=headless --profile=persistent --session --session-id=server`.
58+It notifies systemd when ready, exports `WAYLAND_DISPLAY` and `DISPLAY` to the
59+user manager, binds `graphical-session.target` and restarts on failure. It
60+conflicts with `neferwl.service`, so it never runs beside a desktop session.
61+
62+Programs started by the compositor (`startup`, binds, `do spawn`) already have
63+the right environment. To start a client yourself, take the display from the
64+session list or from the user manager:
65+
66+```sh
67+neferwl session ls # WAYLAND column
68+export $(systemctl --user show-environment | grep -E '^(WAYLAND_DISPLAY|DISPLAY|XDG_RUNTIME_DIR)=')
69+firefox &
70+```
71+
72+Logs are in `$XDG_STATE_HOME/neferwl/sessions/<id>/latest.log` with `--session-id`, else in `$XDG_STATE_HOME/neferwl/runs/headless/latest.log`.
73+
74+## Watch and control it
75+
76+- **Streaming and recording**: the screen-casting portal shares each virtual
77+ output with [Sunshine](#game-streaming-with-sunshine), OBS or any PipeWire
78+ client. It needs PipeWire, `xdg-desktop-portal` and
79+ `xdg-desktop-portal-gnome` with the packaged `neferwl-portals.conf`; see
80+ [Portals](capture.md#portals).
81+- **Screenshots**: `neferwl -s server shot --output tv` writes a PNG and prints
82+ its path. `grim -o tv` works too once its executable is in
83+ [the allowlist](capture.md#the-allowlist).
84+- **Remote desktop**: [wayvnc](#wayvnc) gives a VNC view with keyboard and
85+ pointer.
86+- **Scripts and agents**: actions, input, state and captures through the
87+ control socket; see [Scripting and agents](control.md).
88+
89+```sh
90+neferwl -s server state | jq '.windows[] | {id, app_id}'
91+neferwl -s server do focus-workspace-next
92+neferwl -s server key Super+Return --until 'window-mapped app_id=foot'
93+neferwl -s server shot --output tv
94+```
95+
96+### Virtual pointer
97+
98+Tools using `zwlr_virtual_pointer_v1` move the pointer like a real mouse, so
99+focus, hover and drags behave as they would for a person. Run them with the
100+session's `WAYLAND_DISPLAY`:
101+
102+```sh
103+neferwl pointer abs 0.5 0.5 click
104+neferwl pointer move 200 -50 click right
105+```
106+
107+- `neferwl pointer` actions: `abs X Y` (fractions 0..1 of the layout, or of one output with `--output <name>`), `move DX DY`, `press`/`release`/`click [BTN]`, `hold [BTN] [DURATION]`, `drag DX DY [BTN]` and `scroll up|down|left|right [N]`. BTN is `left` (default), `right`, `middle`, `side`, `extra`, `forward`, `back`, a `BTN_*` name or an evdev code. `--click-duration` (20ms), `--hold-duration` (500ms), `--drag-steps` (10) and `--drag-step-delay` (10ms) tune the timing. Buttons still pressed at exit are released. See `neferwl pointer --help`.
108+- [wlrctl](https://git.sr.ht/~brocellous/wlrctl) (AUR: `wlrctl`) works too: `wlrctl pointer move 200 -50`, `wlrctl pointer click left`.
109+- Absolute motion maps into the whole layout, or into one output when the tool binds it (`create_virtual_pointer_with_output`).
110+- `ydotool` writes to `/dev/uinput` through `ydotoold` and does not use this protocol; prefer `neferwl pointer`.
111+- Nothing is injected while the session is locked. Buttons a tool still held when it disconnects are released.
112+- Flatpak and other sandboxed clients (those on a `wp_security_context_v1` socket) do not see the virtual pointer global.
113+
114+### wayvnc
115+
116+[wayvnc](https://github.com/any1/wayvnc) captures an output with wlr-screencopy and injects input through the virtual pointer and keyboard. Add its executable (`/usr/bin/wayvnc`) to `/etc/neferwl/capture-allow`, then run it in the session:
117+
118+```sh
119+wayvnc -o tv 127.0.0.1 5900
120+```
121+
122+Keep it on localhost and reach it through an SSH tunnel, or configure wayvnc's own authentication and TLS.
123+
124+## Game streaming with Sunshine
125+
126+With [Sunshine](https://github.com/LizardByte/Sunshine), a persistent session
127+turns a machine without a screen into a game streaming host for Moonlight.
128+
129+### Requirements
130+
131+- A GPU with a DRM render node (`/dev/dri/renderD*`).
16 - PipeWire, `xdg-desktop-portal` and `xdg-desktop-portal-gnome`, with the packaged `neferwl-portals.conf` (see [Portals](capture.md#portals)).132 - PipeWire, `xdg-desktop-portal` and `xdg-desktop-portal-gnome`, with the packaged `neferwl-portals.conf` (see [Portals](capture.md#portals)).
17 - Sunshine with portal capture.133 - Sunshine with portal capture.
18 134
19-## Account setup135+### Account setup
20 136
21 The user service runs without anyone logged in:137 The user service runs without anyone logged in:
22 138
@@ -34,7 +150,7 @@ Log out and back in (or reboot) to apply.
34 150
35 **Security.** Membership in `input` lets every program of that user read every keyboard of the machine: it is the same as a keylogger. NeferWL grabs each device exclusively (`EVIOCGRAB`), so a local keyboard types into the server session, not into a console or another session. A device it cannot grab (another program already holds it) is skipped and logged as `input device skipped`. Use a dedicated account, and never run server mode while a desktop NeferWL session is running on the same machine: `neferwl-server.service` conflicts with `neferwl.service` for that reason.151 **Security.** Membership in `input` lets every program of that user read every keyboard of the machine: it is the same as a keylogger. NeferWL grabs each device exclusively (`EVIOCGRAB`), so a local keyboard types into the server session, not into a console or another session. A device it cannot grab (another program already holds it) is skipped and logged as `input device skipped`. Use a dedicated account, and never run server mode while a desktop NeferWL session is running on the same machine: `neferwl-server.service` conflicts with `neferwl.service` for that reason.
36 152
37-## Configuration153+### Configuration
38 154
39 `~/.config/neferwl/config`:155 `~/.config/neferwl/config`:
40 156
@@ -48,16 +164,14 @@ startup = steam -gamepadui
48 164
49 Check it with `neferwl validate-config`. See [Virtual outputs](config.md#virtual-outputs) and [GPUs](config.md#gpus).165 Check it with `neferwl validate-config`. See [Virtual outputs](config.md#virtual-outputs) and [GPUs](config.md#gpus).
50 166
51-## Services167+### Services
52 168
53 ```sh169 ```sh
54 systemctl --user enable --now neferwl-server.service170 systemctl --user enable --now neferwl-server.service
55 systemctl --user enable --now sunshine.service171 systemctl --user enable --now sunshine.service
56 ```172 ```
57 173
58-`neferwl-server.service` starts `neferwl --backend=server --session`, notifies systemd when ready, exports `WAYLAND_DISPLAY` and `DISPLAY` to the user manager and restarts on failure. It binds `graphical-session.target`, so Sunshine and the portals start in the right environment.174+`neferwl-server.service` binds `graphical-session.target`, so Sunshine and the portals start in the right environment.
59-
60-## Sunshine
61 175
62 `~/.config/sunshine/sunshine.conf`:176 `~/.config/sunshine/sunshine.conf`:
63 177
@@ -71,7 +185,7 @@ To match the client's resolution and refresh rate, change the virtual output's m
71 global_prep_cmd = [{"do":"sh -c \"wlr-randr --output tv --custom-mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}\"","undo":"wlr-randr --output tv --custom-mode 1920x1080@60"}]185 global_prep_cmd = [{"do":"sh -c \"wlr-randr --output tv --custom-mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}\"","undo":"wlr-randr --output tv --custom-mode 1920x1080@60"}]
72 ```186 ```
73 187
74-## First portal approval188+### First portal approval
75 189
76 The first time Sunshine captures, the portal shows its share dialog on `tv`, with nobody in front of the screen. Accept it once over SSH:190 The first time Sunshine captures, the portal shows its share dialog on `tv`, with nobody in front of the screen. Accept it once over SSH:
77 191
@@ -83,46 +197,17 @@ ydotool key 28:1 28:0 # Return accepts the selected output
83 197
84 Move the selection with Tab (`15:1 15:0`) if needed, and take another screenshot to check. The portal gives Sunshine a restore token: later streams start without the dialog, as long as the output keeps its name.198 Move the selection with Tab (`15:1 15:0`) if needed, and take another screenshot to check. The portal gives Sunshine a restore token: later streams start without the dialog, as long as the output keeps its name.
85 199
86-## HDR200+### HDR
87 201
88 With `output.tv.hdr = on`, the output is HDR (PQ/BT.2020, reported as a 1000-nit display) and the cast offers 10-bit PQ first. Enable HDR in the Moonlight client and in the game. If the renderer cannot do HDR, the output falls back to SDR and the log says why. See [HDR](config.md#hdr) and [Screen capture](capture.md#portals).202 With `output.tv.hdr = on`, the output is HDR (PQ/BT.2020, reported as a 1000-nit display) and the cast offers 10-bit PQ first. Enable HDR in the Moonlight client and in the game. If the renderer cannot do HDR, the output falls back to SDR and the log says why. See [HDR](config.md#hdr) and [Screen capture](capture.md#portals).
89 203
90-## Input204+### Input
91 205
92 Moonlight's keyboard, mouse and gamepads reach the host through Sunshine's virtual devices. Keyboard and mouse events go through NeferWL to the focused window. Gamepads go straight to games: NeferWL does not handle them.206 Moonlight's keyboard, mouse and gamepads reach the host through Sunshine's virtual devices. Keyboard and mouse events go through NeferWL to the focused window. Gamepads go straight to games: NeferWL does not handle them.
93 207
94 Steam's controller rules grant access through `uaccess`, which needs a logind seat. Server mode has none, so the `input` group is what gives Steam its gamepads.208 Steam's controller rules grant access through `uaccess`, which needs a logind seat. Server mode has none, so the `input` group is what gives Steam its gamepads.
95 209
96-## Controlling a NeferWL session (agents)210+### Hardening
97-
98-An agent or script on the host can watch the session and drive it with standard Wayland tools. Run them as the session user with the session's display:
99-
100-```sh
101-export $(systemctl --user show-environment | grep -E '^(WAYLAND_DISPLAY|XDG_RUNTIME_DIR)=')
102-grim -o tv /tmp/screen.png # capture one output (see Screen capture)
103-neferwl pointer abs 0.5 0.5 click # click the middle of the layout
104-neferwl pointer move 200 -50 click right # actions run in order
105-wtype 'hello' # type into the focused window
106-neferwl state # windows, focus, outputs as JSON
107-```
108-
109-- `neferwl pointer` actions: `abs X Y` (fractions 0..1 of the layout, or of one output with `--output <name>`), `move DX DY`, `press`/`release`/`click [BTN]`, `hold [BTN] [DURATION]`, `drag DX DY [BTN]` and `scroll up|down|left|right [N]`. BTN is `left` (default), `right`, `middle`, `side`, `extra`, `forward`, `back`, a `BTN_*` name or an evdev code. `--click-duration` (20ms), `--hold-duration` (500ms), `--drag-steps` (10) and `--drag-step-delay` (10ms) tune the timing. Buttons still pressed at exit are released. See `neferwl pointer --help`.
110-- [wlrctl](https://git.sr.ht/~brocellous/wlrctl) (AUR: `wlrctl`) works too: `wlrctl pointer move 200 -50`, `wlrctl pointer click left`.
111-- Both use `zwlr_virtual_pointer_v1`. NeferWL routes their events like a real mouse, so focus, hover and drags behave as they would for a person. Absolute motion maps into the whole layout, or into one output when the tool binds it (`create_virtual_pointer_with_output`).
112-- `ydotool` writes to `/dev/uinput` through `ydotoold` and does not use this protocol; prefer `neferwl pointer`.
113-- Nothing is injected while the session is locked. Buttons a tool still held when it disconnects are released.
114-- Flatpak and other sandboxed clients (those on a `wp_security_context_v1` socket) do not see the virtual pointer global.
115-- `grim` needs the capture allowlist to admit it; see [the allowlist](capture.md#the-allowlist).
116-
117-[wayvnc](https://github.com/any1/wayvnc) works for remote viewing and control: it captures an output with wlr-screencopy and injects input through the virtual pointer and keyboard. Add its executable (`/usr/bin/wayvnc`) to `/etc/neferwl/capture-allow`, then run it in the session:
118-
119-```sh
120-wayvnc -o tv 127.0.0.1 5900
121-```
122-
123-Keep it on localhost and reach it through an SSH tunnel, or configure wayvnc's own authentication and TLS.
124-
125-## Hardening
126 211
127 On a dedicated box, a local keyboard should not reboot or reach a console:212 On a dedicated box, a local keyboard should not reboot or reach a console:
128 213
M domainpolicy_test.go +1 -1
@@ -170,7 +170,7 @@ func TestAdapterImports(t *testing.T) {
170170 const adapters = base + "internal/adapters/"
171171 // Keep the shared-library allowlist here, not in the build-tag-sensitive
172172 // go list output. All other cross-adapter dependencies must use ports.
173- libraries := strings.Fields("drm config sched seat watchdog fdwait busretry overlaydraw outputkit/routing outputkit/cursors outputkit/virtuals outputkit/headlessbackend xcursor outputkit/capture outputkit/corewake outputkit/presented outputkit/surfaces captureallow clock hdrcursor logging peerexe sessionsecurity syncfile workspaceid xkb")
173+ libraries := strings.Fields("drm config sched seat watchdog fdwait busretry overlaydraw outputkit/routing outputkit/cursors outputkit/virtuals outputkit/headlessbackend xcursor outputkit/capture outputkit/corewake outputkit/presented outputkit/surfaces captureallow clock hdrcursor logging peerexe sessionsecurity syncfile statewire workspaceid xkb")
174174 err := filepath.WalkDir("internal/adapters", func(dir string, entry fs.DirEntry, err error) error {
175175 if err != nil {
176176 return err
@@ -170,7 +170,7 @@ func TestAdapterImports(t *testing.T) {
170 const adapters = base + "internal/adapters/"170 const adapters = base + "internal/adapters/"
171 // Keep the shared-library allowlist here, not in the build-tag-sensitive171 // Keep the shared-library allowlist here, not in the build-tag-sensitive
172 // go list output. All other cross-adapter dependencies must use ports.172 // go list output. All other cross-adapter dependencies must use ports.
173- libraries := strings.Fields("drm config sched seat watchdog fdwait busretry overlaydraw outputkit/routing outputkit/cursors outputkit/virtuals outputkit/headlessbackend xcursor outputkit/capture outputkit/corewake outputkit/presented outputkit/surfaces captureallow clock hdrcursor logging peerexe sessionsecurity syncfile workspaceid xkb")173+ libraries := strings.Fields("drm config sched seat watchdog fdwait busretry overlaydraw outputkit/routing outputkit/cursors outputkit/virtuals outputkit/headlessbackend xcursor outputkit/capture outputkit/corewake outputkit/presented outputkit/surfaces captureallow clock hdrcursor logging peerexe sessionsecurity syncfile statewire workspaceid xkb")
174 err := filepath.WalkDir("internal/adapters", func(dir string, entry fs.DirEntry, err error) error {174 err := filepath.WalkDir("internal/adapters", func(dir string, entry fs.DirEntry, err error) error {
175 if err != nil {175 if err != nil {
176 return err176 return err
A internal/adapters/config/catalog_test.go +48 -0
@@ -0,0 +1,48 @@
1+package config
2+
3+import (
4+ "testing"
5+
6+ "github.com/bnema/neferwl/internal/domain"
7+)
8+
9+func TestCatalogBindActions(t *testing.T) {
10+ args := map[string]string{
11+ "focus-workspace": "2",
12+ "move-column-to-workspace": "2",
13+ "move-window-to-workspace": "2",
14+ "workspace": "dev",
15+ "spawn": "foot --app-id=terminal",
16+ "stash": "foot",
17+ "set-column-width": "+1",
18+ "set-window-height": "-10%",
19+ }
20+ for _, spec := range domain.Commands() {
21+ t.Run(spec.Name, func(t *testing.T) {
22+ text := spec.Name
23+ action := spec.Kind == domain.CommandAction || spec.Kind == domain.CommandActionArg
24+ if spec.Kind == domain.CommandActionArg {
25+ arg, ok := args[spec.Name]
26+ if !ok {
27+ t.Fatalf("add a valid argument fixture for %s", spec.Name)
28+ }
29+ text += " " + arg
30+ if err := checkAction(spec.Name); err == nil {
31+ t.Error("bare argument action accepted")
32+ }
33+ }
34+ err := checkAction(text)
35+ if action && err != nil {
36+ t.Errorf("action rejected: %v", err)
37+ }
38+ if !action && err == nil {
39+ t.Error("non-action accepted as bind")
40+ }
41+ })
42+ }
43+ for _, text := range []string{"state extra", "key Super+x", "type hello", "pointer 1 2", "swipe down", "shot DP-1", "output-add 1920x1080@60", "output-rm HEADLESS-2"} {
44+ if err := checkAction(text); err == nil {
45+ t.Errorf("non-action %q accepted", text)
46+ }
47+ }
48+}
@@ -0,0 +1,48 @@
1+package config
2+
3+import (
4+ "testing"
5+
6+ "github.com/bnema/neferwl/internal/domain"
7+)
8+
9+func TestCatalogBindActions(t *testing.T) {
10+ args := map[string]string{
11+ "focus-workspace": "2",
12+ "move-column-to-workspace": "2",
13+ "move-window-to-workspace": "2",
14+ "workspace": "dev",
15+ "spawn": "foot --app-id=terminal",
16+ "stash": "foot",
17+ "set-column-width": "+1",
18+ "set-window-height": "-10%",
19+ }
20+ for _, spec := range domain.Commands() {
21+ t.Run(spec.Name, func(t *testing.T) {
22+ text := spec.Name
23+ action := spec.Kind == domain.CommandAction || spec.Kind == domain.CommandActionArg
24+ if spec.Kind == domain.CommandActionArg {
25+ arg, ok := args[spec.Name]
26+ if !ok {
27+ t.Fatalf("add a valid argument fixture for %s", spec.Name)
28+ }
29+ text += " " + arg
30+ if err := checkAction(spec.Name); err == nil {
31+ t.Error("bare argument action accepted")
32+ }
33+ }
34+ err := checkAction(text)
35+ if action && err != nil {
36+ t.Errorf("action rejected: %v", err)
37+ }
38+ if !action && err == nil {
39+ t.Error("non-action accepted as bind")
40+ }
41+ })
42+ }
43+ for _, text := range []string{"state extra", "key Super+x", "type hello", "pointer 1 2", "swipe down", "shot DP-1", "output-add 1920x1080@60", "output-rm HEADLESS-2"} {
44+ if err := checkAction(text); err == nil {
45+ t.Errorf("non-action %q accepted", text)
46+ }
47+ }
48+}
M internal/adapters/config/config.go +11 -59
@@ -22,6 +22,7 @@ import (
2222 "unicode/utf8"
2323
2424 "bnema.dev/kvconf"
25+ "github.com/bnema/neferwl/internal/adapters/logging"
2526 "github.com/bnema/neferwl/internal/domain"
2627 )
2728
@@ -74,52 +75,6 @@ var defaultBinds = []struct{ combo, action string }{
7475 {"cmd+ctrl+shift+down", "move-workspace-next"},
7576 {"cmd+shift+space", "toggle-floating"},
7677 }
77-var actions = map[string]bool{
78- "focus-monitor-left": true,
79- "focus-monitor-right": true,
80- "move-workspace-to-monitor-left": true,
81- "move-workspace-to-monitor-right": true,
82- "focus-monitor-up": true,
83- "focus-monitor-down": true,
84- "move-workspace-to-monitor-up": true,
85- "move-workspace-to-monitor-down": true,
86- "scale-up": true,
87- "scale-down": true,
88- "focus-workspace-prev": true,
89- "focus-workspace-next": true,
90- "move-column-to-workspace-prev": true,
91- "move-column-to-workspace-next": true,
92- "move-window-to-workspace-prev": true,
93- "move-window-to-workspace-next": true,
94- "none": true,
95- "consume-or-expel-window-left": true,
96- "consume-or-expel-window-right": true,
97- "spawn-terminal": true,
98- "focus-column-left": true,
99- "focus-column-right": true,
100- "focus-window-up": true,
101- "focus-window-down": true,
102- "move-column-left": true,
103- "move-column-right": true,
104- "cycle-column-width": true,
105- "maximize-column": true,
106- "toggle-fullscreen": true,
107- "toggle-window-stash": true,
108- "toggle-stash-visible": true,
109- "toggle-overview": true,
110- "switch-column-next": true,
111- "switch-column-prev": true,
112- "close-window": true,
113- "quit": true,
114- "move-window-up": true,
115- "move-window-down": true,
116- "move-workspace-prev": true,
117- "move-workspace-next": true,
118- "toggle-floating": true,
119- "hint": true,
120- "osd-pin": true,
121-}
122-var components = map[string]bool{"core": true, "wayland": true, "input": true, "drm": true, "seat": true, "render": true, "sync": true, "config": true, "app": true, "hints": true}
12378 var color = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)
12479
12580 // columnStep is the +N or -N step of set-column-width, in cells, N from 1
@@ -585,13 +540,8 @@ func parseBytes(data []byte) (domain.Config, map[string]string, []Warning, error
585540 warn("%s: expected virtual WxH[@Hz]", key)
586541 continue
587542 }
588- w, h, hz, err := ParseMode(fields[1])
589- if hz == 0 {
590- hz = 60
591- }
592- _, representable := domain.RefreshMilli(hz)
593- if err != nil || w < 1 || h < 1 || w > 16384 || h > 16384 || !representable {
594- warn("%s: virtual mode must be WxH[@Hz], dimensions 1..16384 and rounded refresh 1..2147483647 mHz", key)
543+ if _, err := domain.ParseOutputMode(fields[1]); err != nil {
544+ warn("%s: virtual %v", key, err)
595545 continue
596546 }
597547 o.Virtual, o.Mode = true, fields[1]
@@ -1176,11 +1126,10 @@ func set(c *domain.Config, key, v string) error {
11761126 }
11771127 c.Log.Level = v
11781128 case "log.debug":
1129+ // The logger owns the component and category names.
11791130 list := splitList(v)
1180- for _, s := range list {
1181- if !components[s] && s != "all" {
1182- return fmt.Errorf("unknown component %q", s)
1183- }
1131+ if _, err := logging.ParseDebug(strings.Join(list, ",")); err != nil {
1132+ return err
11841133 }
11851134 c.Log.Debug = list
11861135 default:
@@ -1558,11 +1507,14 @@ func checkAction(v string) error {
15581507 return nil
15591508 }
15601509 for old, repl := range map[string]string{"-workspace-up": "-workspace-prev", "-workspace-down": "-workspace-next"} {
1561- if base, ok := strings.CutSuffix(v, old); ok && actions[base+repl] {
1510+ if base, ok := strings.CutSuffix(v, old); ok {
1511+ if spec, found := domain.LookupCommand(base + repl); !found || spec.Kind != domain.CommandAction {
1512+ continue
1513+ }
15621514 return fmt.Errorf("action %q was renamed to %q", v, base+repl)
15631515 }
15641516 }
1565- if !actions[v] {
1517+ if spec, ok := domain.LookupCommand(v); !ok || spec.Kind != domain.CommandAction {
15661518 return fmt.Errorf(`unknown action %q (or "spawn <command>", "stash <command>", "workspace <name>")`, v)
15671519 }
15681520 return nil
@@ -22,6 +22,7 @@ import (
22 "unicode/utf8"22 "unicode/utf8"
23 23
24 "bnema.dev/kvconf"24 "bnema.dev/kvconf"
25+ "github.com/bnema/neferwl/internal/adapters/logging"
25 "github.com/bnema/neferwl/internal/domain"26 "github.com/bnema/neferwl/internal/domain"
26 )27 )
27 28
@@ -74,52 +75,6 @@ var defaultBinds = []struct{ combo, action string }{
74 {"cmd+ctrl+shift+down", "move-workspace-next"},75 {"cmd+ctrl+shift+down", "move-workspace-next"},
75 {"cmd+shift+space", "toggle-floating"},76 {"cmd+shift+space", "toggle-floating"},
76 }77 }
77-var actions = map[string]bool{
78- "focus-monitor-left": true,
79- "focus-monitor-right": true,
80- "move-workspace-to-monitor-left": true,
81- "move-workspace-to-monitor-right": true,
82- "focus-monitor-up": true,
83- "focus-monitor-down": true,
84- "move-workspace-to-monitor-up": true,
85- "move-workspace-to-monitor-down": true,
86- "scale-up": true,
87- "scale-down": true,
88- "focus-workspace-prev": true,
89- "focus-workspace-next": true,
90- "move-column-to-workspace-prev": true,
91- "move-column-to-workspace-next": true,
92- "move-window-to-workspace-prev": true,
93- "move-window-to-workspace-next": true,
94- "none": true,
95- "consume-or-expel-window-left": true,
96- "consume-or-expel-window-right": true,
97- "spawn-terminal": true,
98- "focus-column-left": true,
99- "focus-column-right": true,
100- "focus-window-up": true,
101- "focus-window-down": true,
102- "move-column-left": true,
103- "move-column-right": true,
104- "cycle-column-width": true,
105- "maximize-column": true,
106- "toggle-fullscreen": true,
107- "toggle-window-stash": true,
108- "toggle-stash-visible": true,
109- "toggle-overview": true,
110- "switch-column-next": true,
111- "switch-column-prev": true,
112- "close-window": true,
113- "quit": true,
114- "move-window-up": true,
115- "move-window-down": true,
116- "move-workspace-prev": true,
117- "move-workspace-next": true,
118- "toggle-floating": true,
119- "hint": true,
120- "osd-pin": true,
121-}
122-var components = map[string]bool{"core": true, "wayland": true, "input": true, "drm": true, "seat": true, "render": true, "sync": true, "config": true, "app": true, "hints": true}
123 var color = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)78 var color = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)
124 79
125 // columnStep is the +N or -N step of set-column-width, in cells, N from 180 // columnStep is the +N or -N step of set-column-width, in cells, N from 1
@@ -585,13 +540,8 @@ func parseBytes(data []byte) (domain.Config, map[string]string, []Warning, error
585 warn("%s: expected virtual WxH[@Hz]", key)540 warn("%s: expected virtual WxH[@Hz]", key)
586 continue541 continue
587 }542 }
588- w, h, hz, err := ParseMode(fields[1])543+ if _, err := domain.ParseOutputMode(fields[1]); err != nil {
589- if hz == 0 {544+ warn("%s: virtual %v", key, err)
590- hz = 60
591- }
592- _, representable := domain.RefreshMilli(hz)
593- if err != nil || w < 1 || h < 1 || w > 16384 || h > 16384 || !representable {
594- warn("%s: virtual mode must be WxH[@Hz], dimensions 1..16384 and rounded refresh 1..2147483647 mHz", key)
595 continue545 continue
596 }546 }
597 o.Virtual, o.Mode = true, fields[1]547 o.Virtual, o.Mode = true, fields[1]
@@ -1176,11 +1126,10 @@ func set(c *domain.Config, key, v string) error {
1176 }1126 }
1177 c.Log.Level = v1127 c.Log.Level = v
1178 case "log.debug":1128 case "log.debug":
1129+ // The logger owns the component and category names.
1179 list := splitList(v)1130 list := splitList(v)
1180- for _, s := range list {1131+ if _, err := logging.ParseDebug(strings.Join(list, ",")); err != nil {
1181- if !components[s] && s != "all" {1132+ return err
1182- return fmt.Errorf("unknown component %q", s)
1183- }
1184 }1133 }
1185 c.Log.Debug = list1134 c.Log.Debug = list
1186 default:1135 default:
@@ -1558,11 +1507,14 @@ func checkAction(v string) error {
1558 return nil1507 return nil
1559 }1508 }
1560 for old, repl := range map[string]string{"-workspace-up": "-workspace-prev", "-workspace-down": "-workspace-next"} {1509 for old, repl := range map[string]string{"-workspace-up": "-workspace-prev", "-workspace-down": "-workspace-next"} {
1561- if base, ok := strings.CutSuffix(v, old); ok && actions[base+repl] {1510+ if base, ok := strings.CutSuffix(v, old); ok {
1511+ if spec, found := domain.LookupCommand(base + repl); !found || spec.Kind != domain.CommandAction {
1512+ continue
1513+ }
1562 return fmt.Errorf("action %q was renamed to %q", v, base+repl)1514 return fmt.Errorf("action %q was renamed to %q", v, base+repl)
1563 }1515 }
1564 }1516 }
1565- if !actions[v] {1517+ if spec, ok := domain.LookupCommand(v); !ok || spec.Kind != domain.CommandAction {
1566 return fmt.Errorf(`unknown action %q (or "spawn <command>", "stash <command>", "workspace <name>")`, v)1518 return fmt.Errorf(`unknown action %q (or "spawn <command>", "stash <command>", "workspace <name>")`, v)
1567 }1519 }
1568 return nil1520 return nil
M internal/adapters/config/config_test.go +10 -0
@@ -1277,3 +1277,13 @@ func TestLineageShells(t *testing.T) {
12771277 t.Fatal("shell reload compares equal")
12781278 }
12791279 }
1280+
1281+// TestLogDebugNames: log.debug accepts every logger component and category.
1282+func TestLogDebugNames(t *testing.T) {
1283+ for _, v := range []string{"control", "screensaver, powerkey", "sched,screencast", "input-motion", "all"} {
1284+ c, w := parseString(t, "log.debug = "+v)
1285+ if len(w) != 0 || len(c.Log.Debug) == 0 {
1286+ t.Errorf("%q: debug %v warnings %v", v, c.Log.Debug, w)
1287+ }
1288+ }
1289+}
@@ -1277,3 +1277,13 @@ func TestLineageShells(t *testing.T) {
1277 t.Fatal("shell reload compares equal")1277 t.Fatal("shell reload compares equal")
1278 }1278 }
1279 }1279 }
1280+
1281+// TestLogDebugNames: log.debug accepts every logger component and category.
1282+func TestLogDebugNames(t *testing.T) {
1283+ for _, v := range []string{"control", "screensaver, powerkey", "sched,screencast", "input-motion", "all"} {
1284+ c, w := parseString(t, "log.debug = "+v)
1285+ if len(w) != 0 || len(c.Log.Debug) == 0 {
1286+ t.Errorf("%q: debug %v warnings %v", v, c.Log.Debug, w)
1287+ }
1288+ }
1289+}
A internal/adapters/control/continuous_test.go +36 -0
@@ -0,0 +1,36 @@
1+package control
2+
3+import (
4+ "context"
5+ "testing"
6+ "testing/synctest"
7+
8+ "github.com/bnema/neferwl/internal/domain"
9+ "github.com/bnema/neferwl/internal/ports"
10+)
11+
12+// Every-frame capture goes to core as a ControlCapture: the adapter only
13+// supplies the default directory and relays core's (or the backend's) reply.
14+func TestContinuousDispatch(t *testing.T) {
15+ synctest.Test(t, func(t *testing.T) {
16+ s := &Server{framesDir: "/session/shots/frames"}
17+ out := make(chan ports.ControlRequest)
18+ for _, tc := range []struct {
19+ stop bool
20+ code string
21+ }{{false, ""}, {true, ""}, {false, ports.ControlErrLocked}} {
22+ go func() {
23+ r := (<-out).(ports.ControlCapture)
24+ if r.Dir != s.framesDir || r.Stop != tc.stop || r.Caps != domain.CapsAll || cap(r.Reply) != 1 {
25+ t.Error(r)
26+ }
27+ r.Reply <- ports.ContinuousCaptureResult{Dir: r.Dir, Err: tc.code}
28+ }()
29+ announced := false
30+ got := s.dispatch(context.Background(), request{Op: "shot", EveryFrame: !tc.stop, Stop: tc.stop}, out, &announced)
31+ if got.OK != (tc.code == "") || got.Error != tc.code || got.Dir != s.framesDir {
32+ t.Fatal(got)
33+ }
34+ }
35+ })
36+}
@@ -0,0 +1,36 @@
1+package control
2+
3+import (
4+ "context"
5+ "testing"
6+ "testing/synctest"
7+
8+ "github.com/bnema/neferwl/internal/domain"
9+ "github.com/bnema/neferwl/internal/ports"
10+)
11+
12+// Every-frame capture goes to core as a ControlCapture: the adapter only
13+// supplies the default directory and relays core's (or the backend's) reply.
14+func TestContinuousDispatch(t *testing.T) {
15+ synctest.Test(t, func(t *testing.T) {
16+ s := &Server{framesDir: "/session/shots/frames"}
17+ out := make(chan ports.ControlRequest)
18+ for _, tc := range []struct {
19+ stop bool
20+ code string
21+ }{{false, ""}, {true, ""}, {false, ports.ControlErrLocked}} {
22+ go func() {
23+ r := (<-out).(ports.ControlCapture)
24+ if r.Dir != s.framesDir || r.Stop != tc.stop || r.Caps != domain.CapsAll || cap(r.Reply) != 1 {
25+ t.Error(r)
26+ }
27+ r.Reply <- ports.ContinuousCaptureResult{Dir: r.Dir, Err: tc.code}
28+ }()
29+ announced := false
30+ got := s.dispatch(context.Background(), request{Op: "shot", EveryFrame: !tc.stop, Stop: tc.stop}, out, &announced)
31+ if got.OK != (tc.code == "") || got.Error != tc.code || got.Dir != s.framesDir {
32+ t.Fatal(got)
33+ }
34+ }
35+ })
36+}
A internal/adapters/control/control.go +456 -0
@@ -0,0 +1,456 @@
1+// Package control serves the v1 JSON-lines control protocol on a Unix socket.
2+package control
3+
4+import (
5+ "bufio"
6+ "context"
7+ "encoding/json"
8+ "errors"
9+ "fmt"
10+ "net"
11+ "os"
12+ "path/filepath"
13+ "sync"
14+ "syscall"
15+ "time"
16+
17+ "github.com/bnema/neferwl/internal/adapters/logging"
18+ "github.com/bnema/neferwl/internal/adapters/statewire"
19+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
20+ "github.com/bnema/neferwl/internal/adapters/xkb"
21+ "github.com/bnema/neferwl/internal/domain"
22+ "github.com/bnema/neferwl/internal/ports"
23+ "golang.org/x/sys/unix"
24+)
25+
26+// Server owns a control listener. Requests on each connection are processed in
27+// order: the next line is read only after the preceding core reply is sent.
28+// Options supplies a dedicated control keymap, never the physical input map.
29+// Listen takes ownership of Keymap on success. The server takes ownership of
30+// each map it receives from Keymaps; producers own any maps left in the channel
31+// after shutdown. Security is sampled before every translated event.
32+type Options struct {
33+ FramesDir string
34+ Shooter *Shooter
35+ Keymap *xkb.Keymap
36+ Keymaps <-chan *xkb.Keymap
37+ Security ports.SessionSecurity
38+}
39+
40+type Server struct {
41+ framesDir string
42+ shooter *Shooter
43+ injectMu sync.Mutex
44+ injector *injector
45+ keymaps <-chan *xkb.Keymap
46+ listener *net.UnixListener
47+ ids *workspaceid.IDs
48+ done chan struct{}
49+ once sync.Once
50+ err error
51+}
52+
53+// Listen creates a private socket using the same workspace IDs as statefile.
54+// An existing socket is removed only when connecting proves it has no listener.
55+func Listen(path string, ids *workspaceid.IDs, opts Options) (*Server, error) {
56+ if ids == nil {
57+ return nil, errors.New("workspace IDs are required")
58+ }
59+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
60+ return nil, err
61+ }
62+ if info, err := os.Lstat(path); err == nil {
63+ if info.Mode()&os.ModeSocket == 0 {
64+ return nil, fmt.Errorf("control path is not a socket: %s", path)
65+ }
66+ conn, err := net.DialTimeout("unix", path, time.Second)
67+ if err == nil {
68+ conn.Close()
69+ return nil, fmt.Errorf("control socket already listening: %s", path)
70+ }
71+ if !errors.Is(err, syscall.ECONNREFUSED) {
72+ return nil, err
73+ }
74+ if err := os.Remove(path); err != nil {
75+ return nil, err
76+ }
77+ } else if !errors.Is(err, os.ErrNotExist) {
78+ return nil, err
79+ }
80+ listener, err := net.ListenUnix("unix", &net.UnixAddr{Name: path, Net: "unix"})
81+ if err != nil {
82+ return nil, err
83+ }
84+ if err := os.Chmod(path, 0o600); err != nil {
85+ listener.Close()
86+ return nil, err
87+ }
88+ s := &Server{listener: listener, ids: ids, done: make(chan struct{})}
89+ s.framesDir = opts.FramesDir
90+ s.shooter = opts.Shooter
91+ s.keymaps = opts.Keymaps
92+ if opts.Keymap != nil {
93+ s.injector = newInjector(opts.Keymap, opts.Security)
94+ }
95+ return s, nil
96+}
97+
98+// Close stops acceptance and all active connections. It is safe to call twice.
99+func (s *Server) Close() error {
100+ s.once.Do(func() {
101+ close(s.done)
102+ s.err = s.listener.Close()
103+ s.injectMu.Lock()
104+ defer s.injectMu.Unlock()
105+ if s.injector != nil {
106+ s.injector.km.Close()
107+ s.injector = nil
108+ }
109+ })
110+ return s.err
111+}
112+
113+// Run accepts connections until cancellation or Close, waiting for handlers to exit.
114+func (s *Server) Run(ctx context.Context, out chan<- ports.ControlRequest) error {
115+ ctx, cancel := context.WithCancel(ctx)
116+ stop := context.AfterFunc(ctx, func() { _ = s.Close() })
117+ defer stop()
118+ var workers sync.WaitGroup
119+ defer workers.Wait()
120+ defer cancel()
121+ log := logging.For(ctx, "control")
122+ log.Info().Str("path", s.listener.Addr().String()).Msg("listening")
123+ for {
124+ conn, err := s.listener.AcceptUnix()
125+ if err != nil {
126+ if ctx.Err() != nil || errors.Is(err, net.ErrClosed) {
127+ return nil
128+ }
129+ return err
130+ }
131+ workers.Add(1)
132+ go func() {
133+ defer workers.Done()
134+ defer conn.Close()
135+ connCtx, cancel := context.WithCancel(ctx)
136+ defer cancel()
137+ go func() {
138+ select {
139+ case <-s.done:
140+ cancel()
141+ case <-connCtx.Done():
142+ }
143+ }()
144+ stop := context.AfterFunc(connCtx, func() { _ = conn.Close() })
145+ defer stop()
146+ if !sameUID(conn) {
147+ log.Warn().Msg("peer rejected")
148+ return
149+ }
150+ s.serve(connCtx, conn, out)
151+ }()
152+ }
153+}
154+
155+func sameUID(conn *net.UnixConn) bool {
156+ raw, err := conn.SyscallConn()
157+ if err != nil {
158+ return false
159+ }
160+ var cred *unix.Ucred
161+ var credErr error
162+ if err := raw.Control(func(fd uintptr) { cred, credErr = unix.GetsockoptUcred(int(fd), unix.SOL_SOCKET, unix.SO_PEERCRED) }); err != nil {
163+ return false
164+ }
165+ return credErr == nil && cred != nil && cred.Uid == uint32(os.Getuid())
166+}
167+
168+type request struct {
169+ EveryFrame bool `json:"every_frame"`
170+ Stop bool `json:"stop"`
171+ Name string `json:"name"`
172+ Mode string `json:"mode"`
173+ Outputs []string `json:"outputs"`
174+ Inline bool `json:"inline"`
175+ Raw bool `json:"raw"`
176+ Shot json.RawMessage `json:"shot"`
177+ ID json.RawMessage `json:"id"`
178+ Op string `json:"op"`
179+ Action string `json:"action"`
180+ What string `json:"what"`
181+ Wait *string `json:"wait"`
182+ Until *string `json:"until"`
183+ Timeout *string `json:"timeout"`
184+ Kind string `json:"kind"`
185+ Combo string `json:"combo"`
186+ Text string `json:"text"`
187+ Cmd string `json:"cmd"`
188+ Args []string `json:"args"`
189+ Fingers int `json:"fingers"`
190+ Dir string `json:"dir"`
191+}
192+
193+type reply struct {
194+ Dir string `json:"dir,omitempty"`
195+ Shots []Shot `json:"shots,omitempty"`
196+ Detail string `json:"detail,omitempty"`
197+ ID json.RawMessage `json:"id"`
198+ OK bool `json:"ok"`
199+ Done string `json:"done"`
200+ Diff diff `json:"diff"`
201+ State statewire.State `json:"state"`
202+ Late []domain.WindowID `json:"late"`
203+ Error string `json:"error,omitempty"`
204+}
205+
206+type command struct {
207+ Name string `json:"name"`
208+ Arg string `json:"arg"`
209+ Kind string `json:"kind"`
210+ Caps []string `json:"caps"`
211+ Summary string `json:"summary"`
212+}
213+
214+func capNames(c domain.Caps) []string {
215+ names := []string{}
216+ for _, item := range []struct {
217+ bit domain.Caps
218+ name string
219+ }{{domain.CapRead, "read"}, {domain.CapAct, "act"}, {domain.CapInput, "input"}, {domain.CapCapture, "capture"}, {domain.CapAdmin, "admin"}} {
220+ if c&item.bit != 0 {
221+ names = append(names, item.name)
222+ }
223+ }
224+ return names
225+}
226+
227+var nullID = json.RawMessage("null")
228+
229+// maxRequestTimeout caps the client-supplied timeout: core and the shooter
230+// hold a request at most this long.
231+const maxRequestTimeout = domain.MaxControlTimeout
232+
233+func (s *Server) serve(ctx context.Context, conn *net.UnixConn, out chan<- ports.ControlRequest) {
234+ scanner := bufio.NewScanner(conn)
235+ scanner.Buffer(make([]byte, 4096), 1024*1024)
236+ encoder := json.NewEncoder(conn)
237+ announced := false
238+ for scanner.Scan() {
239+ var req request
240+ if err := json.Unmarshal(scanner.Bytes(), &req); err != nil {
241+ if encoder.Encode(reply{ID: nullID, Error: ports.ControlErrBadRequest}) != nil {
242+ return
243+ }
244+ continue
245+ }
246+ // The id is optional: a request without one gets "id": null back.
247+ if len(req.ID) == 0 {
248+ req.ID = nullID
249+ }
250+ if req.Op == "hello" {
251+ commands := []command{}
252+ for _, spec := range domain.Commands() {
253+ commands = append(commands, command{spec.Name, spec.Arg, spec.Kind.String(), capNames(spec.Caps), spec.Summary})
254+ }
255+ if encoder.Encode(struct {
256+ ID json.RawMessage `json:"id"`
257+ OK bool `json:"ok"`
258+ V int `json:"v"`
259+ Caps []string `json:"caps"`
260+ Commands []command `json:"commands"`
261+ }{req.ID, true, 1, capNames(domain.CapsAll), commands}) != nil {
262+ return
263+ }
264+ continue
265+ }
266+ response := s.dispatch(ctx, req, out, &announced)
267+ if ctx.Err() != nil {
268+ return
269+ }
270+ if encoder.Encode(response) != nil {
271+ return
272+ }
273+ }
274+}
275+
276+func (s *Server) dispatch(ctx context.Context, req request, out chan<- ports.ControlRequest, announced *bool) reply {
277+ // The request deadline covers the core wait and the capture together.
278+ start := time.Now()
279+ response := reply{ID: req.ID, Error: ports.ControlErrBadRequest}
280+ if req.Op == "shot" && (req.EveryFrame || req.Stop) {
281+ return s.continuousCapture(ctx, req, out)
282+ }
283+ ch := make(chan ports.ControlReply, 1)
284+ var message ports.ControlRequest
285+ timeout := domain.DefaultControlTimeout
286+ switch req.Op {
287+ case "output-add", "output-rm":
288+ mode := domain.OutputMode{}
289+ if req.Op == "output-add" {
290+ var err error
291+ mode, err = domain.ParseOutputMode(req.Mode)
292+ if err != nil {
293+ return response
294+ }
295+ } else if req.Name == "" {
296+ return response
297+ }
298+ message = ports.ControlOutput{Name: req.Name, Mode: mode, Remove: req.Op == "output-rm", Caps: domain.CapsAll, Reply: ch}
299+
300+ case "do", "inject", "shot":
301+ shots, err := requestShots(req)
302+ if err != nil {
303+ response.Detail = err.Error()
304+ return response
305+ }
306+ if len(shots) > 0 && s.shooter == nil {
307+ response.Detail = "capture unavailable"
308+ return response
309+ }
310+ wait := domain.DefaultWait
311+ if req.Wait != nil {
312+ var err error
313+ wait, err = domain.ParseWaitLevel(*req.Wait)
314+ if err != nil {
315+ return response
316+ }
317+ }
318+ var until *domain.Until
319+ if req.Until != nil {
320+ parsed, err := domain.ParseUntil(*req.Until)
321+ if err != nil {
322+ return response
323+ }
324+ until = &parsed
325+ }
326+ if req.Timeout != nil {
327+ var err error
328+ timeout, err = time.ParseDuration(*req.Timeout)
329+ if err != nil || timeout <= 0 {
330+ return response
331+ }
332+ if timeout > maxRequestTimeout {
333+ response.Detail = "timeout exceeds 5m"
334+ return response
335+ }
336+ }
337+ if len(shots) > 0 {
338+ wait = domain.WaitPresented
339+ }
340+ if req.Op == "inject" {
341+ events, err := s.translate(req, !*announced)
342+ if err != nil {
343+ return response
344+ }
345+ message = ports.ControlInject{Shots: shots, Events: events, Wait: wait, Until: until, Timeout: timeout, Caps: domain.CapsAll, Reply: ch}
346+ } else {
347+ if req.Op == "shot" {
348+ req.Action = "none"
349+ }
350+ if req.Action == "" {
351+ return response
352+ }
353+ message = ports.ControlDo{Shots: shots, Action: req.Action, Wait: wait, Until: until, Timeout: timeout, Caps: domain.CapsAll, Reply: ch}
354+ }
355+ case "query":
356+ if req.What == "" {
357+ return response
358+ }
359+ message = ports.ControlQuery{What: req.What, Caps: domain.CapsAll, Reply: ch}
360+ default:
361+ return response
362+ }
363+ select {
364+ case out <- message:
365+ case <-ctx.Done():
366+ return response
367+ }
368+ var result ports.ControlReply
369+ select {
370+ case result = <-ch:
371+ case <-ctx.Done():
372+ return response
373+ }
374+ // The device announcement went through only if core ran the batch.
375+ code := result.Err
376+ if _, inject := message.(ports.ControlInject); inject && (code == "" || code == ports.ControlErrTimeout) {
377+ *announced = true
378+ }
379+ response = reply{ID: req.ID, OK: code == "", Done: result.Done.String(), Diff: wireDiff(result.Diff), State: statewire.FromDomain(result.State, s.ids), Late: result.Late, Error: code}
380+ if len(result.Shots) > 0 {
381+ if s.shooter == nil {
382+ response.OK = false
383+ response.Error = ports.ControlErrBadRequest
384+ response.Detail = "capture unavailable"
385+ return response
386+ }
387+ // The capture gets what the core wait left of the request deadline.
388+ shotCtx, cancel := context.WithDeadline(ctx, start.Add(timeout))
389+ shots, err := s.shooter.Shoot(shotCtx, result.Shots, req.Inline)
390+ cancel()
391+ response.Shots = shots
392+ if err != nil {
393+ response.OK = false
394+ response.Error = ports.ControlErrCaptureFailed
395+ response.Detail = err.Error()
396+ }
397+ }
398+ return response
399+}
400+
401+func requestShots(req request) ([]domain.ShotRequest, error) {
402+ var outputs []string
403+ if req.Op == "shot" {
404+ if req.Raw {
405+ return nil, errors.New("raw shots need --every-frame")
406+ }
407+ outputs = req.Outputs
408+ if len(outputs) == 0 {
409+ outputs = []string{""}
410+ }
411+ } else if len(req.Shot) > 0 {
412+ var enabled bool
413+ if err := json.Unmarshal(req.Shot, &enabled); err == nil {
414+ if !enabled {
415+ return nil, nil
416+ }
417+ outputs = []string{""}
418+ } else {
419+ if err := json.Unmarshal(req.Shot, &outputs); err != nil || outputs == nil {
420+ return nil, errors.New("shot must be true, false or an output list")
421+ }
422+ }
423+ }
424+ shots := make([]domain.ShotRequest, 0, len(outputs))
425+ for _, output := range outputs {
426+ shots = append(shots, domain.ShotRequest{Output: output})
427+ }
428+ return shots, nil
429+}
430+
431+// continuousCapture forwards an every-frame start or stop to core, which
432+// decides it; the default directory is the session's frames directory.
433+func (s *Server) continuousCapture(ctx context.Context, req request, out chan<- ports.ControlRequest) reply {
434+ response := reply{ID: req.ID, Error: ports.ControlErrBadRequest}
435+ if (req.EveryFrame && req.Stop) || req.Inline {
436+ return response
437+ }
438+ dir := req.Dir
439+ if dir == "" {
440+ dir = s.framesDir
441+ }
442+ ack := make(chan ports.ContinuousCaptureResult, 1)
443+ select {
444+ case out <- ports.ControlCapture{Outputs: req.Outputs, Dir: dir, Raw: req.Raw, Stop: req.Stop, Caps: domain.CapsAll, Reply: ack}:
445+ case <-ctx.Done():
446+ return response
447+ }
448+ select {
449+ case result := <-ack:
450+ response.OK = result.Err == ""
451+ response.Error = result.Err
452+ response.Dir = result.Dir
453+ case <-ctx.Done():
454+ }
455+ return response
456+}
@@ -0,0 +1,456 @@
1+// Package control serves the v1 JSON-lines control protocol on a Unix socket.
2+package control
3+
4+import (
5+ "bufio"
6+ "context"
7+ "encoding/json"
8+ "errors"
9+ "fmt"
10+ "net"
11+ "os"
12+ "path/filepath"
13+ "sync"
14+ "syscall"
15+ "time"
16+
17+ "github.com/bnema/neferwl/internal/adapters/logging"
18+ "github.com/bnema/neferwl/internal/adapters/statewire"
19+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
20+ "github.com/bnema/neferwl/internal/adapters/xkb"
21+ "github.com/bnema/neferwl/internal/domain"
22+ "github.com/bnema/neferwl/internal/ports"
23+ "golang.org/x/sys/unix"
24+)
25+
26+// Server owns a control listener. Requests on each connection are processed in
27+// order: the next line is read only after the preceding core reply is sent.
28+// Options supplies a dedicated control keymap, never the physical input map.
29+// Listen takes ownership of Keymap on success. The server takes ownership of
30+// each map it receives from Keymaps; producers own any maps left in the channel
31+// after shutdown. Security is sampled before every translated event.
32+type Options struct {
33+ FramesDir string
34+ Shooter *Shooter
35+ Keymap *xkb.Keymap
36+ Keymaps <-chan *xkb.Keymap
37+ Security ports.SessionSecurity
38+}
39+
40+type Server struct {
41+ framesDir string
42+ shooter *Shooter
43+ injectMu sync.Mutex
44+ injector *injector
45+ keymaps <-chan *xkb.Keymap
46+ listener *net.UnixListener
47+ ids *workspaceid.IDs
48+ done chan struct{}
49+ once sync.Once
50+ err error
51+}
52+
53+// Listen creates a private socket using the same workspace IDs as statefile.
54+// An existing socket is removed only when connecting proves it has no listener.
55+func Listen(path string, ids *workspaceid.IDs, opts Options) (*Server, error) {
56+ if ids == nil {
57+ return nil, errors.New("workspace IDs are required")
58+ }
59+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
60+ return nil, err
61+ }
62+ if info, err := os.Lstat(path); err == nil {
63+ if info.Mode()&os.ModeSocket == 0 {
64+ return nil, fmt.Errorf("control path is not a socket: %s", path)
65+ }
66+ conn, err := net.DialTimeout("unix", path, time.Second)
67+ if err == nil {
68+ conn.Close()
69+ return nil, fmt.Errorf("control socket already listening: %s", path)
70+ }
71+ if !errors.Is(err, syscall.ECONNREFUSED) {
72+ return nil, err
73+ }
74+ if err := os.Remove(path); err != nil {
75+ return nil, err
76+ }
77+ } else if !errors.Is(err, os.ErrNotExist) {
78+ return nil, err
79+ }
80+ listener, err := net.ListenUnix("unix", &net.UnixAddr{Name: path, Net: "unix"})
81+ if err != nil {
82+ return nil, err
83+ }
84+ if err := os.Chmod(path, 0o600); err != nil {
85+ listener.Close()
86+ return nil, err
87+ }
88+ s := &Server{listener: listener, ids: ids, done: make(chan struct{})}
89+ s.framesDir = opts.FramesDir
90+ s.shooter = opts.Shooter
91+ s.keymaps = opts.Keymaps
92+ if opts.Keymap != nil {
93+ s.injector = newInjector(opts.Keymap, opts.Security)
94+ }
95+ return s, nil
96+}
97+
98+// Close stops acceptance and all active connections. It is safe to call twice.
99+func (s *Server) Close() error {
100+ s.once.Do(func() {
101+ close(s.done)
102+ s.err = s.listener.Close()
103+ s.injectMu.Lock()
104+ defer s.injectMu.Unlock()
105+ if s.injector != nil {
106+ s.injector.km.Close()
107+ s.injector = nil
108+ }
109+ })
110+ return s.err
111+}
112+
113+// Run accepts connections until cancellation or Close, waiting for handlers to exit.
114+func (s *Server) Run(ctx context.Context, out chan<- ports.ControlRequest) error {
115+ ctx, cancel := context.WithCancel(ctx)
116+ stop := context.AfterFunc(ctx, func() { _ = s.Close() })
117+ defer stop()
118+ var workers sync.WaitGroup
119+ defer workers.Wait()
120+ defer cancel()
121+ log := logging.For(ctx, "control")
122+ log.Info().Str("path", s.listener.Addr().String()).Msg("listening")
123+ for {
124+ conn, err := s.listener.AcceptUnix()
125+ if err != nil {
126+ if ctx.Err() != nil || errors.Is(err, net.ErrClosed) {
127+ return nil
128+ }
129+ return err
130+ }
131+ workers.Add(1)
132+ go func() {
133+ defer workers.Done()
134+ defer conn.Close()
135+ connCtx, cancel := context.WithCancel(ctx)
136+ defer cancel()
137+ go func() {
138+ select {
139+ case <-s.done:
140+ cancel()
141+ case <-connCtx.Done():
142+ }
143+ }()
144+ stop := context.AfterFunc(connCtx, func() { _ = conn.Close() })
145+ defer stop()
146+ if !sameUID(conn) {
147+ log.Warn().Msg("peer rejected")
148+ return
149+ }
150+ s.serve(connCtx, conn, out)
151+ }()
152+ }
153+}
154+
155+func sameUID(conn *net.UnixConn) bool {
156+ raw, err := conn.SyscallConn()
157+ if err != nil {
158+ return false
159+ }
160+ var cred *unix.Ucred
161+ var credErr error
162+ if err := raw.Control(func(fd uintptr) { cred, credErr = unix.GetsockoptUcred(int(fd), unix.SOL_SOCKET, unix.SO_PEERCRED) }); err != nil {
163+ return false
164+ }
165+ return credErr == nil && cred != nil && cred.Uid == uint32(os.Getuid())
166+}
167+
168+type request struct {
169+ EveryFrame bool `json:"every_frame"`
170+ Stop bool `json:"stop"`
171+ Name string `json:"name"`
172+ Mode string `json:"mode"`
173+ Outputs []string `json:"outputs"`
174+ Inline bool `json:"inline"`
175+ Raw bool `json:"raw"`
176+ Shot json.RawMessage `json:"shot"`
177+ ID json.RawMessage `json:"id"`
178+ Op string `json:"op"`
179+ Action string `json:"action"`
180+ What string `json:"what"`
181+ Wait *string `json:"wait"`
182+ Until *string `json:"until"`
183+ Timeout *string `json:"timeout"`
184+ Kind string `json:"kind"`
185+ Combo string `json:"combo"`
186+ Text string `json:"text"`
187+ Cmd string `json:"cmd"`
188+ Args []string `json:"args"`
189+ Fingers int `json:"fingers"`
190+ Dir string `json:"dir"`
191+}
192+
193+type reply struct {
194+ Dir string `json:"dir,omitempty"`
195+ Shots []Shot `json:"shots,omitempty"`
196+ Detail string `json:"detail,omitempty"`
197+ ID json.RawMessage `json:"id"`
198+ OK bool `json:"ok"`
199+ Done string `json:"done"`
200+ Diff diff `json:"diff"`
201+ State statewire.State `json:"state"`
202+ Late []domain.WindowID `json:"late"`
203+ Error string `json:"error,omitempty"`
204+}
205+
206+type command struct {
207+ Name string `json:"name"`
208+ Arg string `json:"arg"`
209+ Kind string `json:"kind"`
210+ Caps []string `json:"caps"`
211+ Summary string `json:"summary"`
212+}
213+
214+func capNames(c domain.Caps) []string {
215+ names := []string{}
216+ for _, item := range []struct {
217+ bit domain.Caps
218+ name string
219+ }{{domain.CapRead, "read"}, {domain.CapAct, "act"}, {domain.CapInput, "input"}, {domain.CapCapture, "capture"}, {domain.CapAdmin, "admin"}} {
220+ if c&item.bit != 0 {
221+ names = append(names, item.name)
222+ }
223+ }
224+ return names
225+}
226+
227+var nullID = json.RawMessage("null")
228+
229+// maxRequestTimeout caps the client-supplied timeout: core and the shooter
230+// hold a request at most this long.
231+const maxRequestTimeout = domain.MaxControlTimeout
232+
233+func (s *Server) serve(ctx context.Context, conn *net.UnixConn, out chan<- ports.ControlRequest) {
234+ scanner := bufio.NewScanner(conn)
235+ scanner.Buffer(make([]byte, 4096), 1024*1024)
236+ encoder := json.NewEncoder(conn)
237+ announced := false
238+ for scanner.Scan() {
239+ var req request
240+ if err := json.Unmarshal(scanner.Bytes(), &req); err != nil {
241+ if encoder.Encode(reply{ID: nullID, Error: ports.ControlErrBadRequest}) != nil {
242+ return
243+ }
244+ continue
245+ }
246+ // The id is optional: a request without one gets "id": null back.
247+ if len(req.ID) == 0 {
248+ req.ID = nullID
249+ }
250+ if req.Op == "hello" {
251+ commands := []command{}
252+ for _, spec := range domain.Commands() {
253+ commands = append(commands, command{spec.Name, spec.Arg, spec.Kind.String(), capNames(spec.Caps), spec.Summary})
254+ }
255+ if encoder.Encode(struct {
256+ ID json.RawMessage `json:"id"`
257+ OK bool `json:"ok"`
258+ V int `json:"v"`
259+ Caps []string `json:"caps"`
260+ Commands []command `json:"commands"`
261+ }{req.ID, true, 1, capNames(domain.CapsAll), commands}) != nil {
262+ return
263+ }
264+ continue
265+ }
266+ response := s.dispatch(ctx, req, out, &announced)
267+ if ctx.Err() != nil {
268+ return
269+ }
270+ if encoder.Encode(response) != nil {
271+ return
272+ }
273+ }
274+}
275+
276+func (s *Server) dispatch(ctx context.Context, req request, out chan<- ports.ControlRequest, announced *bool) reply {
277+ // The request deadline covers the core wait and the capture together.
278+ start := time.Now()
279+ response := reply{ID: req.ID, Error: ports.ControlErrBadRequest}
280+ if req.Op == "shot" && (req.EveryFrame || req.Stop) {
281+ return s.continuousCapture(ctx, req, out)
282+ }
283+ ch := make(chan ports.ControlReply, 1)
284+ var message ports.ControlRequest
285+ timeout := domain.DefaultControlTimeout
286+ switch req.Op {
287+ case "output-add", "output-rm":
288+ mode := domain.OutputMode{}
289+ if req.Op == "output-add" {
290+ var err error
291+ mode, err = domain.ParseOutputMode(req.Mode)
292+ if err != nil {
293+ return response
294+ }
295+ } else if req.Name == "" {
296+ return response
297+ }
298+ message = ports.ControlOutput{Name: req.Name, Mode: mode, Remove: req.Op == "output-rm", Caps: domain.CapsAll, Reply: ch}
299+
300+ case "do", "inject", "shot":
301+ shots, err := requestShots(req)
302+ if err != nil {
303+ response.Detail = err.Error()
304+ return response
305+ }
306+ if len(shots) > 0 && s.shooter == nil {
307+ response.Detail = "capture unavailable"
308+ return response
309+ }
310+ wait := domain.DefaultWait
311+ if req.Wait != nil {
312+ var err error
313+ wait, err = domain.ParseWaitLevel(*req.Wait)
314+ if err != nil {
315+ return response
316+ }
317+ }
318+ var until *domain.Until
319+ if req.Until != nil {
320+ parsed, err := domain.ParseUntil(*req.Until)
321+ if err != nil {
322+ return response
323+ }
324+ until = &parsed
325+ }
326+ if req.Timeout != nil {
327+ var err error
328+ timeout, err = time.ParseDuration(*req.Timeout)
329+ if err != nil || timeout <= 0 {
330+ return response
331+ }
332+ if timeout > maxRequestTimeout {
333+ response.Detail = "timeout exceeds 5m"
334+ return response
335+ }
336+ }
337+ if len(shots) > 0 {
338+ wait = domain.WaitPresented
339+ }
340+ if req.Op == "inject" {
341+ events, err := s.translate(req, !*announced)
342+ if err != nil {
343+ return response
344+ }
345+ message = ports.ControlInject{Shots: shots, Events: events, Wait: wait, Until: until, Timeout: timeout, Caps: domain.CapsAll, Reply: ch}
346+ } else {
347+ if req.Op == "shot" {
348+ req.Action = "none"
349+ }
350+ if req.Action == "" {
351+ return response
352+ }
353+ message = ports.ControlDo{Shots: shots, Action: req.Action, Wait: wait, Until: until, Timeout: timeout, Caps: domain.CapsAll, Reply: ch}
354+ }
355+ case "query":
356+ if req.What == "" {
357+ return response
358+ }
359+ message = ports.ControlQuery{What: req.What, Caps: domain.CapsAll, Reply: ch}
360+ default:
361+ return response
362+ }
363+ select {
364+ case out <- message:
365+ case <-ctx.Done():
366+ return response
367+ }
368+ var result ports.ControlReply
369+ select {
370+ case result = <-ch:
371+ case <-ctx.Done():
372+ return response
373+ }
374+ // The device announcement went through only if core ran the batch.
375+ code := result.Err
376+ if _, inject := message.(ports.ControlInject); inject && (code == "" || code == ports.ControlErrTimeout) {
377+ *announced = true
378+ }
379+ response = reply{ID: req.ID, OK: code == "", Done: result.Done.String(), Diff: wireDiff(result.Diff), State: statewire.FromDomain(result.State, s.ids), Late: result.Late, Error: code}
380+ if len(result.Shots) > 0 {
381+ if s.shooter == nil {
382+ response.OK = false
383+ response.Error = ports.ControlErrBadRequest
384+ response.Detail = "capture unavailable"
385+ return response
386+ }
387+ // The capture gets what the core wait left of the request deadline.
388+ shotCtx, cancel := context.WithDeadline(ctx, start.Add(timeout))
389+ shots, err := s.shooter.Shoot(shotCtx, result.Shots, req.Inline)
390+ cancel()
391+ response.Shots = shots
392+ if err != nil {
393+ response.OK = false
394+ response.Error = ports.ControlErrCaptureFailed
395+ response.Detail = err.Error()
396+ }
397+ }
398+ return response
399+}
400+
401+func requestShots(req request) ([]domain.ShotRequest, error) {
402+ var outputs []string
403+ if req.Op == "shot" {
404+ if req.Raw {
405+ return nil, errors.New("raw shots need --every-frame")
406+ }
407+ outputs = req.Outputs
408+ if len(outputs) == 0 {
409+ outputs = []string{""}
410+ }
411+ } else if len(req.Shot) > 0 {
412+ var enabled bool
413+ if err := json.Unmarshal(req.Shot, &enabled); err == nil {
414+ if !enabled {
415+ return nil, nil
416+ }
417+ outputs = []string{""}
418+ } else {
419+ if err := json.Unmarshal(req.Shot, &outputs); err != nil || outputs == nil {
420+ return nil, errors.New("shot must be true, false or an output list")
421+ }
422+ }
423+ }
424+ shots := make([]domain.ShotRequest, 0, len(outputs))
425+ for _, output := range outputs {
426+ shots = append(shots, domain.ShotRequest{Output: output})
427+ }
428+ return shots, nil
429+}
430+
431+// continuousCapture forwards an every-frame start or stop to core, which
432+// decides it; the default directory is the session's frames directory.
433+func (s *Server) continuousCapture(ctx context.Context, req request, out chan<- ports.ControlRequest) reply {
434+ response := reply{ID: req.ID, Error: ports.ControlErrBadRequest}
435+ if (req.EveryFrame && req.Stop) || req.Inline {
436+ return response
437+ }
438+ dir := req.Dir
439+ if dir == "" {
440+ dir = s.framesDir
441+ }
442+ ack := make(chan ports.ContinuousCaptureResult, 1)
443+ select {
444+ case out <- ports.ControlCapture{Outputs: req.Outputs, Dir: dir, Raw: req.Raw, Stop: req.Stop, Caps: domain.CapsAll, Reply: ack}:
445+ case <-ctx.Done():
446+ return response
447+ }
448+ select {
449+ case result := <-ack:
450+ response.OK = result.Err == ""
451+ response.Error = result.Err
452+ response.Dir = result.Dir
453+ case <-ctx.Done():
454+ }
455+ return response
456+}
A internal/adapters/control/control_test.go +313 -0
@@ -0,0 +1,313 @@
1+package control
2+
3+import (
4+ "bufio"
5+ "context"
6+ "encoding/json"
7+ "net"
8+ "os"
9+ "path/filepath"
10+ "reflect"
11+ "testing"
12+ "time"
13+
14+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
15+ "github.com/bnema/neferwl/internal/domain"
16+ "github.com/bnema/neferwl/internal/ports"
17+)
18+
19+//testpolicy:realtime Unix socket exchanges and server shutdown need bounded waits outside synctest.
20+func TestProtocol(t *testing.T) {
21+ path := filepath.Join(t.TempDir(), "session", "control.sock")
22+ s, err := Listen(path, workspaceid.WithPrefix("test"), Options{})
23+ if err != nil {
24+ t.Fatal(err)
25+ }
26+ defer s.Close()
27+ for path, want := range map[string]os.FileMode{filepath.Dir(path): 0o700, path: 0o600} {
28+ info, err := os.Stat(path)
29+ if err != nil || info.Mode().Perm() != want {
30+ t.Fatalf("permissions %s: %v %v", path, info, err)
31+ }
32+ }
33+ ctx, cancel := context.WithCancel(context.Background())
34+ defer cancel()
35+ out := make(chan ports.ControlRequest)
36+ done := make(chan error, 1)
37+ go func() { done <- s.Run(ctx, out) }()
38+ conn, err := net.Dial("unix", path)
39+ if err != nil {
40+ t.Fatal(err)
41+ }
42+ defer conn.Close()
43+ if err := conn.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
44+ t.Fatal(err)
45+ }
46+ reader := bufio.NewReader(conn)
47+ exchange := func(line string) map[string]json.RawMessage {
48+ t.Helper()
49+ if _, err := conn.Write([]byte(line + "\n")); err != nil {
50+ t.Fatal(err)
51+ }
52+ data, err := reader.ReadBytes('\n')
53+ if err != nil {
54+ t.Fatal(err)
55+ }
56+ var got map[string]json.RawMessage
57+ if err := json.Unmarshal(data, &got); err != nil {
58+ t.Fatal(err)
59+ }
60+ return got
61+ }
62+ hello := exchange(`{"id":"hello","op":"hello"}`)
63+ if string(hello["id"]) != `"hello"` || string(hello["ok"]) != "true" || string(hello["v"]) != "1" {
64+ t.Fatal(hello)
65+ }
66+ // A line that is not JSON has no id to echo: null.
67+ if bad := exchange(`{broken`); string(bad["id"]) != "null" || string(bad["error"]) != `"bad-request"` {
68+ t.Fatal(bad)
69+ }
70+ if long := exchange(`{"id":9,"op":"do","action":"none","timeout":"6m"}`); string(long["detail"]) != `"timeout exceeds 5m"` {
71+ t.Fatal(long)
72+ }
73+ // The id is optional and echoed as null.
74+ if anon := exchange(`{"op":"hello"}`); string(anon["id"]) != "null" || string(anon["ok"]) != "true" {
75+ t.Fatal(anon)
76+ }
77+ var commands []command
78+ if err := json.Unmarshal(hello["commands"], &commands); err != nil {
79+ t.Fatal(err)
80+ }
81+ if len(commands) != len(domain.Commands()) || commands[0].Name != domain.Commands()[0].Name || len(commands[0].Caps) == 0 {
82+ t.Fatal(commands)
83+ }
84+ for i, spec := range domain.Commands() {
85+ if commands[i].Kind != spec.Kind.String() {
86+ t.Errorf("command %q kind = %q, want %q", spec.Name, commands[i].Kind, spec.Kind.String())
87+ }
88+ }
89+ var caps []string
90+ if err := json.Unmarshal(hello["caps"], &caps); err != nil {
91+ t.Fatal(err)
92+ }
93+ if !reflect.DeepEqual(caps, []string{"read", "act", "input", "capture", "admin"}) {
94+ t.Fatal(caps)
95+ }
96+ for _, line := range []string{`{broken`, `{"id":2,"op":"unknown"}`, `{"id":3,"op":"do","action":"none","wait":"bad"}`, `{"id":4,"op":"do","action":"none","until":"bad"}`, `{"id":5,"op":"do","action":"none","timeout":"bad"}`, `{"id":5,"op":"do","action":"none","timeout":"6m"}`, `{"op":"do"}`} {
97+ got := exchange(line)
98+ if string(got["error"]) != `"bad-request"` || string(got["ok"]) != "false" {
99+ t.Fatal(got)
100+ }
101+ }
102+ coreDone := make(chan struct{})
103+ go func() {
104+ defer close(coreDone)
105+ for i := 0; i < 3; i++ {
106+ select {
107+ case message := <-out:
108+ switch req := message.(type) {
109+ case ports.ControlDo:
110+ if req.Action != "none" || req.Caps != domain.CapsAll || cap(req.Reply) != 1 {
111+ t.Errorf("do: %+v", req)
112+ }
113+ if i == 0 {
114+ if req.Wait != domain.WaitPresented || req.Timeout != 2*time.Second || req.Until == nil || req.Until.Kind != domain.UntilFocused || req.Until.AppID != "foot" {
115+ t.Errorf("explicit: %+v", req)
116+ }
117+ } else if req.Wait != domain.DefaultWait || req.Timeout != 10*time.Second || req.Until != nil {
118+ t.Errorf("defaults: %+v", req)
119+ }
120+ // Core may reach less than the requested level; preserve its report.
121+ timedOut := ""
122+ if i == 1 {
123+ timedOut = ports.ControlErrTimeout
124+ }
125+ req.Reply <- ports.ControlReply{Done: domain.WaitCommitted, Err: timedOut, Diff: domain.StateDiff{FocusFrom: 1, FocusTo: 2, FocusChanged: true}, Late: []domain.WindowID{3}}
126+ case ports.ControlQuery:
127+ if req.What != "state" || req.Caps != domain.CapsAll || cap(req.Reply) != 1 {
128+ t.Errorf("query: %+v", req)
129+ }
130+ req.Reply <- ports.ControlReply{Done: domain.WaitCommitted, State: domain.State{Outputs: []domain.OutputState{{Name: "A", WorkspaceID: 7}}}}
131+ default:
132+ t.Errorf("unexpected %T", message)
133+ }
134+ case <-ctx.Done():
135+ return
136+ }
137+ }
138+ }()
139+ got := exchange(`{"id":6,"op":"do","action":"none","wait":"presented","until":"focused app_id=foot","timeout":"2s"}`)
140+ if string(got["id"]) != "6" || string(got["done"]) != `"committed"` || string(got["ok"]) != "true" {
141+ t.Fatal(got)
142+ }
143+ if _, present := got["error"]; present {
144+ t.Fatalf("successful reply includes error: %s", got["error"])
145+ }
146+ var d map[string]any
147+ if err := json.Unmarshal(got["diff"], &d); err != nil {
148+ t.Fatal(err)
149+ }
150+ if d["focus_from"] != float64(1) || d["focus_to"] != float64(2) || d["focus_changed"] != true {
151+ t.Fatal(d)
152+ }
153+ got = exchange(`{"id":7,"op":"do","action":"none"}`)
154+ if string(got["error"]) != `"timeout"` || string(got["late"]) != "[3]" {
155+ t.Fatal(got)
156+ }
157+ got = exchange(`{"id":8,"op":"query","what":"state"}`)
158+ var state struct {
159+ Outputs []struct {
160+ WorkspaceID string `json:"workspace_id"`
161+ }
162+ }
163+ if err := json.Unmarshal(got["state"], &state); err != nil {
164+ t.Fatal(err)
165+ }
166+ if len(state.Outputs) != 1 || state.Outputs[0].WorkspaceID != "test-7" {
167+ t.Fatal(state)
168+ }
169+ <-coreDone
170+ // Leave one request awaiting core forever; cancellation must release it.
171+ if _, err := conn.Write([]byte("{\"id\":9,\"op\":\"query\",\"what\":\"state\"}\n")); err != nil {
172+ t.Fatal(err)
173+ }
174+ select {
175+ case <-out:
176+ case <-time.After(10 * time.Second):
177+ t.Fatal("request not received")
178+ }
179+ cancel()
180+ select {
181+ case err := <-done:
182+ if err != nil {
183+ t.Fatal(err)
184+ }
185+ case <-time.After(10 * time.Second):
186+ t.Fatal("Run did not stop")
187+ }
188+}
189+
190+func TestListenPreservesLiveSocketAndFiles(t *testing.T) {
191+ path := filepath.Join(t.TempDir(), "control.sock")
192+ ids := workspaceid.WithPrefix("test")
193+ s, err := Listen(path, ids, Options{})
194+ if err != nil {
195+ t.Fatal(err)
196+ }
197+ defer s.Close()
198+ if other, err := Listen(path, ids, Options{}); err == nil {
199+ other.Close()
200+ t.Fatal("replaced live listener")
201+ }
202+ if err := s.Close(); err != nil {
203+ t.Fatal(err)
204+ }
205+ if err := os.WriteFile(path, []byte("keep"), 0o600); err != nil {
206+ t.Fatal(err)
207+ }
208+ if other, err := Listen(path, ids, Options{}); err == nil {
209+ other.Close()
210+ t.Fatal("replaced regular file")
211+ }
212+ data, err := os.ReadFile(path)
213+ if err != nil || string(data) != "keep" {
214+ t.Fatal(string(data), err)
215+ }
216+}
217+
218+func TestListenRemovesStaleSocket(t *testing.T) {
219+ path := filepath.Join(t.TempDir(), "control.sock")
220+ listener, err := net.ListenUnix("unix", &net.UnixAddr{Name: path, Net: "unix"})
221+ if err != nil {
222+ t.Fatal(err)
223+ }
224+ listener.SetUnlinkOnClose(false)
225+ if err := listener.Close(); err != nil {
226+ t.Fatal(err)
227+ }
228+ s, err := Listen(path, workspaceid.WithPrefix("test"), Options{})
229+ if err != nil {
230+ t.Fatal(err)
231+ }
232+ if err := s.Close(); err != nil {
233+ t.Fatal(err)
234+ }
235+}
236+
237+//testpolicy:realtime Socket reads and cancellation completion are bounded real I/O waits.
238+func TestConnectionOrderingAndClose(t *testing.T) {
239+ s, err := Listen(filepath.Join(t.TempDir(), "control.sock"), workspaceid.WithPrefix("test"), Options{})
240+ if err != nil {
241+ t.Fatal(err)
242+ }
243+ defer s.Close()
244+ ctx, cancel := context.WithCancel(context.Background())
245+ defer cancel()
246+ out := make(chan ports.ControlRequest, 2)
247+ done := make(chan error, 1)
248+ go func() { done <- s.Run(ctx, out) }()
249+ conn, err := net.Dial("unix", s.listener.Addr().String())
250+ if err != nil {
251+ t.Fatal(err)
252+ }
253+ defer conn.Close()
254+ if err := conn.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
255+ t.Fatal(err)
256+ }
257+ if _, err := conn.Write([]byte("{\"id\":1,\"op\":\"query\",\"what\":\"state\"}\n{\"id\":2,\"op\":\"query\",\"what\":\"state\"}\n")); err != nil {
258+ t.Fatal(err)
259+ }
260+ var first ports.ControlQuery
261+ select {
262+ case req := <-out:
263+ first = req.(ports.ControlQuery)
264+ case <-time.After(10 * time.Second):
265+ t.Fatal("first request missing")
266+ }
267+ // A second connection's hello is an I/O barrier while the first awaits core.
268+ barrier, err := net.Dial("unix", s.listener.Addr().String())
269+ if err != nil {
270+ t.Fatal(err)
271+ }
272+ defer barrier.Close()
273+ if err := barrier.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
274+ t.Fatal(err)
275+ }
276+ if _, err := barrier.Write([]byte("{\"id\":0,\"op\":\"hello\"}\n")); err != nil {
277+ t.Fatal(err)
278+ }
279+ if _, err := bufio.NewReader(barrier).ReadBytes('\n'); err != nil {
280+ t.Fatal(err)
281+ }
282+ select {
283+ case <-out:
284+ t.Fatal("read next request before core replied")
285+ default:
286+ }
287+ first.Reply <- ports.ControlReply{}
288+ reader := bufio.NewReader(conn)
289+ if _, err := reader.ReadBytes('\n'); err != nil {
290+ t.Fatal(err)
291+ }
292+ select {
293+ case req := <-out:
294+ req.(ports.ControlQuery).Reply <- ports.ControlReply{}
295+ case <-time.After(10 * time.Second):
296+ t.Fatal("second request missing")
297+ }
298+ if _, err := reader.ReadBytes('\n'); err != nil {
299+ t.Fatal(err)
300+ }
301+ // Both handlers now block reading; Close must release them and the accept loop.
302+ if err := s.Close(); err != nil {
303+ t.Fatal(err)
304+ }
305+ select {
306+ case err := <-done:
307+ if err != nil {
308+ t.Fatal(err)
309+ }
310+ case <-time.After(10 * time.Second):
311+ t.Fatal("Close did not stop Run")
312+ }
313+}
@@ -0,0 +1,313 @@
1+package control
2+
3+import (
4+ "bufio"
5+ "context"
6+ "encoding/json"
7+ "net"
8+ "os"
9+ "path/filepath"
10+ "reflect"
11+ "testing"
12+ "time"
13+
14+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
15+ "github.com/bnema/neferwl/internal/domain"
16+ "github.com/bnema/neferwl/internal/ports"
17+)
18+
19+//testpolicy:realtime Unix socket exchanges and server shutdown need bounded waits outside synctest.
20+func TestProtocol(t *testing.T) {
21+ path := filepath.Join(t.TempDir(), "session", "control.sock")
22+ s, err := Listen(path, workspaceid.WithPrefix("test"), Options{})
23+ if err != nil {
24+ t.Fatal(err)
25+ }
26+ defer s.Close()
27+ for path, want := range map[string]os.FileMode{filepath.Dir(path): 0o700, path: 0o600} {
28+ info, err := os.Stat(path)
29+ if err != nil || info.Mode().Perm() != want {
30+ t.Fatalf("permissions %s: %v %v", path, info, err)
31+ }
32+ }
33+ ctx, cancel := context.WithCancel(context.Background())
34+ defer cancel()
35+ out := make(chan ports.ControlRequest)
36+ done := make(chan error, 1)
37+ go func() { done <- s.Run(ctx, out) }()
38+ conn, err := net.Dial("unix", path)
39+ if err != nil {
40+ t.Fatal(err)
41+ }
42+ defer conn.Close()
43+ if err := conn.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
44+ t.Fatal(err)
45+ }
46+ reader := bufio.NewReader(conn)
47+ exchange := func(line string) map[string]json.RawMessage {
48+ t.Helper()
49+ if _, err := conn.Write([]byte(line + "\n")); err != nil {
50+ t.Fatal(err)
51+ }
52+ data, err := reader.ReadBytes('\n')
53+ if err != nil {
54+ t.Fatal(err)
55+ }
56+ var got map[string]json.RawMessage
57+ if err := json.Unmarshal(data, &got); err != nil {
58+ t.Fatal(err)
59+ }
60+ return got
61+ }
62+ hello := exchange(`{"id":"hello","op":"hello"}`)
63+ if string(hello["id"]) != `"hello"` || string(hello["ok"]) != "true" || string(hello["v"]) != "1" {
64+ t.Fatal(hello)
65+ }
66+ // A line that is not JSON has no id to echo: null.
67+ if bad := exchange(`{broken`); string(bad["id"]) != "null" || string(bad["error"]) != `"bad-request"` {
68+ t.Fatal(bad)
69+ }
70+ if long := exchange(`{"id":9,"op":"do","action":"none","timeout":"6m"}`); string(long["detail"]) != `"timeout exceeds 5m"` {
71+ t.Fatal(long)
72+ }
73+ // The id is optional and echoed as null.
74+ if anon := exchange(`{"op":"hello"}`); string(anon["id"]) != "null" || string(anon["ok"]) != "true" {
75+ t.Fatal(anon)
76+ }
77+ var commands []command
78+ if err := json.Unmarshal(hello["commands"], &commands); err != nil {
79+ t.Fatal(err)
80+ }
81+ if len(commands) != len(domain.Commands()) || commands[0].Name != domain.Commands()[0].Name || len(commands[0].Caps) == 0 {
82+ t.Fatal(commands)
83+ }
84+ for i, spec := range domain.Commands() {
85+ if commands[i].Kind != spec.Kind.String() {
86+ t.Errorf("command %q kind = %q, want %q", spec.Name, commands[i].Kind, spec.Kind.String())
87+ }
88+ }
89+ var caps []string
90+ if err := json.Unmarshal(hello["caps"], &caps); err != nil {
91+ t.Fatal(err)
92+ }
93+ if !reflect.DeepEqual(caps, []string{"read", "act", "input", "capture", "admin"}) {
94+ t.Fatal(caps)
95+ }
96+ for _, line := range []string{`{broken`, `{"id":2,"op":"unknown"}`, `{"id":3,"op":"do","action":"none","wait":"bad"}`, `{"id":4,"op":"do","action":"none","until":"bad"}`, `{"id":5,"op":"do","action":"none","timeout":"bad"}`, `{"id":5,"op":"do","action":"none","timeout":"6m"}`, `{"op":"do"}`} {
97+ got := exchange(line)
98+ if string(got["error"]) != `"bad-request"` || string(got["ok"]) != "false" {
99+ t.Fatal(got)
100+ }
101+ }
102+ coreDone := make(chan struct{})
103+ go func() {
104+ defer close(coreDone)
105+ for i := 0; i < 3; i++ {
106+ select {
107+ case message := <-out:
108+ switch req := message.(type) {
109+ case ports.ControlDo:
110+ if req.Action != "none" || req.Caps != domain.CapsAll || cap(req.Reply) != 1 {
111+ t.Errorf("do: %+v", req)
112+ }
113+ if i == 0 {
114+ if req.Wait != domain.WaitPresented || req.Timeout != 2*time.Second || req.Until == nil || req.Until.Kind != domain.UntilFocused || req.Until.AppID != "foot" {
115+ t.Errorf("explicit: %+v", req)
116+ }
117+ } else if req.Wait != domain.DefaultWait || req.Timeout != 10*time.Second || req.Until != nil {
118+ t.Errorf("defaults: %+v", req)
119+ }
120+ // Core may reach less than the requested level; preserve its report.
121+ timedOut := ""
122+ if i == 1 {
123+ timedOut = ports.ControlErrTimeout
124+ }
125+ req.Reply <- ports.ControlReply{Done: domain.WaitCommitted, Err: timedOut, Diff: domain.StateDiff{FocusFrom: 1, FocusTo: 2, FocusChanged: true}, Late: []domain.WindowID{3}}
126+ case ports.ControlQuery:
127+ if req.What != "state" || req.Caps != domain.CapsAll || cap(req.Reply) != 1 {
128+ t.Errorf("query: %+v", req)
129+ }
130+ req.Reply <- ports.ControlReply{Done: domain.WaitCommitted, State: domain.State{Outputs: []domain.OutputState{{Name: "A", WorkspaceID: 7}}}}
131+ default:
132+ t.Errorf("unexpected %T", message)
133+ }
134+ case <-ctx.Done():
135+ return
136+ }
137+ }
138+ }()
139+ got := exchange(`{"id":6,"op":"do","action":"none","wait":"presented","until":"focused app_id=foot","timeout":"2s"}`)
140+ if string(got["id"]) != "6" || string(got["done"]) != `"committed"` || string(got["ok"]) != "true" {
141+ t.Fatal(got)
142+ }
143+ if _, present := got["error"]; present {
144+ t.Fatalf("successful reply includes error: %s", got["error"])
145+ }
146+ var d map[string]any
147+ if err := json.Unmarshal(got["diff"], &d); err != nil {
148+ t.Fatal(err)
149+ }
150+ if d["focus_from"] != float64(1) || d["focus_to"] != float64(2) || d["focus_changed"] != true {
151+ t.Fatal(d)
152+ }
153+ got = exchange(`{"id":7,"op":"do","action":"none"}`)
154+ if string(got["error"]) != `"timeout"` || string(got["late"]) != "[3]" {
155+ t.Fatal(got)
156+ }
157+ got = exchange(`{"id":8,"op":"query","what":"state"}`)
158+ var state struct {
159+ Outputs []struct {
160+ WorkspaceID string `json:"workspace_id"`
161+ }
162+ }
163+ if err := json.Unmarshal(got["state"], &state); err != nil {
164+ t.Fatal(err)
165+ }
166+ if len(state.Outputs) != 1 || state.Outputs[0].WorkspaceID != "test-7" {
167+ t.Fatal(state)
168+ }
169+ <-coreDone
170+ // Leave one request awaiting core forever; cancellation must release it.
171+ if _, err := conn.Write([]byte("{\"id\":9,\"op\":\"query\",\"what\":\"state\"}\n")); err != nil {
172+ t.Fatal(err)
173+ }
174+ select {
175+ case <-out:
176+ case <-time.After(10 * time.Second):
177+ t.Fatal("request not received")
178+ }
179+ cancel()
180+ select {
181+ case err := <-done:
182+ if err != nil {
183+ t.Fatal(err)
184+ }
185+ case <-time.After(10 * time.Second):
186+ t.Fatal("Run did not stop")
187+ }
188+}
189+
190+func TestListenPreservesLiveSocketAndFiles(t *testing.T) {
191+ path := filepath.Join(t.TempDir(), "control.sock")
192+ ids := workspaceid.WithPrefix("test")
193+ s, err := Listen(path, ids, Options{})
194+ if err != nil {
195+ t.Fatal(err)
196+ }
197+ defer s.Close()
198+ if other, err := Listen(path, ids, Options{}); err == nil {
199+ other.Close()
200+ t.Fatal("replaced live listener")
201+ }
202+ if err := s.Close(); err != nil {
203+ t.Fatal(err)
204+ }
205+ if err := os.WriteFile(path, []byte("keep"), 0o600); err != nil {
206+ t.Fatal(err)
207+ }
208+ if other, err := Listen(path, ids, Options{}); err == nil {
209+ other.Close()
210+ t.Fatal("replaced regular file")
211+ }
212+ data, err := os.ReadFile(path)
213+ if err != nil || string(data) != "keep" {
214+ t.Fatal(string(data), err)
215+ }
216+}
217+
218+func TestListenRemovesStaleSocket(t *testing.T) {
219+ path := filepath.Join(t.TempDir(), "control.sock")
220+ listener, err := net.ListenUnix("unix", &net.UnixAddr{Name: path, Net: "unix"})
221+ if err != nil {
222+ t.Fatal(err)
223+ }
224+ listener.SetUnlinkOnClose(false)
225+ if err := listener.Close(); err != nil {
226+ t.Fatal(err)
227+ }
228+ s, err := Listen(path, workspaceid.WithPrefix("test"), Options{})
229+ if err != nil {
230+ t.Fatal(err)
231+ }
232+ if err := s.Close(); err != nil {
233+ t.Fatal(err)
234+ }
235+}
236+
237+//testpolicy:realtime Socket reads and cancellation completion are bounded real I/O waits.
238+func TestConnectionOrderingAndClose(t *testing.T) {
239+ s, err := Listen(filepath.Join(t.TempDir(), "control.sock"), workspaceid.WithPrefix("test"), Options{})
240+ if err != nil {
241+ t.Fatal(err)
242+ }
243+ defer s.Close()
244+ ctx, cancel := context.WithCancel(context.Background())
245+ defer cancel()
246+ out := make(chan ports.ControlRequest, 2)
247+ done := make(chan error, 1)
248+ go func() { done <- s.Run(ctx, out) }()
249+ conn, err := net.Dial("unix", s.listener.Addr().String())
250+ if err != nil {
251+ t.Fatal(err)
252+ }
253+ defer conn.Close()
254+ if err := conn.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
255+ t.Fatal(err)
256+ }
257+ if _, err := conn.Write([]byte("{\"id\":1,\"op\":\"query\",\"what\":\"state\"}\n{\"id\":2,\"op\":\"query\",\"what\":\"state\"}\n")); err != nil {
258+ t.Fatal(err)
259+ }
260+ var first ports.ControlQuery
261+ select {
262+ case req := <-out:
263+ first = req.(ports.ControlQuery)
264+ case <-time.After(10 * time.Second):
265+ t.Fatal("first request missing")
266+ }
267+ // A second connection's hello is an I/O barrier while the first awaits core.
268+ barrier, err := net.Dial("unix", s.listener.Addr().String())
269+ if err != nil {
270+ t.Fatal(err)
271+ }
272+ defer barrier.Close()
273+ if err := barrier.SetDeadline(time.Now().Add(10 * time.Second)); err != nil {
274+ t.Fatal(err)
275+ }
276+ if _, err := barrier.Write([]byte("{\"id\":0,\"op\":\"hello\"}\n")); err != nil {
277+ t.Fatal(err)
278+ }
279+ if _, err := bufio.NewReader(barrier).ReadBytes('\n'); err != nil {
280+ t.Fatal(err)
281+ }
282+ select {
283+ case <-out:
284+ t.Fatal("read next request before core replied")
285+ default:
286+ }
287+ first.Reply <- ports.ControlReply{}
288+ reader := bufio.NewReader(conn)
289+ if _, err := reader.ReadBytes('\n'); err != nil {
290+ t.Fatal(err)
291+ }
292+ select {
293+ case req := <-out:
294+ req.(ports.ControlQuery).Reply <- ports.ControlReply{}
295+ case <-time.After(10 * time.Second):
296+ t.Fatal("second request missing")
297+ }
298+ if _, err := reader.ReadBytes('\n'); err != nil {
299+ t.Fatal(err)
300+ }
301+ // Both handlers now block reading; Close must release them and the accept loop.
302+ if err := s.Close(); err != nil {
303+ t.Fatal(err)
304+ }
305+ select {
306+ case err := <-done:
307+ if err != nil {
308+ t.Fatal(err)
309+ }
310+ case <-time.After(10 * time.Second):
311+ t.Fatal("Close did not stop Run")
312+ }
313+}
A internal/adapters/control/inject.go +261 -0
@@ -0,0 +1,261 @@
1+package control
2+
3+import (
4+ "errors"
5+ "math"
6+ "slices"
7+ "strconv"
8+ "strings"
9+ "time"
10+ "unicode"
11+
12+ "github.com/bnema/neferwl/internal/adapters/xkb"
13+ "github.com/bnema/neferwl/internal/domain"
14+ "github.com/bnema/neferwl/internal/ports"
15+ "golang.org/x/sys/unix"
16+)
17+
18+const controlDeviceID domain.InputDeviceID = 1
19+
20+// injector translates commands on its owner's goroutine. It borrows km; the
21+// caller owns its lifetime and announces Device once before delivering input.
22+// Coordinates are global logical coordinates; layout clamping belongs to core.
23+type injector struct {
24+ km *xkb.Keymap
25+ security ports.SessionSecurity
26+}
27+
28+func newInjector(km *xkb.Keymap, security ports.SessionSecurity) *injector {
29+ return &injector{km: km, security: security}
30+}
31+
32+func injectTime() time.Duration {
33+ var ts unix.Timespec
34+ _ = unix.ClockGettime(unix.CLOCK_MONOTONIC, &ts)
35+ return time.Duration(ts.Nano())
36+}
37+
38+func (i *injector) snapshot() domain.SecurityState {
39+ if i.security != nil {
40+ return i.security.Snapshot()
41+ }
42+ return domain.SecurityState{}
43+}
44+
45+func (i *injector) stamp(ev ports.InputEvent, state domain.SecurityState) ports.InputEvent {
46+ if i.security != nil {
47+ return ports.SecurityInput{State: state, Event: ev}
48+ }
49+ return ev
50+}
51+
52+// Device returns the announcement to send once for this synthetic producer.
53+func (i *injector) Device() ports.InputEvent {
54+ return i.stamp(ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}, i.snapshot())
55+}
56+
57+func (i *injector) keyEdge(events []ports.InputEvent, code uint32, down bool) ([]ports.InputEvent, error) {
58+ state := i.snapshot() // Must precede KeySecure's epoch-aware translation.
59+ var key ports.KeyEvent
60+ if i.security != nil {
61+ var deliver bool
62+ var err error
63+ key, deliver, err = i.km.KeySecure(code, down, injectTime(), state)
64+ if err != nil {
65+ return nil, err
66+ }
67+ if !deliver {
68+ return events, nil
69+ }
70+ } else {
71+ key = i.km.Key(code, down, injectTime())
72+ }
73+ key.Device = controlDeviceID
74+ return append(events, i.stamp(key, state)), nil
75+}
76+
77+func injectModifier(name string) uint32 {
78+ switch name {
79+ case "Super":
80+ return 125
81+ case "Shift":
82+ return 42
83+ case "Ctrl":
84+ return 29
85+ case "Alt":
86+ return 56
87+ }
88+ return 0
89+}
90+
91+// combo resolves all keys before any keymap state is changed.
92+func (i *injector) combo(combo string) ([]uint32, error) {
93+ parts := strings.Split(combo, "+")
94+ var codes []uint32
95+ for _, name := range parts[:len(parts)-1] {
96+ code := injectModifier(name)
97+ if code == 0 {
98+ return nil, errors.New("unknown modifier")
99+ }
100+ codes = append(codes, code)
101+ }
102+ name := parts[len(parts)-1]
103+ // Modifier-only presses use the same evdev identities as script press/release.
104+ if code := injectModifier(name); code != 0 {
105+ return append(codes, code), nil
106+ }
107+ code, shift, ok := i.km.KeycodeFor(name)
108+ if !ok {
109+ return nil, errors.New("unknown key")
110+ }
111+ if shift && !slices.Contains(codes, uint32(42)) && !slices.Contains(codes, uint32(54)) {
112+ codes = append(codes, 42)
113+ }
114+ return append(codes, code), nil
115+}
116+
117+func (i *injector) edges(codes []uint32, down bool, events []ports.InputEvent) ([]ports.InputEvent, error) {
118+ for n := range codes {
119+ at := n
120+ if !down {
121+ at = len(codes) - 1 - n
122+ }
123+ var err error
124+ events, err = i.keyEdge(events, codes[at], down)
125+ if err != nil {
126+ return nil, err
127+ }
128+ }
129+ return events, nil
130+}
131+
132+func (i *injector) Key(combo string) ([]ports.InputEvent, error) {
133+ codes, err := i.combo(combo)
134+ if err != nil {
135+ return nil, err
136+ }
137+ events, err := i.edges(codes, true, nil)
138+ if err != nil {
139+ return nil, err
140+ }
141+ return i.edges(codes, false, events)
142+}
143+
144+func (i *injector) Press(combo string) ([]ports.InputEvent, error) {
145+ codes, err := i.combo(combo)
146+ if err != nil {
147+ return nil, err
148+ }
149+ return i.edges(codes, true, nil)
150+}
151+
152+func (i *injector) Release(combo string) ([]ports.InputEvent, error) {
153+ codes, err := i.combo(combo)
154+ if err != nil {
155+ return nil, err
156+ }
157+ return i.edges(codes, false, nil)
158+}
159+
160+var injectPunctuation = map[rune]string{' ': "space", '\n': "Return", '.': "period", ',': "comma", '-': "minus", '_': "underscore", '/': "slash", ':': "colon", ';': "semicolon", '!': "exclam", '?': "question", '\'': "apostrophe", '"': "quotedbl", '(': "parenleft", ')': "parenright", '=': "equal", '+': "plus", '\\': "backslash", '@': "at", '#': "numbersign", '$': "dollar", '%': "percent", '&': "ampersand", '*': "asterisk", '[': "bracketleft", ']': "bracketright", '{': "braceleft", '}': "braceright", '<': "less", '>': "greater", '|': "bar", '`': "grave", '~': "asciitilde", '^': "asciicircum"}
161+
162+func (i *injector) Type(text string) ([]ports.InputEvent, error) {
163+ var strokes [][]uint32
164+ for _, r := range text {
165+ name := injectPunctuation[r]
166+ if name == "" && (unicode.IsLetter(r) || unicode.IsDigit(r)) {
167+ name = string(r)
168+ }
169+ if name == "" {
170+ return nil, errors.New("unknown rune")
171+ }
172+ codes, err := i.combo(name)
173+ if err != nil {
174+ return nil, err
175+ }
176+ strokes = append(strokes, codes)
177+ }
178+ var events []ports.InputEvent
179+ for _, codes := range strokes {
180+ var err error
181+ events, err = i.edges(codes, true, events)
182+ if err != nil {
183+ return nil, err
184+ }
185+ events, err = i.edges(codes, false, events)
186+ if err != nil {
187+ return nil, err
188+ }
189+ }
190+ return events, nil
191+}
192+
193+func (i *injector) Pointer(cmd string, args []string) ([]ports.InputEvent, error) {
194+ now := injectTime()
195+ if cmd == "move" {
196+ if len(args) != 2 {
197+ return nil, errors.New("move requires x y")
198+ }
199+ x, ex := strconv.ParseFloat(args[0], 64)
200+ y, ey := strconv.ParseFloat(args[1], 64)
201+ if ex != nil || ey != nil || math.IsNaN(x) || math.IsNaN(y) || math.IsInf(x, 0) || math.IsInf(y, 0) {
202+ return nil, errors.New("invalid move coordinates")
203+ }
204+ return []ports.InputEvent{i.stamp(ports.PointerMotion{Device: controlDeviceID, X: x, Y: y, Time: now}, i.snapshot())}, nil
205+ }
206+ if cmd != "click" && cmd != "down" && cmd != "up" {
207+ return nil, errors.New("unknown pointer command")
208+ }
209+ if len(args) > 1 || len(args) == 0 && cmd != "click" {
210+ return nil, errors.New("invalid button arguments")
211+ }
212+ name := "left"
213+ if len(args) == 1 {
214+ name = args[0]
215+ }
216+ var button uint32
217+ switch name {
218+ case "left":
219+ button = 0x110
220+ case "right":
221+ button = 0x111
222+ case "middle":
223+ button = 0x112
224+ default:
225+ return nil, errors.New("unknown button")
226+ }
227+ var events []ports.InputEvent
228+ if cmd != "up" {
229+ events = append(events, i.stamp(ports.PointerButton{Device: controlDeviceID, Button: button, Pressed: true, Time: now}, i.snapshot()))
230+ }
231+ if cmd != "down" {
232+ events = append(events, i.stamp(ports.PointerButton{Device: controlDeviceID, Button: button, Time: now}, i.snapshot()))
233+ }
234+ return events, nil
235+}
236+
237+func (i *injector) Swipe(fingers int, dir string) ([]ports.InputEvent, error) {
238+ if fingers != 3 && fingers != 4 {
239+ return nil, errors.New("swipe requires three or four fingers")
240+ }
241+ var dx, dy float64
242+ switch dir {
243+ case "up":
244+ dy = -40
245+ case "down":
246+ dy = 40
247+ case "left":
248+ dx = -40
249+ case "right":
250+ dx = 40
251+ default:
252+ return nil, errors.New("invalid swipe direction")
253+ }
254+ at := injectTime()
255+ events := []ports.InputEvent{i.stamp(ports.SwipeBegin{Device: controlDeviceID, Fingers: fingers, Time: at}, i.snapshot())}
256+ for range 10 {
257+ at += 8 * time.Millisecond
258+ events = append(events, i.stamp(ports.SwipeUpdate{Device: controlDeviceID, DX: dx, DY: dy, Time: at}, i.snapshot()))
259+ }
260+ return append(events, i.stamp(ports.SwipeEnd{Device: controlDeviceID, Time: at}, i.snapshot())), nil
261+}
@@ -0,0 +1,261 @@
1+package control
2+
3+import (
4+ "errors"
5+ "math"
6+ "slices"
7+ "strconv"
8+ "strings"
9+ "time"
10+ "unicode"
11+
12+ "github.com/bnema/neferwl/internal/adapters/xkb"
13+ "github.com/bnema/neferwl/internal/domain"
14+ "github.com/bnema/neferwl/internal/ports"
15+ "golang.org/x/sys/unix"
16+)
17+
18+const controlDeviceID domain.InputDeviceID = 1
19+
20+// injector translates commands on its owner's goroutine. It borrows km; the
21+// caller owns its lifetime and announces Device once before delivering input.
22+// Coordinates are global logical coordinates; layout clamping belongs to core.
23+type injector struct {
24+ km *xkb.Keymap
25+ security ports.SessionSecurity
26+}
27+
28+func newInjector(km *xkb.Keymap, security ports.SessionSecurity) *injector {
29+ return &injector{km: km, security: security}
30+}
31+
32+func injectTime() time.Duration {
33+ var ts unix.Timespec
34+ _ = unix.ClockGettime(unix.CLOCK_MONOTONIC, &ts)
35+ return time.Duration(ts.Nano())
36+}
37+
38+func (i *injector) snapshot() domain.SecurityState {
39+ if i.security != nil {
40+ return i.security.Snapshot()
41+ }
42+ return domain.SecurityState{}
43+}
44+
45+func (i *injector) stamp(ev ports.InputEvent, state domain.SecurityState) ports.InputEvent {
46+ if i.security != nil {
47+ return ports.SecurityInput{State: state, Event: ev}
48+ }
49+ return ev
50+}
51+
52+// Device returns the announcement to send once for this synthetic producer.
53+func (i *injector) Device() ports.InputEvent {
54+ return i.stamp(ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}, i.snapshot())
55+}
56+
57+func (i *injector) keyEdge(events []ports.InputEvent, code uint32, down bool) ([]ports.InputEvent, error) {
58+ state := i.snapshot() // Must precede KeySecure's epoch-aware translation.
59+ var key ports.KeyEvent
60+ if i.security != nil {
61+ var deliver bool
62+ var err error
63+ key, deliver, err = i.km.KeySecure(code, down, injectTime(), state)
64+ if err != nil {
65+ return nil, err
66+ }
67+ if !deliver {
68+ return events, nil
69+ }
70+ } else {
71+ key = i.km.Key(code, down, injectTime())
72+ }
73+ key.Device = controlDeviceID
74+ return append(events, i.stamp(key, state)), nil
75+}
76+
77+func injectModifier(name string) uint32 {
78+ switch name {
79+ case "Super":
80+ return 125
81+ case "Shift":
82+ return 42
83+ case "Ctrl":
84+ return 29
85+ case "Alt":
86+ return 56
87+ }
88+ return 0
89+}
90+
91+// combo resolves all keys before any keymap state is changed.
92+func (i *injector) combo(combo string) ([]uint32, error) {
93+ parts := strings.Split(combo, "+")
94+ var codes []uint32
95+ for _, name := range parts[:len(parts)-1] {
96+ code := injectModifier(name)
97+ if code == 0 {
98+ return nil, errors.New("unknown modifier")
99+ }
100+ codes = append(codes, code)
101+ }
102+ name := parts[len(parts)-1]
103+ // Modifier-only presses use the same evdev identities as script press/release.
104+ if code := injectModifier(name); code != 0 {
105+ return append(codes, code), nil
106+ }
107+ code, shift, ok := i.km.KeycodeFor(name)
108+ if !ok {
109+ return nil, errors.New("unknown key")
110+ }
111+ if shift && !slices.Contains(codes, uint32(42)) && !slices.Contains(codes, uint32(54)) {
112+ codes = append(codes, 42)
113+ }
114+ return append(codes, code), nil
115+}
116+
117+func (i *injector) edges(codes []uint32, down bool, events []ports.InputEvent) ([]ports.InputEvent, error) {
118+ for n := range codes {
119+ at := n
120+ if !down {
121+ at = len(codes) - 1 - n
122+ }
123+ var err error
124+ events, err = i.keyEdge(events, codes[at], down)
125+ if err != nil {
126+ return nil, err
127+ }
128+ }
129+ return events, nil
130+}
131+
132+func (i *injector) Key(combo string) ([]ports.InputEvent, error) {
133+ codes, err := i.combo(combo)
134+ if err != nil {
135+ return nil, err
136+ }
137+ events, err := i.edges(codes, true, nil)
138+ if err != nil {
139+ return nil, err
140+ }
141+ return i.edges(codes, false, events)
142+}
143+
144+func (i *injector) Press(combo string) ([]ports.InputEvent, error) {
145+ codes, err := i.combo(combo)
146+ if err != nil {
147+ return nil, err
148+ }
149+ return i.edges(codes, true, nil)
150+}
151+
152+func (i *injector) Release(combo string) ([]ports.InputEvent, error) {
153+ codes, err := i.combo(combo)
154+ if err != nil {
155+ return nil, err
156+ }
157+ return i.edges(codes, false, nil)
158+}
159+
160+var injectPunctuation = map[rune]string{' ': "space", '\n': "Return", '.': "period", ',': "comma", '-': "minus", '_': "underscore", '/': "slash", ':': "colon", ';': "semicolon", '!': "exclam", '?': "question", '\'': "apostrophe", '"': "quotedbl", '(': "parenleft", ')': "parenright", '=': "equal", '+': "plus", '\\': "backslash", '@': "at", '#': "numbersign", '$': "dollar", '%': "percent", '&': "ampersand", '*': "asterisk", '[': "bracketleft", ']': "bracketright", '{': "braceleft", '}': "braceright", '<': "less", '>': "greater", '|': "bar", '`': "grave", '~': "asciitilde", '^': "asciicircum"}
161+
162+func (i *injector) Type(text string) ([]ports.InputEvent, error) {
163+ var strokes [][]uint32
164+ for _, r := range text {
165+ name := injectPunctuation[r]
166+ if name == "" && (unicode.IsLetter(r) || unicode.IsDigit(r)) {
167+ name = string(r)
168+ }
169+ if name == "" {
170+ return nil, errors.New("unknown rune")
171+ }
172+ codes, err := i.combo(name)
173+ if err != nil {
174+ return nil, err
175+ }
176+ strokes = append(strokes, codes)
177+ }
178+ var events []ports.InputEvent
179+ for _, codes := range strokes {
180+ var err error
181+ events, err = i.edges(codes, true, events)
182+ if err != nil {
183+ return nil, err
184+ }
185+ events, err = i.edges(codes, false, events)
186+ if err != nil {
187+ return nil, err
188+ }
189+ }
190+ return events, nil
191+}
192+
193+func (i *injector) Pointer(cmd string, args []string) ([]ports.InputEvent, error) {
194+ now := injectTime()
195+ if cmd == "move" {
196+ if len(args) != 2 {
197+ return nil, errors.New("move requires x y")
198+ }
199+ x, ex := strconv.ParseFloat(args[0], 64)
200+ y, ey := strconv.ParseFloat(args[1], 64)
201+ if ex != nil || ey != nil || math.IsNaN(x) || math.IsNaN(y) || math.IsInf(x, 0) || math.IsInf(y, 0) {
202+ return nil, errors.New("invalid move coordinates")
203+ }
204+ return []ports.InputEvent{i.stamp(ports.PointerMotion{Device: controlDeviceID, X: x, Y: y, Time: now}, i.snapshot())}, nil
205+ }
206+ if cmd != "click" && cmd != "down" && cmd != "up" {
207+ return nil, errors.New("unknown pointer command")
208+ }
209+ if len(args) > 1 || len(args) == 0 && cmd != "click" {
210+ return nil, errors.New("invalid button arguments")
211+ }
212+ name := "left"
213+ if len(args) == 1 {
214+ name = args[0]
215+ }
216+ var button uint32
217+ switch name {
218+ case "left":
219+ button = 0x110
220+ case "right":
221+ button = 0x111
222+ case "middle":
223+ button = 0x112
224+ default:
225+ return nil, errors.New("unknown button")
226+ }
227+ var events []ports.InputEvent
228+ if cmd != "up" {
229+ events = append(events, i.stamp(ports.PointerButton{Device: controlDeviceID, Button: button, Pressed: true, Time: now}, i.snapshot()))
230+ }
231+ if cmd != "down" {
232+ events = append(events, i.stamp(ports.PointerButton{Device: controlDeviceID, Button: button, Time: now}, i.snapshot()))
233+ }
234+ return events, nil
235+}
236+
237+func (i *injector) Swipe(fingers int, dir string) ([]ports.InputEvent, error) {
238+ if fingers != 3 && fingers != 4 {
239+ return nil, errors.New("swipe requires three or four fingers")
240+ }
241+ var dx, dy float64
242+ switch dir {
243+ case "up":
244+ dy = -40
245+ case "down":
246+ dy = 40
247+ case "left":
248+ dx = -40
249+ case "right":
250+ dx = 40
251+ default:
252+ return nil, errors.New("invalid swipe direction")
253+ }
254+ at := injectTime()
255+ events := []ports.InputEvent{i.stamp(ports.SwipeBegin{Device: controlDeviceID, Fingers: fingers, Time: at}, i.snapshot())}
256+ for range 10 {
257+ at += 8 * time.Millisecond
258+ events = append(events, i.stamp(ports.SwipeUpdate{Device: controlDeviceID, DX: dx, DY: dy, Time: at}, i.snapshot()))
259+ }
260+ return append(events, i.stamp(ports.SwipeEnd{Device: controlDeviceID, Time: at}, i.snapshot())), nil
261+}
A internal/adapters/control/inject_test.go +312 -0
@@ -0,0 +1,312 @@
1+package control
2+
3+import (
4+ "reflect"
5+ "strings"
6+ "testing"
7+ "time"
8+
9+ "github.com/bnema/neferwl/internal/adapters/xkb"
10+ "github.com/bnema/neferwl/internal/domain"
11+ portsmocks "github.com/bnema/neferwl/internal/mocks/ports"
12+ "github.com/bnema/neferwl/internal/ports"
13+)
14+
15+func injectKeymap(t *testing.T) *xkb.Keymap {
16+ t.Helper()
17+ km, err := xkb.New(xkb.RMLVO{Layout: "us"})
18+ if err != nil {
19+ if strings.Contains(err.Error(), "libxkbcommon.so.0") {
20+ t.Skip(err)
21+ }
22+ t.Fatal(err)
23+ }
24+ t.Cleanup(km.Close)
25+ return km
26+}
27+
28+func TestInjectKeys(t *testing.T) {
29+ for _, tt := range []struct {
30+ method, text string
31+ names []string
32+ codes []uint32
33+ }{
34+ {"type", "Hi!", []string{"Shift_L", "H", "H", "Shift_L", "i", "i", "Shift_L", "exclam", "exclam", "Shift_L"}, nil},
35+ {"key", "Shift+A", []string{"Shift_L", "A", "A", "Shift_L"}, []uint32{42, 30, 30, 42}},
36+ {"key", "Super+Return", []string{"Super_L", "Return", "Return", "Super_L"}, []uint32{125, 28, 28, 125}},
37+ {"press", "Super", []string{"Super_L"}, []uint32{125}},
38+ {"release", "Super", []string{"Super_L"}, []uint32{125}},
39+ {"press", "Shift", []string{"Shift_L"}, []uint32{42}},
40+ {"press", "Ctrl", []string{"Control_L"}, []uint32{29}},
41+ {"press", "Alt", []string{"Alt_L"}, []uint32{56}},
42+ } {
43+ t.Run(tt.method+tt.text, func(t *testing.T) {
44+ i := newInjector(injectKeymap(t), nil)
45+ methods := map[string]func(string) ([]ports.InputEvent, error){"type": i.Type, "key": i.Key, "press": i.Press, "release": i.Release}
46+ events, err := methods[tt.method](tt.text)
47+ if err != nil {
48+ t.Fatal(err)
49+ }
50+ if len(events) != len(tt.names) {
51+ t.Fatalf("events %v", events)
52+ }
53+ for n, raw := range events {
54+ ev := raw.(ports.KeyEvent)
55+ if ev.Device != controlDeviceID || ev.Keysym != tt.names[n] || tt.codes != nil && ev.Keycode != tt.codes[n] {
56+ t.Fatalf("event %d: %+v", n, ev)
57+ }
58+ if tt.text == "Super+Return" && (n == 1 && ev.Mods&domain.ModSuper == 0 || n == 3 && ev.Mods&domain.ModSuper != 0) {
59+ t.Fatal(ev)
60+ }
61+ }
62+ })
63+ }
64+}
65+
66+func TestInjectModifierAcrossPointer(t *testing.T) {
67+ i := newInjector(injectKeymap(t), nil)
68+ events, err := i.Press("Super")
69+ if err != nil || !events[0].(ports.KeyEvent).Pressed {
70+ t.Fatal(events, err)
71+ }
72+ for _, cmd := range []struct {
73+ name string
74+ args []string
75+ }{{"move", []string{"500", "100"}}, {"down", []string{"right"}}, {"move", []string{"700", "100"}}, {"up", []string{"right"}}} {
76+ if _, err := i.Pointer(cmd.name, cmd.args); err != nil {
77+ t.Fatal(err)
78+ }
79+ }
80+ events, err = i.Press("h")
81+ if err != nil || events[0].(ports.KeyEvent).Mods&domain.ModSuper == 0 {
82+ t.Fatal(events, err)
83+ }
84+ if _, err := i.Release("h"); err != nil {
85+ t.Fatal(err)
86+ }
87+ events, err = i.Release("Super")
88+ if err != nil || events[0].(ports.KeyEvent).Mods&domain.ModSuper != 0 {
89+ t.Fatal(events, err)
90+ }
91+ events, err = i.Press("Super+Shift+a")
92+ if err != nil || len(events) != 3 {
93+ t.Fatal(events, err)
94+ }
95+ events, err = i.Release("Super+Shift+a")
96+ if err != nil || len(events) != 3 {
97+ t.Fatal(events, err)
98+ }
99+ for n, code := range []uint32{30, 42, 125} {
100+ if ev := events[n].(ports.KeyEvent); ev.Pressed || ev.Keycode != code {
101+ t.Fatal(ev)
102+ }
103+ }
104+}
105+
106+func TestInjectPointerAndSwipe(t *testing.T) {
107+ i := newInjector(injectKeymap(t), nil)
108+ if got := i.Device(); got != (ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}) {
109+ t.Fatal(got)
110+ }
111+ events, err := i.Pointer("move", []string{"12.5", "45"})
112+ if err != nil {
113+ t.Fatal(err)
114+ }
115+ m := events[0].(ports.PointerMotion)
116+ if m.Device != controlDeviceID || m.X != 12.5 || m.Y != 45 || m.DX != 0 || m.DY != 0 {
117+ t.Fatal(m)
118+ }
119+ for _, name := range []string{"left", "right", "middle"} {
120+ var args []string
121+ if name != "left" {
122+ args = []string{name}
123+ }
124+ events, err = i.Pointer("click", args)
125+ if err != nil || len(events) != 2 {
126+ t.Fatal(events, err)
127+ }
128+ down, up := events[0].(ports.PointerButton), events[1].(ports.PointerButton)
129+ code := map[string]uint32{"left": 0x110, "right": 0x111, "middle": 0x112}[name]
130+ if down.Device != controlDeviceID || down.Button != code || !down.Pressed || up.Pressed || up.Button != code || up.Time != down.Time {
131+ t.Fatal(events)
132+ }
133+ }
134+ for _, fingers := range []int{3, 4} {
135+ for dir, delta := range map[string][2]float64{"left": {-40, 0}, "right": {40, 0}, "up": {0, -40}, "down": {0, 40}} {
136+ events, err := i.Swipe(fingers, dir)
137+ if err != nil || len(events) != 12 {
138+ t.Fatal(events, err)
139+ }
140+ begin := events[0].(ports.SwipeBegin)
141+ if begin.Device != controlDeviceID || begin.Fingers != fingers {
142+ t.Fatal(begin)
143+ }
144+ at := begin.Time
145+ for _, raw := range events[1:11] {
146+ u := raw.(ports.SwipeUpdate)
147+ if u.Device != controlDeviceID || u.DX != delta[0] || u.DY != delta[1] || u.Time-at != 8*time.Millisecond {
148+ t.Fatal(u)
149+ }
150+ at = u.Time
151+ }
152+ if end := events[11].(ports.SwipeEnd); end.Device != controlDeviceID || end.Cancelled || end.Time != at {
153+ t.Fatal(end)
154+ }
155+ }
156+ }
157+}
158+
159+func TestInjectInvalid(t *testing.T) {
160+ i := newInjector(injectKeymap(t), nil)
161+ for _, text := range []string{"", "Super+", "Unknown+a", "Super+not-a-key", "Super extra"} {
162+ for _, f := range []func(string) ([]ports.InputEvent, error){i.Key, i.Press, i.Release} {
163+ if ev, err := f(text); err == nil || len(ev) != 0 {
164+ t.Fatalf("%q: %v %v", text, ev, err)
165+ }
166+ }
167+ }
168+ if ev, err := i.Type("ok🔐"); err == nil || len(ev) != 0 {
169+ t.Fatal(ev, err)
170+ }
171+ for _, cmd := range []struct {
172+ name string
173+ args []string
174+ }{{"move", nil}, {"move", []string{"NaN", "1"}}, {"move", []string{"1", "Inf"}}, {"move", []string{"x", "2"}}, {"move", []string{"1", "2", "3"}}, {"click", []string{"bad"}}, {"down", nil}, {"up", []string{"left", "right"}}, {"bad", nil}} {
175+ if ev, err := i.Pointer(cmd.name, cmd.args); err == nil || len(ev) != 0 {
176+ t.Fatal(ev, err)
177+ }
178+ }
179+ for _, args := range []struct {
180+ f int
181+ d string
182+ }{{2, "left"}, {3, "sideways"}, {5, "up"}} {
183+ if ev, err := i.Swipe(args.f, args.d); err == nil || len(ev) != 0 {
184+ t.Fatal(ev, err)
185+ }
186+ }
187+ // Validation did not leave Super or an implicit Shift pressed.
188+ ev, err := i.Key("a")
189+ if err != nil || ev[0].(ports.KeyEvent).Mods != 0 {
190+ t.Fatal(ev, err)
191+ }
192+}
193+
194+func TestInjectSecuritySnapshots(t *testing.T) {
195+ security := portsmocks.NewMockSessionSecurity(t)
196+ state := domain.SecurityState{Generation: 7, Protected: true}
197+ security.EXPECT().Snapshot().Return(state).Maybe()
198+ i := newInjector(injectKeymap(t), security)
199+ device := i.Device().(ports.SecurityInput)
200+ if device.State != state || device.Event != (ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}) {
201+ t.Fatal(device)
202+ }
203+ var events []ports.InputEvent
204+ key, err := i.Key("A")
205+ if err != nil {
206+ t.Fatal(err)
207+ }
208+ events = append(events, key...)
209+ move, err := i.Pointer("move", []string{"10", "20"})
210+ if err != nil {
211+ t.Fatal(err)
212+ }
213+ events = append(events, move...)
214+ click, err := i.Pointer("click", nil)
215+ if err != nil {
216+ t.Fatal(err)
217+ }
218+ events = append(events, click...)
219+ swipe, err := i.Swipe(3, "left")
220+ if err != nil {
221+ t.Fatal(err)
222+ }
223+ events = append(events, swipe...)
224+ for _, raw := range events {
225+ ev, ok := raw.(ports.SecurityInput)
226+ if !ok || ev.State != state || reflect.ValueOf(ev.Event).FieldByName("Device").Uint() != uint64(controlDeviceID) {
227+ t.Fatal(raw)
228+ }
229+ }
230+}
231+
232+func TestInjectSecurityQuarantine(t *testing.T) {
233+ km := injectKeymap(t)
234+ security := portsmocks.NewMockSessionSecurity(t)
235+ initial := domain.SecurityState{}
236+ locked := domain.SecurityState{Generation: 1, Protected: true}
237+ security.EXPECT().Snapshot().Return(initial).Once()
238+ i := newInjector(km, security)
239+ if _, err := i.Press("Super"); err != nil {
240+ t.Fatal(err)
241+ }
242+ security.EXPECT().Snapshot().Return(locked).Times(5)
243+ events, err := i.Key("q")
244+ if err != nil {
245+ t.Fatal(err)
246+ }
247+ for _, raw := range events {
248+ if ev := raw.(ports.SecurityInput).Event.(ports.KeyEvent); ev.Mods&domain.ModSuper != 0 {
249+ t.Fatal(ev)
250+ }
251+ }
252+ events, err = i.Release("Super")
253+ if err != nil || len(events) != 0 {
254+ t.Fatal("held modifier was not quarantined", events, err)
255+ }
256+ events, err = i.Key("q")
257+ if err != nil || len(events) != 2 {
258+ t.Fatal(events, err)
259+ }
260+}
261+
262+func TestInjectPunctuation(t *testing.T) {
263+ i := newInjector(injectKeymap(t), nil)
264+ for r := range injectPunctuation {
265+ events, err := i.Type(string(r))
266+ if err != nil || len(events) < 2 {
267+ t.Fatalf("rune %q: %v %v", r, events, err)
268+ }
269+ }
270+ if events, err := i.Type(""); err != nil || len(events) != 0 {
271+ t.Fatal(events, err)
272+ }
273+}
274+
275+func TestInjectSecuritySnapshotBeforeTranslation(t *testing.T) {
276+ km := injectKeymap(t)
277+ security := portsmocks.NewMockSessionSecurity(t)
278+ initial := domain.SecurityState{}
279+ locked := domain.SecurityState{Generation: 1, Protected: true}
280+ security.EXPECT().Snapshot().Return(initial).Once()
281+ i := newInjector(km, security)
282+ if _, err := i.Press("Super"); err != nil {
283+ t.Fatal(err)
284+ }
285+ // The epoch changes between the key's press and release. The release is
286+ // quarantined, rather than translated using the previous modifier state.
287+ security.EXPECT().Snapshot().Return(initial).Once()
288+ security.EXPECT().Snapshot().Return(locked).Once()
289+ events, err := i.Key("q")
290+ if err != nil || len(events) != 1 {
291+ t.Fatal(events, err)
292+ }
293+ ev := events[0].(ports.SecurityInput)
294+ if ev.State != initial || ev.Event.(ports.KeyEvent).Mods&domain.ModSuper == 0 {
295+ t.Fatal(ev)
296+ }
297+ security.EXPECT().Snapshot().Return(locked).Times(3)
298+ events, err = i.Release("Super")
299+ if err != nil || len(events) != 0 {
300+ t.Fatal(events, err)
301+ }
302+ events, err = i.Key("q")
303+ if err != nil || len(events) != 2 {
304+ t.Fatal(events, err)
305+ }
306+ for _, raw := range events {
307+ ev := raw.(ports.SecurityInput)
308+ if ev.State != locked || ev.Event.(ports.KeyEvent).Mods&domain.ModSuper != 0 {
309+ t.Fatal(ev)
310+ }
311+ }
312+}
@@ -0,0 +1,312 @@
1+package control
2+
3+import (
4+ "reflect"
5+ "strings"
6+ "testing"
7+ "time"
8+
9+ "github.com/bnema/neferwl/internal/adapters/xkb"
10+ "github.com/bnema/neferwl/internal/domain"
11+ portsmocks "github.com/bnema/neferwl/internal/mocks/ports"
12+ "github.com/bnema/neferwl/internal/ports"
13+)
14+
15+func injectKeymap(t *testing.T) *xkb.Keymap {
16+ t.Helper()
17+ km, err := xkb.New(xkb.RMLVO{Layout: "us"})
18+ if err != nil {
19+ if strings.Contains(err.Error(), "libxkbcommon.so.0") {
20+ t.Skip(err)
21+ }
22+ t.Fatal(err)
23+ }
24+ t.Cleanup(km.Close)
25+ return km
26+}
27+
28+func TestInjectKeys(t *testing.T) {
29+ for _, tt := range []struct {
30+ method, text string
31+ names []string
32+ codes []uint32
33+ }{
34+ {"type", "Hi!", []string{"Shift_L", "H", "H", "Shift_L", "i", "i", "Shift_L", "exclam", "exclam", "Shift_L"}, nil},
35+ {"key", "Shift+A", []string{"Shift_L", "A", "A", "Shift_L"}, []uint32{42, 30, 30, 42}},
36+ {"key", "Super+Return", []string{"Super_L", "Return", "Return", "Super_L"}, []uint32{125, 28, 28, 125}},
37+ {"press", "Super", []string{"Super_L"}, []uint32{125}},
38+ {"release", "Super", []string{"Super_L"}, []uint32{125}},
39+ {"press", "Shift", []string{"Shift_L"}, []uint32{42}},
40+ {"press", "Ctrl", []string{"Control_L"}, []uint32{29}},
41+ {"press", "Alt", []string{"Alt_L"}, []uint32{56}},
42+ } {
43+ t.Run(tt.method+tt.text, func(t *testing.T) {
44+ i := newInjector(injectKeymap(t), nil)
45+ methods := map[string]func(string) ([]ports.InputEvent, error){"type": i.Type, "key": i.Key, "press": i.Press, "release": i.Release}
46+ events, err := methods[tt.method](tt.text)
47+ if err != nil {
48+ t.Fatal(err)
49+ }
50+ if len(events) != len(tt.names) {
51+ t.Fatalf("events %v", events)
52+ }
53+ for n, raw := range events {
54+ ev := raw.(ports.KeyEvent)
55+ if ev.Device != controlDeviceID || ev.Keysym != tt.names[n] || tt.codes != nil && ev.Keycode != tt.codes[n] {
56+ t.Fatalf("event %d: %+v", n, ev)
57+ }
58+ if tt.text == "Super+Return" && (n == 1 && ev.Mods&domain.ModSuper == 0 || n == 3 && ev.Mods&domain.ModSuper != 0) {
59+ t.Fatal(ev)
60+ }
61+ }
62+ })
63+ }
64+}
65+
66+func TestInjectModifierAcrossPointer(t *testing.T) {
67+ i := newInjector(injectKeymap(t), nil)
68+ events, err := i.Press("Super")
69+ if err != nil || !events[0].(ports.KeyEvent).Pressed {
70+ t.Fatal(events, err)
71+ }
72+ for _, cmd := range []struct {
73+ name string
74+ args []string
75+ }{{"move", []string{"500", "100"}}, {"down", []string{"right"}}, {"move", []string{"700", "100"}}, {"up", []string{"right"}}} {
76+ if _, err := i.Pointer(cmd.name, cmd.args); err != nil {
77+ t.Fatal(err)
78+ }
79+ }
80+ events, err = i.Press("h")
81+ if err != nil || events[0].(ports.KeyEvent).Mods&domain.ModSuper == 0 {
82+ t.Fatal(events, err)
83+ }
84+ if _, err := i.Release("h"); err != nil {
85+ t.Fatal(err)
86+ }
87+ events, err = i.Release("Super")
88+ if err != nil || events[0].(ports.KeyEvent).Mods&domain.ModSuper != 0 {
89+ t.Fatal(events, err)
90+ }
91+ events, err = i.Press("Super+Shift+a")
92+ if err != nil || len(events) != 3 {
93+ t.Fatal(events, err)
94+ }
95+ events, err = i.Release("Super+Shift+a")
96+ if err != nil || len(events) != 3 {
97+ t.Fatal(events, err)
98+ }
99+ for n, code := range []uint32{30, 42, 125} {
100+ if ev := events[n].(ports.KeyEvent); ev.Pressed || ev.Keycode != code {
101+ t.Fatal(ev)
102+ }
103+ }
104+}
105+
106+func TestInjectPointerAndSwipe(t *testing.T) {
107+ i := newInjector(injectKeymap(t), nil)
108+ if got := i.Device(); got != (ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}) {
109+ t.Fatal(got)
110+ }
111+ events, err := i.Pointer("move", []string{"12.5", "45"})
112+ if err != nil {
113+ t.Fatal(err)
114+ }
115+ m := events[0].(ports.PointerMotion)
116+ if m.Device != controlDeviceID || m.X != 12.5 || m.Y != 45 || m.DX != 0 || m.DY != 0 {
117+ t.Fatal(m)
118+ }
119+ for _, name := range []string{"left", "right", "middle"} {
120+ var args []string
121+ if name != "left" {
122+ args = []string{name}
123+ }
124+ events, err = i.Pointer("click", args)
125+ if err != nil || len(events) != 2 {
126+ t.Fatal(events, err)
127+ }
128+ down, up := events[0].(ports.PointerButton), events[1].(ports.PointerButton)
129+ code := map[string]uint32{"left": 0x110, "right": 0x111, "middle": 0x112}[name]
130+ if down.Device != controlDeviceID || down.Button != code || !down.Pressed || up.Pressed || up.Button != code || up.Time != down.Time {
131+ t.Fatal(events)
132+ }
133+ }
134+ for _, fingers := range []int{3, 4} {
135+ for dir, delta := range map[string][2]float64{"left": {-40, 0}, "right": {40, 0}, "up": {0, -40}, "down": {0, 40}} {
136+ events, err := i.Swipe(fingers, dir)
137+ if err != nil || len(events) != 12 {
138+ t.Fatal(events, err)
139+ }
140+ begin := events[0].(ports.SwipeBegin)
141+ if begin.Device != controlDeviceID || begin.Fingers != fingers {
142+ t.Fatal(begin)
143+ }
144+ at := begin.Time
145+ for _, raw := range events[1:11] {
146+ u := raw.(ports.SwipeUpdate)
147+ if u.Device != controlDeviceID || u.DX != delta[0] || u.DY != delta[1] || u.Time-at != 8*time.Millisecond {
148+ t.Fatal(u)
149+ }
150+ at = u.Time
151+ }
152+ if end := events[11].(ports.SwipeEnd); end.Device != controlDeviceID || end.Cancelled || end.Time != at {
153+ t.Fatal(end)
154+ }
155+ }
156+ }
157+}
158+
159+func TestInjectInvalid(t *testing.T) {
160+ i := newInjector(injectKeymap(t), nil)
161+ for _, text := range []string{"", "Super+", "Unknown+a", "Super+not-a-key", "Super extra"} {
162+ for _, f := range []func(string) ([]ports.InputEvent, error){i.Key, i.Press, i.Release} {
163+ if ev, err := f(text); err == nil || len(ev) != 0 {
164+ t.Fatalf("%q: %v %v", text, ev, err)
165+ }
166+ }
167+ }
168+ if ev, err := i.Type("ok🔐"); err == nil || len(ev) != 0 {
169+ t.Fatal(ev, err)
170+ }
171+ for _, cmd := range []struct {
172+ name string
173+ args []string
174+ }{{"move", nil}, {"move", []string{"NaN", "1"}}, {"move", []string{"1", "Inf"}}, {"move", []string{"x", "2"}}, {"move", []string{"1", "2", "3"}}, {"click", []string{"bad"}}, {"down", nil}, {"up", []string{"left", "right"}}, {"bad", nil}} {
175+ if ev, err := i.Pointer(cmd.name, cmd.args); err == nil || len(ev) != 0 {
176+ t.Fatal(ev, err)
177+ }
178+ }
179+ for _, args := range []struct {
180+ f int
181+ d string
182+ }{{2, "left"}, {3, "sideways"}, {5, "up"}} {
183+ if ev, err := i.Swipe(args.f, args.d); err == nil || len(ev) != 0 {
184+ t.Fatal(ev, err)
185+ }
186+ }
187+ // Validation did not leave Super or an implicit Shift pressed.
188+ ev, err := i.Key("a")
189+ if err != nil || ev[0].(ports.KeyEvent).Mods != 0 {
190+ t.Fatal(ev, err)
191+ }
192+}
193+
194+func TestInjectSecuritySnapshots(t *testing.T) {
195+ security := portsmocks.NewMockSessionSecurity(t)
196+ state := domain.SecurityState{Generation: 7, Protected: true}
197+ security.EXPECT().Snapshot().Return(state).Maybe()
198+ i := newInjector(injectKeymap(t), security)
199+ device := i.Device().(ports.SecurityInput)
200+ if device.State != state || device.Event != (ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}) {
201+ t.Fatal(device)
202+ }
203+ var events []ports.InputEvent
204+ key, err := i.Key("A")
205+ if err != nil {
206+ t.Fatal(err)
207+ }
208+ events = append(events, key...)
209+ move, err := i.Pointer("move", []string{"10", "20"})
210+ if err != nil {
211+ t.Fatal(err)
212+ }
213+ events = append(events, move...)
214+ click, err := i.Pointer("click", nil)
215+ if err != nil {
216+ t.Fatal(err)
217+ }
218+ events = append(events, click...)
219+ swipe, err := i.Swipe(3, "left")
220+ if err != nil {
221+ t.Fatal(err)
222+ }
223+ events = append(events, swipe...)
224+ for _, raw := range events {
225+ ev, ok := raw.(ports.SecurityInput)
226+ if !ok || ev.State != state || reflect.ValueOf(ev.Event).FieldByName("Device").Uint() != uint64(controlDeviceID) {
227+ t.Fatal(raw)
228+ }
229+ }
230+}
231+
232+func TestInjectSecurityQuarantine(t *testing.T) {
233+ km := injectKeymap(t)
234+ security := portsmocks.NewMockSessionSecurity(t)
235+ initial := domain.SecurityState{}
236+ locked := domain.SecurityState{Generation: 1, Protected: true}
237+ security.EXPECT().Snapshot().Return(initial).Once()
238+ i := newInjector(km, security)
239+ if _, err := i.Press("Super"); err != nil {
240+ t.Fatal(err)
241+ }
242+ security.EXPECT().Snapshot().Return(locked).Times(5)
243+ events, err := i.Key("q")
244+ if err != nil {
245+ t.Fatal(err)
246+ }
247+ for _, raw := range events {
248+ if ev := raw.(ports.SecurityInput).Event.(ports.KeyEvent); ev.Mods&domain.ModSuper != 0 {
249+ t.Fatal(ev)
250+ }
251+ }
252+ events, err = i.Release("Super")
253+ if err != nil || len(events) != 0 {
254+ t.Fatal("held modifier was not quarantined", events, err)
255+ }
256+ events, err = i.Key("q")
257+ if err != nil || len(events) != 2 {
258+ t.Fatal(events, err)
259+ }
260+}
261+
262+func TestInjectPunctuation(t *testing.T) {
263+ i := newInjector(injectKeymap(t), nil)
264+ for r := range injectPunctuation {
265+ events, err := i.Type(string(r))
266+ if err != nil || len(events) < 2 {
267+ t.Fatalf("rune %q: %v %v", r, events, err)
268+ }
269+ }
270+ if events, err := i.Type(""); err != nil || len(events) != 0 {
271+ t.Fatal(events, err)
272+ }
273+}
274+
275+func TestInjectSecuritySnapshotBeforeTranslation(t *testing.T) {
276+ km := injectKeymap(t)
277+ security := portsmocks.NewMockSessionSecurity(t)
278+ initial := domain.SecurityState{}
279+ locked := domain.SecurityState{Generation: 1, Protected: true}
280+ security.EXPECT().Snapshot().Return(initial).Once()
281+ i := newInjector(km, security)
282+ if _, err := i.Press("Super"); err != nil {
283+ t.Fatal(err)
284+ }
285+ // The epoch changes between the key's press and release. The release is
286+ // quarantined, rather than translated using the previous modifier state.
287+ security.EXPECT().Snapshot().Return(initial).Once()
288+ security.EXPECT().Snapshot().Return(locked).Once()
289+ events, err := i.Key("q")
290+ if err != nil || len(events) != 1 {
291+ t.Fatal(events, err)
292+ }
293+ ev := events[0].(ports.SecurityInput)
294+ if ev.State != initial || ev.Event.(ports.KeyEvent).Mods&domain.ModSuper == 0 {
295+ t.Fatal(ev)
296+ }
297+ security.EXPECT().Snapshot().Return(locked).Times(3)
298+ events, err = i.Release("Super")
299+ if err != nil || len(events) != 0 {
300+ t.Fatal(events, err)
301+ }
302+ events, err = i.Key("q")
303+ if err != nil || len(events) != 2 {
304+ t.Fatal(events, err)
305+ }
306+ for _, raw := range events {
307+ ev := raw.(ports.SecurityInput)
308+ if ev.State != locked || ev.Event.(ports.KeyEvent).Mods&domain.ModSuper != 0 {
309+ t.Fatal(ev)
310+ }
311+ }
312+}
A internal/adapters/control/inject_wire.go +75 -0
@@ -0,0 +1,75 @@
1+package control
2+
3+import (
4+ "errors"
5+
6+ "github.com/bnema/neferwl/internal/ports"
7+)
8+
9+// translate serializes XKB access across connections and keymap reloads. The
10+// output batch is immutable; core receives it through the normal control port.
11+func (s *Server) translate(req request, announce bool) ([]ports.InputEvent, error) {
12+ s.injectMu.Lock()
13+ defer s.injectMu.Unlock()
14+ select {
15+ case <-s.done:
16+ return nil, errors.New("control closed")
17+ default:
18+ }
19+ if s.injector == nil {
20+ return nil, errors.New("input unavailable")
21+ }
22+ for s.keymaps != nil {
23+ select {
24+ case next, ok := <-s.keymaps:
25+ if !ok {
26+ s.keymaps = nil
27+ continue
28+ }
29+ if next == nil {
30+ continue
31+ }
32+ previous := s.injector.km
33+ if s.injector.security != nil {
34+ next.QuarantineFrom(previous)
35+ }
36+ s.injector.km = next
37+ previous.Close()
38+ default:
39+ goto ready
40+ }
41+ }
42+ready:
43+ i := s.injector
44+ var events []ports.InputEvent
45+ var err error
46+ // Snapshot an announcement before translating the first event, but don't
47+ // deliver it or consume the connection's announcement on validation failure.
48+ var device ports.InputEvent
49+ if announce {
50+ device = i.Device()
51+ }
52+ switch req.Kind {
53+ case "key":
54+ events, err = i.Key(req.Combo)
55+ case "type":
56+ events, err = i.Type(req.Text)
57+ case "press":
58+ events, err = i.Press(req.Combo)
59+ case "release":
60+ events, err = i.Release(req.Combo)
61+ case "pointer":
62+ events, err = i.Pointer(req.Cmd, req.Args)
63+ case "swipe":
64+ events, err = i.Swipe(req.Fingers, req.Dir)
65+ default:
66+ return nil, errors.New("unknown injection kind")
67+ }
68+ if err != nil {
69+ return nil, err
70+ }
71+ if announce {
72+ events = append([]ports.InputEvent{device}, events...)
73+ }
74+ return events, nil
75+}
@@ -0,0 +1,75 @@
1+package control
2+
3+import (
4+ "errors"
5+
6+ "github.com/bnema/neferwl/internal/ports"
7+)
8+
9+// translate serializes XKB access across connections and keymap reloads. The
10+// output batch is immutable; core receives it through the normal control port.
11+func (s *Server) translate(req request, announce bool) ([]ports.InputEvent, error) {
12+ s.injectMu.Lock()
13+ defer s.injectMu.Unlock()
14+ select {
15+ case <-s.done:
16+ return nil, errors.New("control closed")
17+ default:
18+ }
19+ if s.injector == nil {
20+ return nil, errors.New("input unavailable")
21+ }
22+ for s.keymaps != nil {
23+ select {
24+ case next, ok := <-s.keymaps:
25+ if !ok {
26+ s.keymaps = nil
27+ continue
28+ }
29+ if next == nil {
30+ continue
31+ }
32+ previous := s.injector.km
33+ if s.injector.security != nil {
34+ next.QuarantineFrom(previous)
35+ }
36+ s.injector.km = next
37+ previous.Close()
38+ default:
39+ goto ready
40+ }
41+ }
42+ready:
43+ i := s.injector
44+ var events []ports.InputEvent
45+ var err error
46+ // Snapshot an announcement before translating the first event, but don't
47+ // deliver it or consume the connection's announcement on validation failure.
48+ var device ports.InputEvent
49+ if announce {
50+ device = i.Device()
51+ }
52+ switch req.Kind {
53+ case "key":
54+ events, err = i.Key(req.Combo)
55+ case "type":
56+ events, err = i.Type(req.Text)
57+ case "press":
58+ events, err = i.Press(req.Combo)
59+ case "release":
60+ events, err = i.Release(req.Combo)
61+ case "pointer":
62+ events, err = i.Pointer(req.Cmd, req.Args)
63+ case "swipe":
64+ events, err = i.Swipe(req.Fingers, req.Dir)
65+ default:
66+ return nil, errors.New("unknown injection kind")
67+ }
68+ if err != nil {
69+ return nil, err
70+ }
71+ if announce {
72+ events = append([]ports.InputEvent{device}, events...)
73+ }
74+ return events, nil
75+}
A internal/adapters/control/inject_wire_test.go +169 -0
@@ -0,0 +1,169 @@
1+package control
2+
3+import (
4+ "context"
5+ "encoding/json"
6+ "net"
7+ "path/filepath"
8+ "testing"
9+ "testing/synctest"
10+ "time"
11+
12+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
13+ "github.com/bnema/neferwl/internal/adapters/xkb"
14+ "github.com/bnema/neferwl/internal/domain"
15+ portsmocks "github.com/bnema/neferwl/internal/mocks/ports"
16+ "github.com/bnema/neferwl/internal/ports"
17+)
18+
19+//testpolicy:realtime real Unix control socket exchanges and shutdown
20+func TestInjectProtocol(t *testing.T) {
21+ km := injectKeymap(t)
22+ security := portsmocks.NewMockSessionSecurity(t)
23+ state := domain.SecurityState{Generation: 7}
24+ security.EXPECT().Snapshot().Return(state)
25+ updates := make(chan *xkb.Keymap, 1)
26+ path := filepath.Join(t.TempDir(), "control.sock")
27+ s, err := Listen(path, workspaceid.WithPrefix("inject"), Options{Keymap: km, Keymaps: updates, Security: security})
28+ if err != nil {
29+ t.Fatal(err)
30+ }
31+ defer s.Close()
32+ ctx, cancel := context.WithCancel(context.Background())
33+ defer cancel()
34+ out := make(chan ports.ControlRequest, 1)
35+ done := make(chan error, 1)
36+ go func() { done <- s.Run(ctx, out) }()
37+ connect := func() net.Conn {
38+ t.Helper()
39+ c, err := net.Dial("unix", path)
40+ if err != nil {
41+ t.Fatal(err)
42+ }
43+ t.Cleanup(func() { c.Close() })
44+ if err := c.SetDeadline(time.Now().Add(5 * time.Second)); err != nil {
45+ t.Fatal(err)
46+ }
47+ return c
48+ }
49+ conn := connect()
50+ enc, dec := json.NewEncoder(conn), json.NewDecoder(conn)
51+ for _, req := range []map[string]any{
52+ {"kind": "key", "combo": "bad-key"}, {"kind": "unknown"}, {"kind": "key", "combo": "a", "wait": "bad"}, {"kind": "swipe", "fingers": 3, "dir": "bad"},
53+ } {
54+ req["id"], req["op"] = 1, "inject"
55+ if err := enc.Encode(req); err != nil {
56+ t.Fatal(err)
57+ }
58+ var response reply
59+ if err := dec.Decode(&response); err != nil || response.Error != ports.ControlErrBadRequest {
60+ t.Fatal(response, err)
61+ }
62+ }
63+ exchange := func(conn net.Conn, req map[string]any, announcement bool) []ports.InputEvent {
64+ t.Helper()
65+ req["id"], req["op"] = 2, "inject"
66+ if err := json.NewEncoder(conn).Encode(req); err != nil {
67+ t.Fatal(err)
68+ }
69+ var message ports.ControlInject
70+ select {
71+ case raw := <-out:
72+ var ok bool
73+ message, ok = raw.(ports.ControlInject)
74+ if !ok {
75+ t.Fatalf("request %T", raw)
76+ }
77+ case <-time.After(5 * time.Second):
78+ t.Fatal("missing injection")
79+ }
80+ if message.Caps != domain.CapsAll || cap(message.Reply) != 1 {
81+ t.Fatal(message)
82+ }
83+ events := message.Events
84+ for _, raw := range events {
85+ if ev, ok := raw.(ports.SecurityInput); !ok || ev.State != state {
86+ t.Fatal(raw)
87+ }
88+ }
89+ if announcement {
90+ if ev := events[0].(ports.SecurityInput).Event; ev != (ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}) {
91+ t.Fatal(ev)
92+ }
93+ events = events[1:]
94+ } else {
95+ if _, ok := events[0].(ports.SecurityInput).Event.(ports.InputDeviceAdded); ok {
96+ t.Fatal("duplicate announcement")
97+ }
98+ }
99+ if req["wait"] != nil {
100+ if message.Wait != domain.WaitPresented || message.Until == nil || message.Until.AppID != "foot" || message.Timeout != 2*time.Second {
101+ t.Fatal(message)
102+ }
103+ } else if message.Wait != domain.DefaultWait || message.Until != nil || message.Timeout != 10*time.Second {
104+ t.Fatal(message)
105+ }
106+ message.Reply <- ports.ControlReply{Done: domain.WaitCommitted}
107+ var response reply
108+ if err := json.NewDecoder(conn).Decode(&response); err != nil || !response.OK {
109+ t.Fatal(response, err)
110+ }
111+ return events
112+ }
113+ events := exchange(conn, map[string]any{"kind": "press", "combo": "Super", "wait": "presented", "until": "focused app_id=foot", "timeout": "2s"}, true)
114+ if len(events) != 1 || !events[0].(ports.SecurityInput).Event.(ports.KeyEvent).Pressed {
115+ t.Fatal(events)
116+ }
117+ // A newly received map takes over held-key tracking, quarantining release.
118+ next := injectKeymap(t)
119+ updates <- next
120+ events = exchange(conn, map[string]any{"kind": "key", "combo": "q"}, false)
121+ for _, raw := range events {
122+ if ev := raw.(ports.SecurityInput).Event.(ports.KeyEvent); ev.Mods&domain.ModSuper != 0 {
123+ t.Fatal(ev)
124+ }
125+ }
126+ // Other kinds share the same request port and first-inject bookkeeping.
127+ for _, req := range []map[string]any{
128+ {"kind": "type", "text": "Hi!"}, {"kind": "pointer", "cmd": "click"}, {"kind": "swipe", "fingers": 4, "dir": "up"}, {"kind": "release", "combo": "a"},
129+ } {
130+ exchange(conn, req, false)
131+ }
132+ other := connect()
133+ exchange(other, map[string]any{"kind": "key", "combo": "Return"}, true)
134+ // Both clients remain open: shutdown must interrupt their blocked scanners.
135+ cancel()
136+ select {
137+ case err := <-done:
138+ if err != nil {
139+ t.Fatal(err)
140+ }
141+ case <-time.After(5 * time.Second):
142+ t.Fatal("open-client shutdown hung")
143+ }
144+}
145+
146+// The device announcement repeats until core accepts a batch: a refused
147+// (locked) batch never reached the input path.
148+func TestInjectAnnouncesUntilAccepted(t *testing.T) {
149+ synctest.Test(t, func(t *testing.T) {
150+ s := &Server{ids: workspaceid.WithPrefix("inject"), done: make(chan struct{}), injector: newInjector(injectKeymap(t), nil)}
151+ out := make(chan ports.ControlRequest)
152+ announced := false
153+ for _, refuse := range []string{ports.ControlErrLocked, "", ""} {
154+ go func() {
155+ r := (<-out).(ports.ControlInject)
156+ _, first := r.Events[0].(ports.InputDeviceAdded)
157+ if first == announced {
158+ t.Errorf("announcement sent=%v after announced=%v", first, announced)
159+ }
160+ r.Reply <- ports.ControlReply{Err: refuse}
161+ }()
162+ s.dispatch(context.Background(), request{Op: "inject", Kind: "key", Combo: "a"}, out, &announced)
163+ synctest.Wait()
164+ if announced != (refuse == "") {
165+ t.Fatalf("announced=%v after %q", announced, refuse)
166+ }
167+ }
168+ })
169+}
@@ -0,0 +1,169 @@
1+package control
2+
3+import (
4+ "context"
5+ "encoding/json"
6+ "net"
7+ "path/filepath"
8+ "testing"
9+ "testing/synctest"
10+ "time"
11+
12+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
13+ "github.com/bnema/neferwl/internal/adapters/xkb"
14+ "github.com/bnema/neferwl/internal/domain"
15+ portsmocks "github.com/bnema/neferwl/internal/mocks/ports"
16+ "github.com/bnema/neferwl/internal/ports"
17+)
18+
19+//testpolicy:realtime real Unix control socket exchanges and shutdown
20+func TestInjectProtocol(t *testing.T) {
21+ km := injectKeymap(t)
22+ security := portsmocks.NewMockSessionSecurity(t)
23+ state := domain.SecurityState{Generation: 7}
24+ security.EXPECT().Snapshot().Return(state)
25+ updates := make(chan *xkb.Keymap, 1)
26+ path := filepath.Join(t.TempDir(), "control.sock")
27+ s, err := Listen(path, workspaceid.WithPrefix("inject"), Options{Keymap: km, Keymaps: updates, Security: security})
28+ if err != nil {
29+ t.Fatal(err)
30+ }
31+ defer s.Close()
32+ ctx, cancel := context.WithCancel(context.Background())
33+ defer cancel()
34+ out := make(chan ports.ControlRequest, 1)
35+ done := make(chan error, 1)
36+ go func() { done <- s.Run(ctx, out) }()
37+ connect := func() net.Conn {
38+ t.Helper()
39+ c, err := net.Dial("unix", path)
40+ if err != nil {
41+ t.Fatal(err)
42+ }
43+ t.Cleanup(func() { c.Close() })
44+ if err := c.SetDeadline(time.Now().Add(5 * time.Second)); err != nil {
45+ t.Fatal(err)
46+ }
47+ return c
48+ }
49+ conn := connect()
50+ enc, dec := json.NewEncoder(conn), json.NewDecoder(conn)
51+ for _, req := range []map[string]any{
52+ {"kind": "key", "combo": "bad-key"}, {"kind": "unknown"}, {"kind": "key", "combo": "a", "wait": "bad"}, {"kind": "swipe", "fingers": 3, "dir": "bad"},
53+ } {
54+ req["id"], req["op"] = 1, "inject"
55+ if err := enc.Encode(req); err != nil {
56+ t.Fatal(err)
57+ }
58+ var response reply
59+ if err := dec.Decode(&response); err != nil || response.Error != ports.ControlErrBadRequest {
60+ t.Fatal(response, err)
61+ }
62+ }
63+ exchange := func(conn net.Conn, req map[string]any, announcement bool) []ports.InputEvent {
64+ t.Helper()
65+ req["id"], req["op"] = 2, "inject"
66+ if err := json.NewEncoder(conn).Encode(req); err != nil {
67+ t.Fatal(err)
68+ }
69+ var message ports.ControlInject
70+ select {
71+ case raw := <-out:
72+ var ok bool
73+ message, ok = raw.(ports.ControlInject)
74+ if !ok {
75+ t.Fatalf("request %T", raw)
76+ }
77+ case <-time.After(5 * time.Second):
78+ t.Fatal("missing injection")
79+ }
80+ if message.Caps != domain.CapsAll || cap(message.Reply) != 1 {
81+ t.Fatal(message)
82+ }
83+ events := message.Events
84+ for _, raw := range events {
85+ if ev, ok := raw.(ports.SecurityInput); !ok || ev.State != state {
86+ t.Fatal(raw)
87+ }
88+ }
89+ if announcement {
90+ if ev := events[0].(ports.SecurityInput).Event; ev != (ports.InputDeviceAdded{ID: controlDeviceID, Name: "control"}) {
91+ t.Fatal(ev)
92+ }
93+ events = events[1:]
94+ } else {
95+ if _, ok := events[0].(ports.SecurityInput).Event.(ports.InputDeviceAdded); ok {
96+ t.Fatal("duplicate announcement")
97+ }
98+ }
99+ if req["wait"] != nil {
100+ if message.Wait != domain.WaitPresented || message.Until == nil || message.Until.AppID != "foot" || message.Timeout != 2*time.Second {
101+ t.Fatal(message)
102+ }
103+ } else if message.Wait != domain.DefaultWait || message.Until != nil || message.Timeout != 10*time.Second {
104+ t.Fatal(message)
105+ }
106+ message.Reply <- ports.ControlReply{Done: domain.WaitCommitted}
107+ var response reply
108+ if err := json.NewDecoder(conn).Decode(&response); err != nil || !response.OK {
109+ t.Fatal(response, err)
110+ }
111+ return events
112+ }
113+ events := exchange(conn, map[string]any{"kind": "press", "combo": "Super", "wait": "presented", "until": "focused app_id=foot", "timeout": "2s"}, true)
114+ if len(events) != 1 || !events[0].(ports.SecurityInput).Event.(ports.KeyEvent).Pressed {
115+ t.Fatal(events)
116+ }
117+ // A newly received map takes over held-key tracking, quarantining release.
118+ next := injectKeymap(t)
119+ updates <- next
120+ events = exchange(conn, map[string]any{"kind": "key", "combo": "q"}, false)
121+ for _, raw := range events {
122+ if ev := raw.(ports.SecurityInput).Event.(ports.KeyEvent); ev.Mods&domain.ModSuper != 0 {
123+ t.Fatal(ev)
124+ }
125+ }
126+ // Other kinds share the same request port and first-inject bookkeeping.
127+ for _, req := range []map[string]any{
128+ {"kind": "type", "text": "Hi!"}, {"kind": "pointer", "cmd": "click"}, {"kind": "swipe", "fingers": 4, "dir": "up"}, {"kind": "release", "combo": "a"},
129+ } {
130+ exchange(conn, req, false)
131+ }
132+ other := connect()
133+ exchange(other, map[string]any{"kind": "key", "combo": "Return"}, true)
134+ // Both clients remain open: shutdown must interrupt their blocked scanners.
135+ cancel()
136+ select {
137+ case err := <-done:
138+ if err != nil {
139+ t.Fatal(err)
140+ }
141+ case <-time.After(5 * time.Second):
142+ t.Fatal("open-client shutdown hung")
143+ }
144+}
145+
146+// The device announcement repeats until core accepts a batch: a refused
147+// (locked) batch never reached the input path.
148+func TestInjectAnnouncesUntilAccepted(t *testing.T) {
149+ synctest.Test(t, func(t *testing.T) {
150+ s := &Server{ids: workspaceid.WithPrefix("inject"), done: make(chan struct{}), injector: newInjector(injectKeymap(t), nil)}
151+ out := make(chan ports.ControlRequest)
152+ announced := false
153+ for _, refuse := range []string{ports.ControlErrLocked, "", ""} {
154+ go func() {
155+ r := (<-out).(ports.ControlInject)
156+ _, first := r.Events[0].(ports.InputDeviceAdded)
157+ if first == announced {
158+ t.Errorf("announcement sent=%v after announced=%v", first, announced)
159+ }
160+ r.Reply <- ports.ControlReply{Err: refuse}
161+ }()
162+ s.dispatch(context.Background(), request{Op: "inject", Kind: "key", Combo: "a"}, out, &announced)
163+ synctest.Wait()
164+ if announced != (refuse == "") {
165+ t.Fatalf("announced=%v after %q", announced, refuse)
166+ }
167+ }
168+ })
169+}
A internal/adapters/control/output_test.go +38 -0
@@ -0,0 +1,38 @@
1+package control
2+
3+import (
4+ "context"
5+ "encoding/json"
6+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
7+ "github.com/bnema/neferwl/internal/domain"
8+ "github.com/bnema/neferwl/internal/ports"
9+ "testing"
10+ "testing/synctest"
11+)
12+
13+func TestOutputDispatch(t *testing.T) {
14+ synctest.Test(t, func(t *testing.T) {
15+ s := &Server{ids: workspaceid.WithPrefix("test")}
16+ out := make(chan ports.ControlRequest)
17+ for _, wire := range []string{`{"op":"output-add","mode":"1920x1080@60","name":"X"}`, `{"op":"output-rm","name":"X"}`} {
18+ var req request
19+ json.Unmarshal([]byte(wire), &req)
20+ go func() {
21+ r := (<-out).(ports.ControlOutput)
22+ if r.Name != "X" || r.Caps != domain.CapsAll || r.Remove != (req.Op == "output-rm") {
23+ t.Error(r)
24+ }
25+ r.Reply <- ports.ControlReply{}
26+ }()
27+ announced := false
28+ if r := s.dispatch(context.Background(), req, out, &announced); !r.OK {
29+ t.Fatal(r)
30+ }
31+ }
32+ for _, mode := range []string{"bad", "0x2", "2x3@NaN", "2x3@Inf"} {
33+ if _, err := domain.ParseOutputMode(mode); err == nil {
34+ t.Fatal(mode)
35+ }
36+ }
37+ })
38+}
@@ -0,0 +1,38 @@
1+package control
2+
3+import (
4+ "context"
5+ "encoding/json"
6+ "github.com/bnema/neferwl/internal/adapters/workspaceid"
7+ "github.com/bnema/neferwl/internal/domain"
8+ "github.com/bnema/neferwl/internal/ports"
9+ "testing"
10+ "testing/synctest"
11+)
12+
13+func TestOutputDispatch(t *testing.T) {
14+ synctest.Test(t, func(t *testing.T) {
15+ s := &Server{ids: workspaceid.WithPrefix("test")}
16+ out := make(chan ports.ControlRequest)
17+ for _, wire := range []string{`{"op":"output-add","mode":"1920x1080@60","name":"X"}`, `{"op":"output-rm","name":"X"}`} {
18+ var req request
19+ json.Unmarshal([]byte(wire), &req)
20+ go func() {
21+ r := (<-out).(ports.ControlOutput)
22+ if r.Name != "X" || r.Caps != domain.CapsAll || r.Remove != (req.Op == "output-rm") {
23+ t.Error(r)
24+ }
25+ r.Reply <- ports.ControlReply{}
26+ }()
27+ announced := false
28+ if r := s.dispatch(context.Background(), req, out, &announced); !r.OK {
29+ t.Fatal(r)
30+ }
31+ }
32+ for _, mode := range []string{"bad", "0x2", "2x3@NaN", "2x3@Inf"} {
33+ if _, err := domain.ParseOutputMode(mode); err == nil {
34+ t.Fatal(mode)
35+ }
36+ }
37+ })
38+}
A internal/adapters/control/shot.go +165 -0
@@ -0,0 +1,165 @@
1+package control
2+
3+import (
4+ "bytes"
5+ "context"
6+ "errors"
7+ "fmt"
8+ "image"
9+ "image/png"
10+ "os"
11+ "path/filepath"
12+ "strings"
13+ "sync"
14+
15+ "github.com/bnema/neferwl/internal/domain"
16+ "github.com/bnema/neferwl/internal/ports"
17+ "golang.org/x/sys/unix"
18+)
19+
20+// Shot is a file capture and, when requested, its PNG bytes (JSON base64).
21+type Shot struct {
22+ Output string `json:"output"`
23+ Path string `json:"path"`
24+ Seq uint64 `json:"seq"`
25+ PNG []byte `json:"png,omitempty"`
26+}
27+
28+// Shooter serializes captures and owns their destinations until CaptureDone.
29+// Its done channel must be dedicated to control captures. Cancellation retains
30+// an admitted mapping until a later Shoot reaps its matching completion.
31+type Shooter struct {
32+ requests chan<- domain.CaptureRequest
33+ done <-chan domain.CaptureDone
34+ dir string
35+ token chan struct{}
36+ next uint64
37+ orphans map[uint64][]byte
38+}
39+
40+// NewShooter writes into dir; each shot's pixel size comes from core.
41+func NewShooter(requests chan<- domain.CaptureRequest, done <-chan domain.CaptureDone, dir string) *Shooter {
42+ return &Shooter{requests: requests, done: done, dir: dir, token: make(chan struct{}, 1), orphans: make(map[uint64][]byte)}
43+}
44+
45+// Shoot captures presented scenes to private PNG files. Raw single shots are
46+// unsupported; raw PQ remains available through the every-frame writer.
47+func (s *Shooter) Shoot(ctx context.Context, shots []domain.ShotRequest, inline bool) ([]Shot, error) {
48+ select {
49+ case s.token <- struct{}{}:
50+ defer func() { <-s.token }()
51+ case <-ctx.Done():
52+ return nil, ctx.Err()
53+ }
54+ for _, q := range shots {
55+ if q.Raw {
56+ return nil, errors.New("raw shots need --every-frame")
57+ }
58+ }
59+ if err := os.MkdirAll(s.dir, 0o700); err != nil {
60+ return nil, err
61+ }
62+ var results []Shot
63+ for _, q := range shots {
64+ if err := ctx.Err(); err != nil {
65+ return results, err
66+ }
67+ w, h := q.Width, q.Height
68+ const maxBytes = 512 * 1024 * 1024
69+ if w <= 0 || h <= 0 || w > maxBytes/4 || h > maxBytes/(w*4) {
70+ return results, fmt.Errorf("invalid or unknown shot output %q", q.Output)
71+ }
72+ if q.Output == "" || strings.ContainsAny(q.Output, "/\\") || q.Output == "." || q.Output == ".." {
73+ return results, fmt.Errorf("invalid shot output name %q", q.Output)
74+ }
75+ pixels, err := unix.Mmap(-1, 0, w*h*4, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_PRIVATE|unix.MAP_ANON)
76+ if err != nil {
77+ return results, err
78+ }
79+ s.next++
80+ id := ports.CaptureIDControl | s.next
81+ request := domain.CaptureRequest{ID: id, Output: q.Output, MinSeq: q.MinSeq, Region: image.Rect(0, 0, w, h), Mapped: pixels, Width: w, Height: h, Stride: w * 4, Format: 1}
82+ select {
83+ case s.requests <- request:
84+ case <-ctx.Done():
85+ unix.Munmap(pixels)
86+ return results, ctx.Err()
87+ }
88+ completed := false
89+ for !completed {
90+ select {
91+ case done, open := <-s.done:
92+ if !open {
93+ s.orphans[id] = pixels
94+ return results, errors.New("control capture sink closed before completion")
95+ }
96+ if old, ok := s.orphans[done.ID]; ok {
97+ unix.Munmap(old)
98+ delete(s.orphans, done.ID)
99+ }
100+ if done.ID != id {
101+ continue
102+ }
103+ completed = true
104+ if done.Err != nil {
105+ unix.Munmap(pixels)
106+ return results, fmt.Errorf("capture %s: %w", q.Output, done.Err)
107+ }
108+ case <-ctx.Done():
109+ s.orphans[id] = pixels
110+ return results, ctx.Err()
111+ }
112+ }
113+ if err := ctx.Err(); err != nil {
114+ unix.Munmap(pixels)
115+ return results, err
116+ }
117+ // CaptureFrame.Read writes opaque little-endian XRGB (BGRA bytes):
118+ // swap to RGBA in the private mapping and encode it in place.
119+ for i := 0; i < len(pixels); i += 4 {
120+ pixels[i], pixels[i+2], pixels[i+3] = pixels[i+2], pixels[i], 255
121+ }
122+ img := &image.NRGBA{Pix: pixels, Stride: w * 4, Rect: image.Rect(0, 0, w, h)}
123+ var encoded bytes.Buffer
124+ err = shotPNG.Encode(&encoded, img)
125+ unix.Munmap(pixels)
126+ if err != nil {
127+ return results, err
128+ }
129+ path := filepath.Join(s.dir, fmt.Sprintf("%d-%s.png", q.MinSeq, q.Output))
130+ f, err := os.CreateTemp(s.dir, ".shot-*.png")
131+ if err != nil {
132+ return results, err
133+ }
134+ _, writeErr := f.Write(encoded.Bytes())
135+ closeErr := f.Close()
136+ if err := errors.Join(writeErr, closeErr); err != nil {
137+ os.Remove(f.Name())
138+ return results, err
139+ }
140+ if err := os.Rename(f.Name(), path); err != nil {
141+ os.Remove(f.Name())
142+ return results, err
143+ }
144+ shot := Shot{Output: q.Output, Path: path, Seq: q.MinSeq}
145+ if inline {
146+ shot.PNG = encoded.Bytes()
147+ }
148+ results = append(results, shot)
149+ }
150+ return results, nil
151+}
152+
153+// shotPNG matches the headless frame writer: fast compression, pooled
154+// encoder buffers.
155+var shotPNG = png.Encoder{CompressionLevel: png.BestSpeed, BufferPool: new(pngBuffers)}
156+
157+// pngBuffers is a png.EncoderBufferPool.
158+type pngBuffers struct{ pool sync.Pool }
159+
160+func (p *pngBuffers) Get() *png.EncoderBuffer {
161+ b, _ := p.pool.Get().(*png.EncoderBuffer)
162+ return b
163+}
164+
165+func (p *pngBuffers) Put(b *png.EncoderBuffer) { p.pool.Put(b) }
@@ -0,0 +1,165 @@
1+package control
2+
3+import (
4+ "bytes"
5+ "context"
6+ "errors"
7+ "fmt"
8+ "image"
9+ "image/png"
10+ "os"
11+ "path/filepath"
12+ "strings"
13+ "sync"
14+
15+ "github.com/bnema/neferwl/internal/domain"
16+ "github.com/bnema/neferwl/internal/ports"
17+ "golang.org/x/sys/unix"
18+)
19+
20+// Shot is a file capture and, when requested, its PNG bytes (JSON base64).
21+type Shot struct {
22+ Output string `json:"output"`
23+ Path string `json:"path"`
24+ Seq uint64 `json:"seq"`
25+ PNG []byte `json:"png,omitempty"`
26+}
27+
28+// Shooter serializes captures and owns their destinations until CaptureDone.
29+// Its done channel must be dedicated to control captures. Cancellation retains
30+// an admitted mapping until a later Shoot reaps its matching completion.
31+type Shooter struct {
32+ requests chan<- domain.CaptureRequest
33+ done <-chan domain.CaptureDone
34+ dir string
35+ token chan struct{}
36+ next uint64
37+ orphans map[uint64][]byte
38+}
39+
40+// NewShooter writes into dir; each shot's pixel size comes from core.
41+func NewShooter(requests chan<- domain.CaptureRequest, done <-chan domain.CaptureDone, dir string) *Shooter {
42+ return &Shooter{requests: requests, done: done, dir: dir, token: make(chan struct{}, 1), orphans: make(map[uint64][]byte)}
43+}
44+
45+// Shoot captures presented scenes to private PNG files. Raw single shots are
46+// unsupported; raw PQ remains available through the every-frame writer.
47+func (s *Shooter) Shoot(ctx context.Context, shots []domain.ShotRequest, inline bool) ([]Shot, error) {
48+ select {
49+ case s.token <- struct{}{}:
50+ defer func() { <-s.token }()
51+ case <-ctx.Done():
52+ return nil, ctx.Err()
53+ }
54+ for _, q := range shots {
55+ if q.Raw {
56+ return nil, errors.New("raw shots need --every-frame")
57+ }
58+ }
59+ if err := os.MkdirAll(s.dir, 0o700); err != nil {
60+ return nil, err
61+ }
62+ var results []Shot
63+ for _, q := range shots {
64+ if err := ctx.Err(); err != nil {
65+ return results, err
66+ }
67+ w, h := q.Width, q.Height
68+ const maxBytes = 512 * 1024 * 1024
69+ if w <= 0 || h <= 0 || w > maxBytes/4 || h > maxBytes/(w*4) {
70+ return results, fmt.Errorf("invalid or unknown shot output %q", q.Output)
71+ }
72+ if q.Output == "" || strings.ContainsAny(q.Output, "/\\") || q.Output == "." || q.Output == ".." {
73+ return results, fmt.Errorf("invalid shot output name %q", q.Output)
74+ }
75+ pixels, err := unix.Mmap(-1, 0, w*h*4, unix.PROT_READ|unix.PROT_WRITE, unix.MAP_PRIVATE|unix.MAP_ANON)
76+ if err != nil {
77+ return results, err
78+ }
79+ s.next++
80+ id := ports.CaptureIDControl | s.next
81+ request := domain.CaptureRequest{ID: id, Output: q.Output, MinSeq: q.MinSeq, Region: image.Rect(0, 0, w, h), Mapped: pixels, Width: w, Height: h, Stride: w * 4, Format: 1}
82+ select {
83+ case s.requests <- request:
84+ case <-ctx.Done():
85+ unix.Munmap(pixels)
86+ return results, ctx.Err()
87+ }
88+ completed := false
89+ for !completed {
90+ select {
91+ case done, open := <-s.done:
92+ if !open {
93+ s.orphans[id] = pixels
94+ return results, errors.New("control capture sink closed before completion")
95+ }
96+ if old, ok := s.orphans[done.ID]; ok {
97+ unix.Munmap(old)
98+ delete(s.orphans, done.ID)
99+ }
100+ if done.ID != id {
101+ continue
102+ }
103+ completed = true
104+ if done.Err != nil {
105+ unix.Munmap(pixels)
106+ return results, fmt.Errorf("capture %s: %w", q.Output, done.Err)
107+ }
108+ case <-ctx.Done():
109+ s.orphans[id] = pixels
110+ return results, ctx.Err()
111+ }
112+ }
113+ if err := ctx.Err(); err != nil {
114+ unix.Munmap(pixels)
115+ return results, err
116+ }
117+ // CaptureFrame.Read writes opaque little-endian XRGB (BGRA bytes):
118+ // swap to RGBA in the private mapping and encode it in place.
119+ for i := 0; i < len(pixels); i += 4 {
120+ pixels[i], pixels[i+2], pixels[i+3] = pixels[i+2], pixels[i], 255
121+ }
122+ img := &image.NRGBA{Pix: pixels, Stride: w * 4, Rect: image.Rect(0, 0, w, h)}
123+ var encoded bytes.Buffer
124+ err = shotPNG.Encode(&encoded, img)
125+ unix.Munmap(pixels)
126+ if err != nil {
127+ return results, err
128+ }
129+ path := filepath.Join(s.dir, fmt.Sprintf("%d-%s.png", q.MinSeq, q.Output))
130+ f, err := os.CreateTemp(s.dir, ".shot-*.png")
131+ if err != nil {
132+ return results, err
133+ }
134+ _, writeErr := f.Write(encoded.Bytes())
135+ closeErr := f.Close()
136+ if err := errors.Join(writeErr, closeErr); err != nil {
137+ os.Remove(f.Name())
138+ return results, err
139+ }
140+ if err := os.Rename(f.Name(), path); err != nil {
141+ os.Remove(f.Name())
142+ return results, err
143+ }
144+ shot := Shot{Output: q.Output, Path: path, Seq: q.MinSeq}
145+ if inline {
146+ shot.PNG = encoded.Bytes()
147+ }
148+ results = append(results, shot)
149+ }
150+ return results, nil
151+}
152+
153+// shotPNG matches the headless frame writer: fast compression, pooled
154+// encoder buffers.
155+var shotPNG = png.Encoder{CompressionLevel: png.BestSpeed, BufferPool: new(pngBuffers)}
156+
157+// pngBuffers is a png.EncoderBufferPool.
158+type pngBuffers struct{ pool sync.Pool }
159+
160+func (p *pngBuffers) Get() *png.EncoderBuffer {
161+ b, _ := p.pool.Get().(*png.EncoderBuffer)
162+ return b
163+}
164+
165+func (p *pngBuffers) Put(b *png.EncoderBuffer) { p.pool.Put(b) }
A internal/adapters/control/shot_test.go +104 -0
A internal/adapters/control/shot_wire_test.go +118 -0
A internal/adapters/control/wire_diff.go +23 -0
A internal/adapters/control/wire_diff_test.go +26 -0
M internal/adapters/drm/frame_lifecycle.go +1 -0
M internal/adapters/drm/frame_submit.go +2 -2
M internal/adapters/drm/frames_test.go +5 -5
M internal/adapters/drm/output.go +4 -2
M internal/adapters/headless/capture_test.go +37 -0
A internal/adapters/headless/continuous_test.go +83 -0
M internal/adapters/headless/frames_test.go +72 -8
M internal/adapters/headless/output.go +169 -83
D internal/adapters/headlessinput/identity.go +0 -48
D internal/adapters/headlessinput/input.go +0 -476
D internal/adapters/headlessinput/input_test.go +0 -431
D internal/adapters/headlessinput/security_test.go +0 -287
D internal/adapters/headlessinput/swipe.go +0 -35
M internal/adapters/logging/logging.go +116 -11
M internal/adapters/logging/logging_test.go +74 -0
M internal/adapters/outputkit/capture/fence.go +2 -2
M internal/adapters/outputkit/capture/offscreen.go +1 -1
M internal/adapters/outputkit/capture/pipeline.go +23 -9
M internal/adapters/outputkit/capture/pipeline_cursor_test.go +3 -1
M internal/adapters/outputkit/capture/pipeline_pq_test.go +3 -1
A internal/adapters/outputkit/capture/pixels.go +46 -0
A internal/adapters/outputkit/capture/pixels_test.go +81 -0
M internal/adapters/outputkit/capture/requests.go +1 -1
M internal/adapters/outputkit/corewake/corewake.go +6 -4
M internal/adapters/outputkit/corewake/corewake_test.go +6 -6
M internal/adapters/outputkit/headlessbackend/backend.go +113 -16
M internal/adapters/outputkit/headlessbackend/backend_test.go +57 -0
M internal/adapters/outputkit/routing/captured.go +14 -8
M internal/adapters/outputkit/routing/captured_test.go +38 -3
M internal/adapters/outputkit/routing/outputrouting.go +2 -0
M internal/adapters/outputkit/virtuals/virtuals.go +16 -22
M internal/adapters/outputkit/virtuals/virtuals_test.go +0 -18
A internal/adapters/sessiondir/sessiondir.go +224 -0
A internal/adapters/sessiondir/sessiondir_test.go +118 -0
M internal/adapters/statefile/statefile.go +13 -163
M internal/adapters/statefile/statefile_test.go +6 -147
A internal/adapters/statewire/statewire.go +159 -0
A internal/adapters/statewire/statewire_test.go +150 -0
M internal/adapters/vulkan/renderer.go +1 -1
M internal/adapters/vulkan/targets_test.go +1 -1
A internal/adapters/wayland/configure_commit_test.go +154 -0
M internal/adapters/wayland/input_region_test.go +1 -1
M internal/adapters/wayland/layer.go +1 -1
M internal/adapters/wayland/popup.go +1 -1
M internal/adapters/wayland/session_lock_surface.go +1 -1
M internal/adapters/wayland/xdg.go +47 -7
M internal/app/app.go +36 -22
M internal/app/app_test.go +94 -18
M internal/app/colorcheck_test.go +32 -18
A internal/app/control_client_test.go +142 -0
A internal/app/control_keymaps_test.go +39 -0
A internal/app/control_test.go +177 -0
M internal/app/hintoptin_test.go +19 -3
M internal/app/outputapply_e2e_test.go +2 -2
M internal/app/pointercli_test.go +1 -1
M internal/app/screencast_test.go +18 -8
M internal/app/server_test.go +8 -6
M internal/app/session.go +148 -45
M internal/app/session_lock_test.go +20 -12
M internal/app/textinput_test.go +2 -2
M internal/app/wayvnc_test.go +1 -1
M internal/app/wiring.go +60 -37
M internal/app/xwayland_fullscreen_group_test.go +15 -11
M internal/app/xwayland_keepfocus_test.go +1 -2
M internal/app/xwayland_lineage_test.go +11 -11
M internal/app/xwayland_test.go +75 -39
M internal/cli/cli.go +21 -1
M internal/cli/cli_test.go +13 -66
M internal/cli/commands.go +15 -4
A internal/cli/control.go +179 -0
A internal/cli/control_test.go +210 -0
A internal/cli/inject.go +177 -0
A internal/cli/inject_test.go +20 -0
A internal/cli/main_test.go +25 -0
A internal/cli/output.go +33 -0
A internal/cli/output_test.go +50 -0
A internal/cli/profile_test.go +52 -0
M internal/cli/run.go +101 -69
A internal/cli/session.go +81 -0
A internal/cli/session_new.go +163 -0
A internal/cli/session_new_test.go +64 -0
A internal/cli/session_rm.go +132 -0
A internal/cli/session_rm_test.go +94 -0
A internal/cli/session_test.go +60 -0
A internal/cli/shot.go +60 -0
A internal/cli/shot_test.go +105 -0
A internal/cli/target.go +54 -0
A internal/cli/target_test.go +80 -0
M internal/core/backendplan.go +54 -25
M internal/core/backendplan_test.go +57 -14
A internal/core/catalog_test.go +47 -0
M internal/core/client.go +8 -0
A internal/core/configure_commit_internal_test.go +72 -0
A internal/core/configure_resend_test.go +87 -0
M internal/core/configures.go +40 -5
A internal/core/control.go +163 -0
A internal/core/control_test.go +106 -0
A internal/core/controlcapture.go +68 -0
A internal/core/controlcapture_test.go +89 -0
A internal/core/controlinject_test.go +157 -0
A internal/core/controlinput.go +27 -0
A internal/core/controloutput.go +37 -0
A internal/core/controloutput_test.go +56 -0
A internal/core/controlshots_test.go +105 -0
A internal/core/controlwait.go +283 -0
A internal/core/controlwait_test.go +324 -0
M internal/core/core.go +53 -31
M internal/core/core_test.go +9 -6
M internal/core/datadrag.go +2 -0
M internal/core/outputapply.go +10 -4
M internal/core/outputoverrides.go +2 -1
A internal/core/presented_internal_test.go +47 -0
A internal/core/runtimecode.go +21 -0
A internal/core/runtimecode_test.go +22 -0
M internal/core/scene.go +1 -0
M internal/core/screens.go +1 -0
A internal/core/virtualruntime.go +92 -0
A internal/core/virtualruntime_test.go +73 -0
A internal/core/workspace/actions_test.go +46 -0
M internal/core/workspace/workspace_actions.go +33 -0
M internal/domain/backend.go +2 -3
A internal/domain/backend_profile.go +34 -0
A internal/domain/backend_profile_test.go +20 -0
M internal/domain/backend_test.go +2 -2
M internal/domain/bind_events.go +1 -0
M internal/domain/capture_messages.go +3 -0
A internal/domain/command.go +334 -0
A internal/domain/command_test.go +178 -0
M internal/domain/output_events.go +6 -4
A internal/domain/output_mode.go +45 -0
A internal/domain/output_mode_test.go +33 -0
M internal/ports/capture_messages.go +4 -0
M internal/ports/client_commands.go +2 -0
M internal/ports/client_events.go +11 -0
A internal/ports/continuous_capture.go +40 -0
A internal/ports/control.go +106 -0
A internal/ports/output_runtime.go +27 -0
M packaging/neferwl-server.service +1 -1
A skills/neferwl/CLI.md +168 -0
A skills/neferwl/PROTOCOL.md +50 -0
A skills/neferwl/SKILL.md +129 -0
M tools/demo/record.sh +15 -16

Comments11 unresolved

  1. bnema outdated

    Follow-up after a performance review and a maintainability/architecture review (22 commits, d2820f6):

    • Fix: configures are recorded only after a successful send (a security change mid-publish lost the configure and stalled settled waits).
    • Perf: no per-configure allocation in xdg/layer/lock serial tracking; WindowCommitted skips the lineage scan; --until evaluates on a reused snapshot; shots encode in place from the mapping (no 8 MB copy, pooled BestSpeed encoder).
    • Arch: continuous capture is decided in core (ports.ControlCapture: caps, protection, outputs, dir); core computes shot sizes (app map and mutex removed); runtime-output codes decided in core; BackendPlan.Control; single domain.ParseOutputMode; shared timeout constants and timeout error code; one diff wire shape; control()/evalWaits split.
    • Cleanup: dead headless shot options removed, log.debug validated through logging, catalog test without source parsing, xwayland fixture watches the session state directory (fixes the xwayland flakes).
    • Behaviour: shot default timeout is 10s like other verbs; output add no longer caps refresh at 1000 Hz.

    Checks: make check, race, mocks-check, staticcheck (incl. xwayland,colorcheck tags), arch; xwayland suite 3× green; colorcheck green. Remote headless e2e 49/49, systemd server unit with every-frame capture, local lock refusal (inject, shot, do, every-frame → locked).

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
l
merge request: the list of files (j k move, enter opens, esc back)
M
merge request: the merge menu; there 1–3 pick the mode, D deletes the branch, enter merges
R
merge request: mark the head read
esc
close a dialog, leave a field

Branches 33

Tags 15

↑↓ moveenter openesc close