Skip to content

feat(plugins): session process plugins stay running and hear the map - #1553

Merged
Mavrick-F merged 6 commits into
opengeos:mainfrom
Mavrick-F:feat/session-plugins
Nov 9, 2026
Merged

Mavrick-F merged 6 commits into
opengeos:mainfrom
Mavrick-F:feat/session-plugins

Conversation

@Mavrick-F

@Mavrick-F Mavrick-F commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds session process plugins, as proposed in #1518: a process plugin with "session": true keeps one program running between its commands, so it can ask RustGIS for things at any time and hear when the map changes. A view of the map in a window of its own, such as RustPlanetX's 3D globe, can then stay linked to the map without the MCP relay. The relay is for agents the user turns on; a plugin never starts it.

The protocol, also in docs/plugins.md › Session plugins:

  • RustGIS starts the program the first time one of the plugin's commands runs, and writes {"session": {"abi", "plugin", "rustgis", "lang"}}.
  • Commands come as {"command": request, "id": n} and are answered {"ok"|"error", "id": n}.
  • The program sends host requests at any time, {"call": {...}, "id": "any"}; the answer carries the id back. They go through the same checks as a command's, within the plugin's permissions. Between commands, an edit is an undo step of its own named after the plugin, and host.fetch is refused, because it would make the app wait. The program can fetch for itself.
  • The desktop app sends {"event": "view", "view": {...}}, {"event": "layers"} (added, removed, reordered, renamed, shown or hidden, restyled, transparency, fields, features, web tile layers), {"event": "selection"} and {"event": "project"} (another project opened) when they change.
  • The channel is the program's own input and output: no port, no token file, nothing another program can join.
  • RustGIS stops the program, with what it started, when the plugin is turned off, removed or updated and when the app closes. The program's input closing (RustGIS gone, however it ended) is its sign to exit. A program that exits by itself is started again by the next command. On Linux and macOS what it left running is stopped too.

Left out on purpose:

  • A Windows job object, which would stop a globe even if the program detached from it. It needs windows-sys as a direct dependency, so it can follow separately. Until then, a Windows program must stop what it starts.
  • Tools still start the program once per run.
  • rustgis-cli and the Python package answer between-command requests only while a command runs, and send no events.

What RustPlanetX needs, from the list on #1518:

  • Works with this PR.
    • The view, layers, selection and project events replace polling.
    • host.features already answers GeoJSON in WGS 84, so no temporary file is needed.
    • The calls (map.goToXY, select.rows, layer.visibility, layer.transparency, group.add, layer.addDataText) are commands, run within edit. Two of them need more than edit: map.setTiles needs network and layer.addData needs files, the same rules as for any plugin.
  • A follow-up PR, since each is a new or wider host request:
    • host.layers with each layer's extent, opacity, group and kind, the web tile layers and the project.
    • A layer's symbology as a MapLibre style without writing a file.
    • A host request that renders one z/x/y tile of a raster layer in its RustGIS look.

This adds to the plugin interface (a manifest key, gated by minRustgisVersion), so per CONTRIBUTING it waits for a second maintainer's go-ahead before landing.

Testing

  • cargo xtask ci, the wasm32-unknown-unknown build of rustgis-web, and pre-commit run --all-files.
  • New tests run the test binary as a session program:
    • session_plugins_keep_one_program_running: the same program answers several commands; requests between commands; events; stop and restart; tools still per run.
    • session_plugins_that_end_or_fail_are_started_again: a quiet exit; a program it left running is stopped (fails without the fix); a crash names its last error; a hang is stopped; update and disable stop it.
    • session_plugins_ask_between_commands_and_hear_the_map (engine): reads leave no undo step; an edit is its own step; permission refusals and the host.fetch refusal go back to the program; layers, view and selection events.
  • process_manifests_are_checked: session only for process plugins.

UI evidence

No visible UI change.

Related issue

Part of #1518.

Summary by CodeRabbit

  • New Features
    • Process plugins can stay running between commands, retain state, and receive map, layer, selection, and project change events on desktop.
    • Session plugins can make host requests between commands. Read-only requests avoid undo steps; permitted edits are undoable. host.fetch is unavailable between commands.
    • Map view information now includes camera bearing and pitch.
    • Sessions stop when a plugin is disabled, replaced, or unloaded, or when the app or CLI closes. They can restart when the plugin runs again.
    • Session log entries can include plugin attribution in JSON Lines and CSV exports; entries without attribution omit it from JSON Lines and show an empty CSV cell.
  • Documentation
    • Added guidance on session-plugin setup, permissions, events, compatibility, and log attribution.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:macos Run the macOS CI jobs on this pull request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants