M3.1: PHP detection and pinned Phpactor download
- crates/lsp toolchain: PHP from php.executable or PATH, `php -v` with a 5 s timeout and capped output, version parsing (proptest), PHP >= 8.2. - Pinned Phpactor 2026.06.25.0 (SHA-256 832510fe...59e9); newer releases need ext-posix and do not start on Windows. - Download with ureq + rustls (ring, OS roots via rustls-native-certs): HTTPS only, 32 MiB cap, SHA-256 verified before an atomic write, retry with backoff. Tests use a local HTTP server only. - Engine: settings php.executable, phpactor.path, phpactor.autoDownload (bool and string setting kinds), toolchain.status, toolchain.downloadPhpactor, toolchainChanged, notifications; worker thread off the engine lock, results via the pump. Downloads only after the host calls Engine::allow_downloads (the desktop does). - Docs: architecture Toolchain section (network access, D15), G6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
78709dd76b
commit
50f36cce8b
23 changed files with 2577 additions and 10 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Architecture
|
||||
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library · **Last updated:** 2026-10-18
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download) · **Last updated:** 2026-10-18
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -291,7 +291,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
### LSP client (M3.2)
|
||||
|
||||
- `crates/lsp` (L3, depends on `lutra-text` and `serde_json` only) is a library; the engine wiring is M3.3. `Server::spawn(command, args, root, ServerOptions)` starts the process in `root` with piped stdio (on Windows with `CREATE_NO_WINDOW`) and returns at once with the server and a bounded `Receiver<ServerEvent>` (capacity 4096; overflow drops and counts, `dropped_events()`). A spawn error (missing executable, relative root) is returned synchronously.
|
||||
- `crates/lsp` (L3; the client depends on `lutra-text` and `serde_json` only, the toolchain module of M3.1 adds `lutra-vfs`, `ureq`, `rustls`, `ring` and `rustls-native-certs`) is a library; the engine wiring is M3.3. `Server::spawn(command, args, root, ServerOptions)` starts the process in `root` with piped stdio (on Windows with `CREATE_NO_WINDOW`) and returns at once with the server and a bounded `Receiver<ServerEvent>` (capacity 4096; overflow drops and counts, `dropped_events()`). A spawn error (missing executable, relative root) is returned synchronously.
|
||||
- Threads, no async runtime: per process a writer (the only one touching stdin, fed by a channel), a reader (frames from stdout), a stderr drain; per server a supervisor that watches the process, expires timeouts every 20 ms, restarts and shuts down. A server is a few blocking pipes and the engine pump is synchronous, so threads with channels are simpler than pulling an executor into L3. All writes happen under the client's one mutex, so messages leave in the order the state changed; callbacks always run outside it (a panicking callback is caught).
|
||||
- Framing (`jsonrpc`): `Content-Length` headers (case-insensitive, other headers ignored, header lines capped at 1 KiB and 16 per frame), bodies capped at 32 MiB (`MAX_MESSAGE_BYTES`; an oversized body is read and discarded without buffering). A malformed header block, invalid JSON or a message that is neither request, response nor notification becomes `ServerEvent::ProtocolError(reason)` (the log line) and the reader carries on with the next frame. serde_json's recursion limit bounds nesting. Proptests: message round trips, random bytes, header-like noise, recovery after bad frames, random JSON bodies.
|
||||
- Initialize: `initialize` (processId, clientInfo, rootUri/rootPath, one workspace folder, `initializationOptions` from the options) with the capabilities of `client_capabilities()`: incremental sync with `didSave`, completion (no snippets, markdown/plain documentation, context), hover, signatureHelp, definition (links), references, rename with prepare, `publishDiagnostics` with versions, `workspace/configuration`, workspace folders, work-done progress, `positionEncodings: ["utf-16"]`; no dynamic registration and no `applyEdit`. Then `initialized`, every open document is (re)opened, queued requests are sent, and the status becomes `Ready`. A server choosing another encoding is logged. `initialize` times out after 30 s; a failed or late `initialize` counts as a crash.
|
||||
|
|
@ -303,6 +303,19 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- URIs (`uri`): `path_to_uri` percent-encodes everything except unreserved characters, `/` and a drive colon (`file:///C:/a%20b.php`, UNC as `file://host/share`); `uri_to_path` accepts escapes in any case, an encoded drive colon and `localhost`, and upper-cases the drive letter; bad escapes, NUL and other schemes give `None`.
|
||||
- Tests: the fake server `src/bin/lutra-lsp-fake.rs` (a test fixture, started via `CARGO_BIN_EXE_lutra-lsp-fake`) covers initialize, server requests, log and stderr, typed requests and errors, queueing before ready, timeout and cancel with `$/cancelRequest`, incremental and full sync (the fake applies the changes and publishes the text as a diagnostic), malformed output, crash, restart and reopen, initialize errors, giving up with the backoff sequence, shutdown and spawn errors (13 tests, about 0.5 s). `real_phpactor` is ignored and runs with `LUTRA_PHPACTOR` (path to `phpactor.phar`, `LUTRA_PHP` for PHP); it was not run in M3.2 (no Phpactor on the dev machine yet; M3.1 downloads it).
|
||||
|
||||
### Toolchain (M3.1)
|
||||
|
||||
- **Owner decision D15:** Lutra downloads the Phpactor PHAR itself; PHP is the user's (found through `php.executable` or `PATH`). Library code lives in `crates/lsp/src/toolchain/` (L3), the engine side in `crates/engine/src/cmd/toolchain.rs`.
|
||||
- **Network access:** downloading the pinned Phpactor is the only network access in Lutra. It is minimal (one GET of one URL, following at most 5 redirects, HTTPS only, also on redirects), visible (a notification when it starts, ends or fails) and verifiable (pinned version, URL and SHA-256 as constants in `lutra_lsp::toolchain::phpactor`; the body is checked before it is written). `phpactor.autoDownload: false` turns the automatic download off, `phpactor.path` replaces the managed PHAR. An engine downloads nothing until the host calls `Engine::allow_downloads()`; the desktop does, tests never do, so no test reaches the network (download tests use a local HTTP server on 127.0.0.1).
|
||||
- **Pin:** phpactor `2026.06.25.0`, SHA-256 `832510fe4cdaf27ba056b8cb66a779d18352585c74fdaac54e45a37b589559e9` (4,474,352 bytes, equal to GitHub's published asset digest). The newer releases (from 2026.06.23.0 on, latest 2026.10.07.0) require `ext-posix`, which PHP on Windows does not have; they refuse to start there. The pin needs PHP ≥ 8.2 (`"php": "^8.2"`), not 8.1 as first planned, so `php::MIN_VERSION` is 8.2.0. Updating the pin means changing version, URL, hash and size together after checking the PHAR on all three platforms.
|
||||
- **HTTP client:** `ureq` 3 with `rustls` (the `ring` provider) and the operating system's trusted roots loaded with `rustls-native-certs` (Windows store, macOS keychain, Linux files or `SSL_CERT_FILE`). `rustls-platform-verifier` and ureq's default `webpki-roots` were rejected: both pull a CDLA-Permissive-2.0 crate (`webpki-root-certs` / `webpki-roots`), outside the licence allow list. Proxies come from `HTTPS_PROXY`/`ALL_PROXY`/`NO_PROXY`. Timeouts: 15 s connect, 300 s per attempt.
|
||||
- **Download:** `download::install` reads the body into memory with a cap of 32 MiB (Content-Length checked first, then the bytes read), compares its SHA-256 with the pin and only then writes `<data_dir>/tools/phpactor/<version>/phpactor.phar` with `lutra_vfs::write_atomic`. A mismatch discards the body and leaves an existing file untouched; nothing unverified ever lies at the target path. `install_with_retry` retries network errors, 5xx, 408 and 429 up to 4 attempts with 2 s, 4 s, 8 s backoff; a mismatch, an oversized body and other client errors are final. A managed PHAR that no longer matches its hash counts as missing and is downloaded again.
|
||||
- **PHP detection:** `php::detect` resolves the setting (a path, or a bare name looked up in `PATH`; empty means `php`, on Windows `php.exe`, `php.bat`, `php.cmd`), runs `php -v` without a console window, with a 5 s timeout (killed after it) and at most 64 KiB of output read, and parses the first line starting with `PHP <major>.<minor>[.<patch>]` (suffixes such as `-dev` or `-1ubuntu1` are ignored; property-tested with random bytes).
|
||||
- **Engine:** settings `php.executable` (string, default `""`), `phpactor.path` (string, default `""`) and `phpactor.autoDownload` (bool, default `true`), section `php`; `settings.list` now has the types `bool` and `string` (the settings dialog shows bool switches; a text control for string settings is a UI follow-up). One worker thread (`lutra-toolchain`) runs checks and the download; commands and the pump only queue jobs (merged while it works, the strongest mode wins), and its reports reach the state through `Engine::pump_vfs` (`cmd::toolchain::pump`), like search results. Jobs start with the first `toolchain.status`, when a project opens (a download if the project has PHP files: a root `composer.json` or a `.php`/`.phtml`/`.inc` file within 6 levels, at most 20,000 entries, skipping `vendor`, `node_modules`, hidden and cache directories; PHP is usable; Phpactor is missing; auto-download is on), when one of the three settings changes after the first check, and with `toolchain.downloadPhpactor` (also with auto-download off; `failed` if the host allows no downloads).
|
||||
- **Commands and event:** `toolchain.status` → `{php: {found, path, version, error?}, phpactor: {state: missing|downloading|ready|failed|disabled, path?, version?, error?}}` as last checked (the first call starts a check); `toolchain.downloadPhpactor` → `{started}`; event `toolchainChanged` with the same shape whenever it changes. A `phpactor.path` PHAR is ready if it is a file, with no version and no hash check (the user chose it).
|
||||
- **Notifications:** `notification.toolchain.phpMissing {reason, min}` (warning, when the PHP result changes to unusable), `notification.toolchain.downloadStarted {version}` and `notification.toolchain.downloadDone {version, seconds}` (info), `notification.toolchain.downloadFailed {version, reason}` (error).
|
||||
- **Live check** (debug build, bundled UI, port 7931, Windows 11, PHP 8.4.24 from WinGet, a temp project with one PHP file, empty data directory): `project.open` → PHP found after 0.15 s, `downloadStarted` after 0.35 s, the real download from GitHub plus SHA-256 check took 2.8 s (notification to notification, measured), `toolchain.status` then `ready` with `<data_dir>/tools/phpactor/2026.06.25.0/phpactor.phar`, whose hash on disk equals the pin. A second run through `toolchain.downloadPhpactor` after deleting the PHAR took 0.3 s; both toasts showed in the window.
|
||||
|
||||
## Decisions (M0)
|
||||
|
||||
| Question | Decision | Why |
|
||||
|
|
@ -320,6 +333,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-18 | minor | M3.1: toolchain (PHP detection, pinned Phpactor download with SHA-256 check, network access note, D15), `toolchain.status`/`toolchain.downloadPhpactor`, `toolchainChanged`, bool and string settings |
|
||||
| 2026-10-18 | minor | M3.2: LSP client library (`crates/lsp`: framing, supervision and restart, initialize, requests with timeout and cancel, server requests, document sync, fake server tests) |
|
||||
| 2026-10-17 | minor | M3.7: `lutra` CLI, single instance, rendezvous file and token listener, `app.auth`/`app.focus`, CLI to L6 |
|
||||
| 2026-10-17 | minor | M2.6: go-to popup (store, debounce and stale drop, modes, `editor.reveal`), `library` on `goto.file` items |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue