dsh-geoserver

Read GeoServer WMS services and render map images inside the dsh web GUI.

• 4 tools for the agent: list workspaces/layers/styles, publish GeoTIFF/SHP ZIP data, fetch map images, and diagnose connectivity.
• A settings card in the GUI (Settings → Plugins → Plugin configuration) to configure the connection, publication limits, and business webhook without editing files.
• Credentials never reach the browser: the plugin holds Basic auth on the host, fetches images itself, and serves them from the same origin as the GUI through ctx.webServer.

Tools

| Tool | Purpose | |---|---| | geoserver_list | Enumerate workspaces, layers (title/bbox/SRS/styles) and image formats via the GeoServer REST API, falling back to the WMS GetCapabilities document. | | geoserver_publish | Upload one local GeoTIFF or one ZIP containing a single SHP dataset. Optionally notify a configured business-system webhook after GeoServer verifies the layer. | | geoserver_map | Fetch one WMS GetMap image server-side and return an in-origin display URL (/geoserver-image/<token>). The agent replies with the rendered markdown image. | | geoserver_probe | Connectivity/authentication diagnostics: reachability, auth state, WMS title, and a small render test. |

Installation

Install the package into the Web profile; the command appends dsh-geoserver to that profile's dsh.profile.bundles list automatically:

dsh plugin --profile web add dsh-geoserver

For a local checkout, pass its path instead of the package name. The bundle's cordis.patch.yml inserts the geoserver plugin row:

# profile cordis.yml patch layer — e.g. ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: geoserver
      name: dsh-geoserver

Restart dsh web. A missing server URL does not prevent Harness from starting, so a first-time user can open the settings card. GeoServer tools report a configuration error until a URL is saved. The plugin is configurable in two ways:

1. Settings UI — Settings → Plugins → Plugin configuration → GeoServer: configure the server URL, credentials, publication directories/size limit, and optional webhook, then Save. Changes take effect immediately, without a restart. Publication directories are entered one per line. The webhook token field stores only an environment-variable name, never the token itself.
2. Environment credentials — configure env (see below) to read GEOSERVER_USER / GEOSERVER_PASS from the process environment.

Configuration

| Key | Default | Meaning | |---|---|---| | baseUrl | '' | GeoServer base URL, e.g. http://host:8080/geoserver. An empty value permits first boot; tool calls reject it with setup instructions. | | env | [] | Environment-variable names for credentials. The first name matching /user/i is the username, the first matching /pass\|pwd\|token/i the password. Direct username/password fields take precedence. | | username / password | — | Direct Basic-auth credentials (alternative to env). The settings card stores the username in settings and the password in the credentials domain, not in settings.yaml. | | cacheTtlMs | 600000 | Image cache TTL. | | cacheMaxEntries | 50 | Max cached images before eviction. | | publicBaseUrl | http://127.0.0.1:<webServer.port> | Externally reachable GUI URL for LAN access; the display URL prefix. | | connectTimeoutMs | 15000 | Per-request HTTP timeout. | | publishRoots | [] | Local directories from which geoserver_publish may read files. An empty list disables publication. Editable in the settings card. | | defaultWorkspace | '' | Workspace used when geoserver_publish omits workspace. A request-level workspace overrides it. Editable in the settings card. | | publishMaxBytes | 536870912 | Maximum TIF or ZIP upload size in bytes. Editable in the settings card. | | webhookUrl | — | Optional business-system endpoint called after publication succeeds. Editable in the settings card. | | webhookTokenEnv | — | Optional environment variable containing the webhook Bearer token. The settings card stores the variable name only. | | webhookTimeoutMs | 5000 | Business webhook timeout. Editable in the settings card. |

Example with credentials from $DSH_HOME/.env (GEOSERVER_USER, GEOSERVER_PASS):

- insert:
    - id: geoserver
      name: dsh-geoserver
      config:
        baseUrl: http://host:8080/geoserver
        env: [GEOSERVER_USER, GEOSERVER_PASS]
        publishRoots: [D:/data]
        defaultWorkspace: demo
        webhookUrl: https://business.example.com/api/geoserver/published
        webhookTokenEnv: GEOSERVER_WEBHOOK_TOKEN

geoserver_publish accepts kind: raster for .tif/.tiff and kind: vector for a .zip containing one same-named SHP dataset. workspace is optional when defaultWorkspace is configured; an explicit request value overrides the default. Existing layers are rejected rather than replaced. Optional flat metadata fields such as projectId and datasetId are returned by the tool and forwarded to the webhook.

GeoServer publication and webhook delivery have separate statuses. A failed webhook does not turn an already-created GeoServer layer into a failed publication; this first version reports the delivery failure and does not retry automatically.

Example tool arguments:

{
  "kind": "raster",
  "sourcePath": "D:/data/dem.tif",
  "workspace": "demo",
  "metadata": {
    "projectId": "project-123",
    "datasetId": "dataset-456"
  }
}

After GeoServer verifies demo:dem, the webhook receives an event with type: "geoserver.layer.published" and version: 1, containing a unique eventId, the workspace/layer/store, WMS and WCS/WFS URLs, discovered SRS/bounds, and the same metadata. Any HTTP 2xx response counts as delivered. When webhookTokenEnv is configured, the request carries Authorization: Bearer <value>; a missing environment value reports a failed notification without sending an unauthenticated request.

Local webhook receiver

Run pnpm webhook:receiver to start the bundled test receiver at http://127.0.0.1:3900. Set the settings-card webhook URL to http://127.0.0.1:3900/geoserver/published and leave the token environment-variable field blank. Received events are printed to the terminal and available from GET http://127.0.0.1:3900/events; GET /health reports readiness. Set GEOSERVER_WEBHOOK_TEST_TOKEN before starting the receiver to require a Bearer token.

Development

pnpm install      # dev dependencies: typescript, tsdown, lightningcss
pnpm build        # tsc (host) + type-check (client) + tsdown (client bundle)
pnpm test         # node --test against lib/

Model Experience

• geoserver_list costs 2 REST calls plus one per layer (skippable with skipDetails), or one GetCapabilities round-trip on fallback.
• geoserver_map adds one GetMap round-trip and one small in-memory image per request; the image lives in the bounded TTL cache.
• geoserver_publish performs workspace/layer checks, one file upload, and one verification request. The source must resolve inside publishRoots and fit publishMaxBytes.
• Credentials resolve per tool call from the settings section (or the composition entry); the settings card's password is written through the credentials domain, never into the settings document or any response.

Known Limitations and Deferred Work

• The GetCapabilities fallback parses layer names/titles/styles only; CRS and bounds come from the REST path.
• Images are cached in host memory; very large raster requests are bounded by the tool's width/height clamp (4096 px) and HTTP timeout.
• WFS/WMTS service listing is not yet exposed; the REST enumeration covers WMS layers and styles.
• The settings card reads and writes through the plugin's own /geoserver/config route, so it renders on any host without the geoserver settings namespace being allowlisted in the api-proxy. The password always travels through the credentials domain, never through a response.