lunartrace.workbench.server

Local Workbench sidecar: the browser’s seam to Python scientific authority.

Binds 127.0.0.1 only. Every number it returns comes from the qualified Python method; the browser computes, thresholds and snaps nothing. Requests from a non-local Origin or for a non-local Host (DNS rebinding) are refused.

Routes (all JSON unless noted): GET /health, GET /site, GET /cell, POST /roi/evaluate, POST /figure (returns SVG, PNG or PDF bytes), GET /presets and POST /lab/open. Handlers run blocking Site work in a worker thread.

Notes

Application errors that the Python layer raises as RoiError, MethodInputError, KeyError or ValueError are returned as HTTP 422; an unknown grid cell is HTTP 404; a body over MAX_BODY_BYTES is HTTP 413; a Lab that cannot start is HTTP 503.

`LOCAL_HOSTS`

attribute

LOCAL_HOSTS

Host names accepted in the Origin and Host headers, on any port.

`MAX_BODY_BYTES`

attribute

MAX_BODY_BYTES

Largest accepted request body; a ring of MAX_RING_VERTICES vertices fits well inside.

`MAX_TAUS`

attribute

MAX_TAUS

Largest accepted number of inclusion thresholds per request.

`Handler`

attribute

Handler

Starlette request handler: an async callable returning a starlette.responses.Response.

`Config`

class

Config

Runtime configuration of one Workbench sidecar process.

Parameters

Name	Type	Description
`manifest`	`pathlib.Path`	Path to the Site source manifest (a `*.manifest.json` under `research/sources`).
`store`	`pathlib.Path`	Root of the content-addressed source store in which the manifest inputs are resolved.
`lab_dir`	`pathlib.Path`	Directory for generated Lab notebooks, served by a `marimo edit` process.
`lab_port`	`int`	TCP port on 127.0.0.1 for the Lab `marimo edit` process.
`lab_enabled`	`bool`	`False` for a hosted sidecar: `POST /lab/open` then answers HTTP 503 and no `marimo edit` process (an arbitrary-code editor) is ever started. Default `True`.

Notes

The Lab process is created here but is only started on the first POST /lab/open.

`Config.site`

def site(self) -> wroi.Site

Load the frozen Site for this configuration.

Returns

lunartrace.workbench.roi.Site — The verified Site, served from the per-process cache of lunartrace.workbench.roi.load_site.

Notes

Errors raised while loading (missing inputs, digest mismatches) propagate unchanged. Concurrent first requests wait on one load instead of each verifying the CAS inputs.

`guarded`

function

def guarded(fn: Handler) -> Handler

Wrap a route handler with the local-Origin guard and the error mapping.

Parameters

Name	Type	Description
`fn`	`Handler`	The async route handler to protect.

Returns

Handler — A handler that first checks the Origin header, then calls fn.

Notes

A request without an Origin header is treated as local. A non-local Origin, or a Host header naming a non-local host (a DNS-rebinding page), is answered with HTTP 403. A body over MAX_BODY_BYTES is answered with HTTP 413. RoiError, MethodInputError, KeyError and ValueError raised by fn are answered with HTTP 422 and their message as the error field; a Lab that cannot start (lunartrace.workbench.lab.LabUnavailable) with HTTP 503. Other exceptions are not caught here.

`RoiShapeError`

class

RoiShapeError

An evaluated result lacked the roi object the figure route requires (HTTP 500).

`build_app`

function

def build_app(config: Config) -> Starlette

Build the Starlette application for one sidecar configuration.

Parameters

Name	Type	Description
`config`	`Config`	The process configuration; its Site and Lab server are shared by all routes.

Returns

starlette.applications.Starlette — The ASGI application with the routes /health, /site, /cell, /roi/evaluate, /figure, /presets and /lab/open.

Notes

The Lab marimo edit process is stopped by the application lifespan on shutdown.

`main`

function

def main(argv: Sequence[str] | None = None) -> int

Command-line entry point: run the sidecar, or check that the Site loads.

Parameters

Name	Type	Description
`argv`	`sequence of str`	Command-line arguments without the program name; `None` reads `sys.argv`. Default `None`.

Returns

int — 0 on success. With --check the Site provenance is printed as sorted JSON and the function returns without starting the server.

Raises

SystemExit — Raised by argparse for invalid arguments.

Notes

The server binds --host (default 127.0.0.1) on --port (default 4318). Bind another address only inside an isolated container whose sole client is a trusted proxy: the Origin and Host guard still accepts local names only. The Lab process uses --lab-port (default 4319); --no-lab disables it. The default manifest and source store comes from --store or the LUNARTRACE_SOURCE_STORE environment variable; there is no built-in host default and the store is not verified here.